README.rdoc in tiny_tds-0.3.2 vs README.rdoc in tiny_tds-0.4.0

- old
+ new

@@ -1,33 +1,38 @@ -= TinyTds - A modern, simple and fast FreeTDS library for Ruby using DB-Library. += TinyTDS - A modern, simple and fast FreeTDS library for Ruby using DB-Library. -The TinyTds gem is meant to serve the extremely common use-case of connecting, querying and iterating over results to Microsoft SQL Server databases from ruby. Even though it uses FreeTDS's DB-Library, it is NOT meant to serve as direct 1:1 mapping of that complex C API. +The TinyTDS gem is meant to serve the extremely common use-case of connecting, querying and iterating over results to Microsoft SQL Server databases from ruby. Even though it uses FreeTDS's DB-Library, it is NOT meant to serve as direct 1:1 mapping of that complex C API. -The benefits are speed, automatic casting to ruby primitives, and proper encoding support. It converts all SQL Server datatypes to native ruby objects supporting :utc or :local time zones for time-like types. To date it is the only ruby client library that allows client encoding options, defaulting to UTF-8, while connecting to SQL Server. It also properly encodes all string and binary data. The motivation for TinyTds is to become the de-facto low level connection mode for the SQL Server adapter for ActiveRecord. For further details see the special thanks section at the bottom +The benefits are speed, automatic casting to ruby primitives, and proper encoding support. It converts all SQL Server datatypes to native ruby objects supporting :utc or :local time zones for time-like types. To date it is the only ruby client library that allows client encoding options, defaulting to UTF-8, while connecting to SQL Server. It also properly encodes all string and binary data. The motivation for TinyTDS is to become the de-facto low level connection mode for the SQL Server adapter for ActiveRecord. For further details see the special thanks section at the bottom The API is simple and consists of these classes: * TinyTds::Client - Your connection to the database. * TinyTds::Result - Returned from issuing an #execute on the connection. It includes Enumerable. * TinyTds::Error - A wrapper for all exceptions. +== New & Noteworthy +* Works with FreeTDS 0.83.dev +* Tested on Windows using MiniPortile & RailsInstaller. + + == Install -Installing with rubygems should just work. TinyTds is tested on ruby version 1.8.6, 1.8.7, 1.9.1, 1.9.2 as well as REE & JRuby. +Installing with rubygems should just work. TinyTDS is tested on ruby version 1.8.6, 1.8.7, 1.9.1, 1.9.2 as well as REE & JRuby. $ gem install tiny_tds Although we search for FreeTDS's libraries and headers, you may have to specify include and lib directories using "--with-freetds-include=/some/local/include/freetds" and "--with-freetds-lib=/some/local/lib" == FreeTDS Compatibility -TinyTds is developed primarily for FreeTDS 0.82 and tested with SQL Server 2000, 2005, and 2008 using TDS Version 8.0. We utilize FreeTDS's db-lib client library. We compile against sybdb.h and define MSDBLIB which means that our client enables Microsoft behavior in the db-lib API where it diverges from Sybase's. You do NOT need to compile FreeTDS with the "--enable-msdblib" option for our client to work properly. However, please make sure to compile FreeTDS with libiconv support for encodings to work at their best. Run "tsql -C" in your console and check for "iconv library: yes". +TinyTDS is developed for FreeTDS 0.82 & 0.83.dev. It is tested with SQL Server 2000, 2005, and 2008 using TDS Version 8.0. We utilize FreeTDS's db-lib client library. We compile against sybdb.h and define MSDBLIB which means that our client enables Microsoft behavior in the db-lib API where it diverges from Sybase's. You do NOT need to compile FreeTDS with the "--enable-msdblib" option for our client to work properly. However, please make sure to compile FreeTDS with libiconv support for encodings to work at their best. Run "tsql -C" in your console and check for "iconv library: yes". == Data Types @@ -86,13 +91,22 @@ # The keys are the fields, as you'd expect. # The values are pre-built ruby primitives mapped from their corresponding types. # Here's an leemer: http://is.gd/g61xo end -Once a result returns its rows, you can access the fields. Returns nil if the data has not yet been loaded or there are no rows returned. +A result object has a #fields accessor. It can be called before the result rows are iterated over. Even if no rows are returned, #fields will still return the column names you expected. Any SQL that does not return columned data will always return an empty array for #fields. It is important to remember that if you access the #fields before iterating over the results, the columns will always follow the default query option's :symbolize_keys setting at the client's level and will ignore the query options passed to each. - result.fields # => [ ... ] + result = client.execute("USE [tinytds_test]") + result.fields # => [] + result.do + + result = client.execute("SELECT [id] FROM [datatypes]") + result.fields # => ["id"] + result.cancel + result = client.execute("SELECT [id] FROM [datatypes]") + result.each(:symbolize_keys => true) + result.fields # => [:id] You can cancel a result object's data from being loading by the server. result = client.execute("SELECT * FROM [super_big_table]") result.cancel @@ -134,10 +148,33 @@ # Second time over (if columns cached), yields each set. # 1st: [{"id"=>11}] # 2nd: [{"bigint"=>-9223372036854775807}, {"bigint"=>9223372036854775806}] end +Use the #sqlsent? and #canceled? query methods on the client to determine if an active SQL batch still needs to be processed and or if data results were canceled from the last result object. These values reset to true and false respectively for the client at the start of each #execute and new result object. Or if all rows are processed normally, #sqlsent? will return false. To demonstrate, lets assume we have 100 rows in the result object. + + client.sqlsent? # = false + client.canceled? # = false + + result = client.execute("SELECT * FROM [super_big_table]") + + client.sqlsent? # = true + client.canceled? # = false + + result.each do |row| + # Assume we break after 20 rows with 80 still pending. + break if row["id"] > 20 + end + + client.sqlsent? # = true + client.canceled? # = false + + result.cancel + + client.sqlsent? # = false + client.canceled? # = true + It is possible to get the return code after executing a stored procedure from either the result or client object. client.return_code # => nil result = client.execute("EXEC tinytds_TestReturnCodes") @@ -168,39 +205,38 @@ == Row Caching -By default row caching is turned on because the SQL Server adapter for ActiveRecord would not work without it. I hope to find some time to create some performance patches for ActiveRecord that would allow it to take advantages of lazily created yielded rows from result objects. Currently only TinyTds and the Mysql2 gem allow such a performance gain. +By default row caching is turned on because the SQL Server adapter for ActiveRecord would not work without it. I hope to find some time to create some performance patches for ActiveRecord that would allow it to take advantages of lazily created yielded rows from result objects. Currently only TinyTDS and the Mysql2 gem allow such a performance gain. -== Using TinyTds With Rails & The ActiveRecord SQL Server adapter. +== Using TinyTDS With Rails & The ActiveRecord SQL Server adapter. -As of version 2.3.11 & 3.0.3 of the adapter, you can specify a :dblib mode in database.yml and use TinyTds as the low level connection mode. Make sure to add a :dataserver option to that matches the name in your freetds.conf file. The SQL Server adapter can be found using the link below. Also included is a direct link to the wiki article covering common questions when using TinyTds as the low level connection mode for the adapter. +As of version 2.3.11 & 3.0.3 of the adapter, you can specify a :dblib mode in database.yml and use TinyTDS as the low level connection mode. Make sure to add a :dataserver option to that matches the name in your freetds.conf file. The SQL Server adapter can be found using the link below. Also included is a direct link to the wiki article covering common questions when using TinyTDS as the low level connection mode for the adapter. -http://github.com/rails-sqlserver/activerecord-sqlserver-adapter http://github.com/rails-sqlserver/activerecord-sqlserver-adapter/wiki/Using-TinyTds == Development & Testing We use bundler for development. Simply run "bundle install" then "rake" to build the gem and run the unit tests. The tests assume you have created a database named "tinytds_test" accessible by a database owner named "tinytds". Before running the test rake task, you may need to define a pair of environment variables that help the client connect to your specific FreeTDS database server name and which schema (2000, 2005 or 2008) to use. For example: - $ env TINYTDS_UNIT_DATASERVER=mydbserver TINYTDS_SCHEMA=sqlserver_2008 rake + $ rake TINYTDS_UNIT_DATASERVER=mydbserver TINYTDS_SCHEMA=sqlserver_2008 +If you are compiling locally using MiniPortile (the default dev setup) and you do not have a user based freetds.conf file with your dataservers, you may have to configure the locally compiled freetds.conf file. You can find it at the ports/<platform>/freetds/<version>/etc/freetds.conf path locally to your repo. In this situation you may have to set the FREETDS environment variable too this full path. + For help and support. * Github Source: http://github.com/rails-sqlserver/tiny_tds * Github Issues: http://github.com/rails-sqlserver/tiny_tds/issues * Google Group: http://groups.google.com/group/rails-sqlserver-adapter * IRC Room: #rails-sqlserver on irc.freenode.net Current to do list. -* Test 0.83 development of FreeTDS. -* Find someone brave enough to compile/test for Windows. * Install an interrupt handler. * Allow #escape to accept all ruby primitives. * Get bug reports!