sequel 3.21.0 → 3.28.0

data/doc/transactions.rdoc

@@ -0,0 +1,97 @@
+= Database Transactions 
+
+Sequel uses autocommit mode by default for all of its database adapters, so in general in Sequel if you want to use database transactions, you need to be explicit about it.  There are a few cases where transactions are used implicitly by default:
+
+* Dataset#import to insert many records at once
+* Model#save
+* Model#destroy
+* Migrations
+* A few model plugins
+
+Everywhere else, it is up to use to use a database transaction if you want to.
+
+== Basic Transaction Usage
+
+In Sequel, the <tt>Database#transaction</tt> method should be called if you want to use a database transaction.  This method must be called with a block.  If the block does not raise an exception, the transaction is committed:
+
+  DB.transaction do # BEGIN
+    DB[:foo].insert(1) # INSERT
+  end # COMMIT
+   
+If the block raises a Sequel::Rollback exception, the transaction is rolled back, but no exception is raised outside the block:
+
+  DB.transaction do # BEGIN
+    raise Sequel::Rollback
+  end # ROLLBACK
+  # no exception raised
+
+If any other exception is raised, the transaction is rolled back, and the exception is raised outside the block:
+
+  # ArgumentError raised
+  DB.transaction do # BEGIN
+    raise ArgumentError
+  end # ROLLBACK
+  # ArgumentError raised
+
+== Nested Transaction Calls / Savepoints
+
+You can nest calls to transaction, which by default just reuses the existing transaction:
+
+  DB.transaction do # BEGIN
+    DB.transaction do
+      DB[:foo].insert(1) # INSERT
+    end
+  end # COMMIT
+
+You can use the <tt>:savepoint => true</tt> option in the inner transaction to explicitly use a savepoint (if the database supports it):
+
+  DB.transaction do # BEGIN
+    DB.transaction(:savepoint => true) do # SAVEPOINT
+      DB[:foo].insert(1) # INSERT
+    end # RELEASE SAVEPOINT
+  end # COMMIT
+
+If a Sequel::Rollback exception is raised inside the savepoint block, it will only rollback to the savepoint:
+
+  DB.transaction do # BEGIN
+    DB.transaction(:savepoint => true) do # SAVEPOINT
+      raise Sequel::Rollback
+    end # ROLLBACK TO SAVEPOINT
+    # no exception raised
+  end # COMMIT
+
+Other exceptions, unless rescued inside the outer transaction block, will rollback the savepoint and the outer transactions, since they are reraised by the transaction code:
+
+  DB.transaction do # BEGIN
+    DB.transaction(:savepoint => true) do # SAVEPOINT
+      raise ArgumentError
+    end # ROLLBACK TO SAVEPOINT
+  end # ROLLBACK
+  # ArgumentError raised
+
+== Prepared Transactions / Two-Phase Commit
+
+Sequel supports database prepared transactions on PostreSQL, MySQL, and H2.  With prepared transactions, at the end of the transaction, the transaction is not immediately committed (it acts like a rollback).  Later, you can call +commit_prepared_transaction+ to commit the transaction or +rollback_prepared_transaction+ to roll the transaction back.  Prepared transactions are usually used with distributed databases to make sure all databases commit the same transaction or none of them do.
+
+To use prepared transactions in Sequel, you provide a string as the value of the :prepare option:
+
+  DB.transaction(:prepare => 'foo') do # BEGIN
+    DB[:foo].insert(1) # INSERT
+  end # PREPARE TRANSACTION 'foo'
+   
+Later, you can commit the prepared transaction:
+
+  DB.commit_prepared_transaction('foo')
+
+or roll the prepared transaction back:
+
+  DB.rollback_prepared_transaction('foo')
+
+== Transaction Isolation Levels
+
+The SQL standard supports 4 isolation levels: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, and SERIALIZABLE.  Not all databases implement the levels as specified in the standard (or implement the levels at all), but on PostgreSQL, MySQL, and Microsoft SQL Server, you can specify which transaction isolation level you want to use via the :isolation option to <tt>Database#transaction</tt>.  The isolation level is specified as one of the following symbols: :uncommitted, :committed, :repeatable, and :serializable.  Using this option make Sequel use the correct transaction isolation syntax for your database:
+
+  DB.transaction(:isolation => :serializable) do # BEGIN
+    # SET TRANSACTION ISOLATION LEVEL SERIALIZABLE
+    DB[:foo].insert(1) # INSERT
+  end # COMMIT

data/doc/virtual_rows.rdoc

@@ -40,7 +40,7 @@ available.  For example, you are no longer able to do:
   # WHERE a AND (b OR NOT c)
   
 Because Symbol#&, Symbol#| and Symbol#~ are not defined when the core
-extensions are turned off.  However, with virtual rows allow almost the same
+extensions are turned off.  However, virtual rows allow almost the same
 syntax even without the core extensions:
 
   dataset.filter{a & (b | ~c)}
@@ -87,7 +87,7 @@ and second is the difference between the the use of "a".  In the regular proc,
 you couldn't call c without an explicit receiver in the proc, unless the self of the
 surrounding scope responded to it.  For a, note how ruby calls the method on
 the receiver of the surrounding scope in the regular proc, which returns an integer,
-and does the substraction before Sequel gets access to it.  In the instance evaled
+and does the substitution before Sequel gets access to it.  In the instance evaled
 proc, calling a without a receiver calls the a method on the VirtualRow instance.
 For b, note that it operates the same in both cases, as it is a local variable.
 

data/lib/sequel/adapters/ado.rb

@@ -4,6 +4,8 @@ module Sequel
   # The ADO adapter provides connectivity to ADO databases in Windows.
   module ADO
     class Database < Sequel::Database
+      DISCONNECT_ERROR_RE = /Communication link failure/
+
       set_adapter_scheme :ado
 
       def initialize(opts)
@@ -12,12 +14,13 @@ module Sequel
         when /Microsoft\.(Jet|ACE)\.OLEDB/io
           Sequel.ts_require 'adapters/shared/access'
           extend Sequel::Access::DatabaseMethods
-        when nil
+        else
           @opts[:driver] ||= 'SQL Server'
           case @opts[:driver]
           when 'SQL Server'
             Sequel.ts_require 'adapters/ado/mssql'
             extend Sequel::ADO::MSSQL::DatabaseMethods
+            set_mssql_unicode_strings
           end
         end
       end
@@ -86,9 +89,17 @@ module Sequel
         end
       end
       
+      def database_error_classes
+        [::WIN32OLERuntimeError]
+      end
+
       def disconnect_connection(conn)
         conn.Close
       end
+
+      def disconnect_error?(e, opts)
+        super || (e.is_a?(::WIN32OLERuntimeError) && e.message =~ DISCONNECT_ERROR_RE)
+      end
     end
     
     class Dataset < Sequel::Dataset

data/lib/sequel/adapters/amalgalite.rb

@@ -31,6 +31,10 @@ module Sequel
       def datetime(s)
         Sequel.database_to_application_timestamp(s)
       end
+
+      def time(s)
+        Sequel.string_to_time(s)
+      end
       
       # Don't raise an error if the value is a string and the declared
       # type doesn't match a known type, just return the value.

data/lib/sequel/adapters/db2.rb

@@ -1,23 +1,24 @@
 require 'db2/db2cli'
+Sequel.require %w'shared/db2', 'adapters'
 
 module Sequel
   module DB2
     class Database < Sequel::Database
-      set_adapter_scheme :db2
+      include DatabaseMethods
 
-      include DB2CLI
+      set_adapter_scheme :db2
 
       TEMPORARY = 'GLOBAL TEMPORARY '.freeze
       
-      rc, @@env = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE)
+      rc, @@env = DB2CLI.SQLAllocHandle(DB2CLI::SQL_HANDLE_ENV, DB2CLI::SQL_NULL_HANDLE)
       #check_error(rc, "Could not allocate DB2 environment")
 
       def connect(server)
         opts = server_opts(server)
-        rc, dbc = SQLAllocHandle(SQL_HANDLE_DBC, @@env) 
+        rc, dbc = DB2CLI.SQLAllocHandle(DB2CLI::SQL_HANDLE_DBC, @@env) 
         check_error(rc, "Could not allocate database connection")
         
-        rc = SQLConnect(dbc, opts[:database], opts[:user], opts[:password]) 
+        rc = DB2CLI.SQLConnect(dbc, opts[:database], opts[:user], opts[:password]) 
         check_error(rc, "Could not connect to database")
         
         dbc
@@ -32,102 +33,138 @@ module Sequel
         DB2::Dataset.new(self, opts)
       end
       
-      def execute(sql, opts={})
+      def execute(sql, opts={}, &block)
+        synchronize(opts[:server]){|conn| log_connection_execute(conn, sql, &block)}
+      end
+      alias do execute
+
+      def execute_insert(sql, opts={})
         synchronize(opts[:server]) do |conn|
-          rc, sth = SQLAllocHandle(SQL_HANDLE_STMT, @handle) 
-          check_error(rc, "Could not allocate statement")
-
-          begin
-            rc = log_yield(sql){SQLExecDirect(sth, sql)}
-            check_error(rc, "Could not execute statement")
-            
-            yield(sth) if block_given?
-
-            rc, rpc = SQLRowCount(sth)
-            check_error(rc, "Could not get RPC") 
-            rpc
-          ensure
-            rc = SQLFreeHandle(SQL_HANDLE_STMT, sth)
-            check_error(rc, "Could not free statement")
+          log_connection_execute(conn, sql)
+          sql = "SELECT IDENTITY_VAL_LOCAL() FROM SYSIBM.SYSDUMMY1"
+          log_connection_execute(conn, sql) do |sth|
+            rc, name, buflen, datatype, size, digits, nullable = DB2CLI.SQLDescribeCol(sth, 1, 256)
+            check_error(rc, "Could not describe column")
+            if (rc = DB2CLI.SQLFetch(sth)) != DB2CLI::SQL_NO_DATA_FOUND
+              rc, v = DB2CLI.SQLGetData(sth, 1, datatype, size)
+              check_error(rc, "Could not get data")
+              if v.is_a?(String) 
+                return v.to_i
+              else
+                return nil
+              end
+            end
           end
         end
       end
-      alias_method :do, :execute
-      
-      private
       
       def check_error(rc, msg)
         case rc
-        when SQL_SUCCESS, SQL_SUCCESS_WITH_INFO
+        when DB2CLI::SQL_SUCCESS, DB2CLI::SQL_SUCCESS_WITH_INFO
           nil
         else
           raise DatabaseError, msg
         end
       end
 
+      private
+
+      def begin_transaction(conn, opts={})
+        log_yield(TRANSACTION_BEGIN){DB2CLI.SQLSetConnectAttr(conn, DB2CLI::SQL_ATTR_AUTOCOMMIT, DB2CLI::SQL_AUTOCOMMIT_OFF)}
+        conn
+      end
+
+      def rollback_transaction(conn, opts={})
+        log_yield(TRANSACTION_ROLLBACK){DB2CLI.SQLEndTran(DB2CLI::SQL_HANDLE_DBC, conn, DB2CLI::SQL_ROLLBACK)}
+      ensure
+        DB2CLI.SQLSetConnectAttr(conn, DB2CLI::SQL_ATTR_AUTOCOMMIT, DB2CLI::SQL_AUTOCOMMIT_ON)
+      end
+
+      def commit_transaction(conn, opts={})
+        log_yield(TRANSACTION_COMMIT){DB2CLI.SQLEndTran(DB2CLI::SQL_HANDLE_DBC, conn, DB2CLI::SQL_COMMIT)}
+      ensure
+        DB2CLI.SQLSetConnectAttr(conn, DB2CLI::SQL_ATTR_AUTOCOMMIT, DB2CLI::SQL_AUTOCOMMIT_ON)
+      end
+    
+      def log_connection_execute(conn, sql)
+        rc, sth = DB2CLI.SQLAllocHandle(DB2CLI::SQL_HANDLE_STMT, conn) 
+        check_error(rc, "Could not allocate statement")
+
+        begin
+          rc = log_yield(sql){DB2CLI.SQLExecDirect(sth, sql)}
+          check_error(rc, "Could not execute statement: #{sql}")
+          
+          yield(sth) if block_given?
+
+          rc, rpc = DB2CLI.SQLRowCount(sth)
+          check_error(rc, "Could not get RPC") 
+          rpc
+        ensure
+          rc = DB2CLI.SQLFreeHandle(DB2CLI::SQL_HANDLE_STMT, sth)
+          check_error(rc, "Could not free statement")
+        end
+      end
+
       def disconnect_connection(conn)
-        rc = SQLDisconnect(conn)
+        rc = DB2CLI.SQLDisconnect(conn)
         check_error(rc, "Could not disconnect from database")
 
-        rc = SQLFreeHandle(SQL_HANDLE_DBC, conn)
+        rc = DB2CLI.SQLFreeHandle(DB2CLI::SQL_HANDLE_DBC, conn)
         check_error(rc, "Could not free Database handle")
       end
     end
     
     class Dataset < Sequel::Dataset
+      include DatasetMethods
+
       MAX_COL_SIZE = 256
       
       def fetch_rows(sql)
         execute(sql) do |sth|
-          @column_info = get_column_info(sth)
-          @columns = @column_info.map {|c| output_identifier(c[:name])}
-          while (rc = SQLFetch(@handle)) != SQL_NO_DATA_FOUND
-            @db.check_error(rc, "Could not fetch row")
-            yield hash_row(sth)
+          offset = @opts[:offset]
+          db = @db
+          i = 1
+          column_info = get_column_info(sth)
+          cols = column_info.map{|c| c.at(1)}
+          cols.delete(row_number_column) if offset
+          @columns = cols
+          while (rc = DB2CLI.SQLFetch(sth)) != DB2CLI::SQL_NO_DATA_FOUND
+            db.check_error(rc, "Could not fetch row")
+            row = {}
+            column_info.each do |i, c, t, s|
+              rc, v = DB2CLI.SQLGetData(sth, i, t, s) 
+              db.check_error(rc, "Could not get data")
+              row[c] = convert_type(v)
+            end
+            row.delete(row_number_column) if offset
+            yield row
           end
         end
         self
       end
       
-      # DB2 supports window functions
-      def supports_window_functions?
-        true
-      end
-      
       private
 
       def get_column_info(sth)
-        rc, column_count = SQLNumResultCols(sth)
-        @db.check_error(rc, "Could not get number of result columns")
+        db = @db
+        rc, column_count = DB2CLI.SQLNumResultCols(sth)
+        db.check_error(rc, "Could not get number of result columns")
 
         (1..column_count).map do |i| 
-          rc, name, buflen, datatype, size, digits, nullable = SQLDescribeCol(sth, i, MAX_COL_SIZE)
-          @b.check_error(rc, "Could not describe column")
-          
-          {:name => name, :db2_type => datatype, :precision => size}
+          rc, name, buflen, datatype, size, digits, nullable = DB2CLI.SQLDescribeCol(sth, i, MAX_COL_SIZE)
+          db.check_error(rc, "Could not describe column")
+          [i, output_identifier(name), datatype, size]
         end 
       end
       
-      def hash_row(sth)
-        row = {}
-        @column_info.each_with_index do |c, i|
-          rc, v = SQLGetData(sth, i+1, c[:db2_type], c[:precision]) 
-          @db.check_error(rc, "Could not get data")
-          
-          row[output_identifier(c[:name])] = convert_type(v)
-        end
-        row
-      end
-      
       def convert_type(v)
         case v
         when DB2CLI::Date 
-          DBI::Date.new(v.year, v.month, v.day)
+          Date.new(v.year, v.month, v.day)
         when DB2CLI::Time
-          DBI::Time.new(v.hour, v.minute, v.second)
+          Sequel::SQLTime.create(v.hour, v.minute, v.second)
         when DB2CLI::Timestamp 
-          DBI::Timestamp.new(v.year, v.month, v.day,
-            v.hour, v.minute, v.second, v.fraction)
+          Sequel.database_to_application_timestamp(v.to_s)
         when DB2CLI::Null
           nil
         else  

data/lib/sequel/adapters/do.rb

@@ -36,6 +36,8 @@ module Sequel
     # Sequel::DataObjects::Database object, or hack DataObjects (or Extlib) to
     # use a pool size at least as large as the pool size being used by Sequel.
     class Database < Sequel::Database
+      DISCONNECT_ERROR_RE = /terminating connection due to administrator command/
+
       set_adapter_scheme :do
       
       # Call the DATABASE_SETUP proc directly after initialization,
@@ -145,10 +147,20 @@ module Sequel
         :execute_non_query
       end
       
+      # dataobjects uses the DataObjects::Error class as the main error class.
+      def database_error_classes
+        [::DataObjects::Error]
+      end
+
       # Close the given database connection.
       def disconnect_connection(c)
         c.close
       end
+
+      # Recognize DataObjects::ConnectionError instances as disconnect errors.
+      def disconnect_error?(e, opts)
+        super || (e.is_a?(::DataObjects::Error) && (e.is_a?(::DataObjects::ConnectionError) || e.message =~ DISCONNECT_ERROR_RE))
+      end
       
       # Execute SQL on the connection by creating a command first
       def log_connection_execute(conn, sql)