sequel 2.3.0 → 2.4.0

data/lib/sequel_core/adapters/shared/sqlite.rb

@@ -7,6 +7,10 @@ module Sequel
       TABLES_FILTER = "type = 'table' AND NOT name = 'sqlite_sequence'"
       TEMP_STORE = {'0' => :default, '1' => :file, '2' => :memory}.freeze
       
+      # SQLite supports limited table modification.  You can add a column
+      # or an index.  Dropping columns is supported by copying the table into
+      # a temporary table, dropping the table, and creating a new table without
+      # the column inside of a transaction.
       def alter_table_sql(table, op)
         case op[:op]
         when :add_column
@@ -28,51 +32,59 @@ module Sequel
         end
       end
       
+      # A symbol signifying the value of the auto_vacuum PRAGMA.
       def auto_vacuum
         AUTO_VACUUM[pragma_get(:auto_vacuum).to_s]
       end
       
+      # Set the auto_vacuum PRAGMA using the given symbol (:none, :full, or
+      # :incremental).
       def auto_vacuum=(value)
         value = AUTO_VACUUM.key(value) || (raise Error, "Invalid value for auto_vacuum option. Please specify one of :none, :full, :incremental.")
         pragma_set(:auto_vacuum, value)
       end
       
+      # Get the value of the given PRAGMA.
       def pragma_get(name)
         self["PRAGMA #{name}"].single_value
       end
       
+      # Set the value of the given PRAGMA to value.
       def pragma_set(name, value)
         execute_ddl("PRAGMA #{name} = #{value}")
       end
       
-      def serial_primary_key_options
-        {:primary_key => true, :type => :integer, :auto_increment => true}
-      end
-      
+      # A symbol signifying the value of the synchronous PRAGMA.
       def synchronous
         SYNCHRONOUS[pragma_get(:synchronous).to_s]
       end
       
+      # Set the synchronous PRAGMA using the given symbol (:off, :normal, or :full).
       def synchronous=(value)
         value = SYNCHRONOUS.key(value) || (raise Error, "Invalid value for synchronous option. Please specify one of :off, :normal, :full.")
         pragma_set(:synchronous, value)
       end
-    
+      
+      # Array of symbols specifying the table names in the current database.
       def tables
         self[:sqlite_master].filter(TABLES_FILTER).map {|r| r[:name].to_sym}
       end
       
+      # A symbol signifying the value of the temp_store PRAGMA.
       def temp_store
         TEMP_STORE[pragma_get(:temp_store).to_s]
       end
       
+      # Set the temp_store PRAGMA using the given symbol (:default, :file, or :memory).
       def temp_store=(value)
         value = TEMP_STORE.key(value) || (raise Error, "Invalid value for temp_store option. Please specify one of :default, :file, :memory.")
         pragma_set(:temp_store, value)
       end
       
       private
-
+      
+      # SQLite supports schema parsing using the table_info PRAGMA, so
+      # parse the output of that into the format Sequel expects.
       def schema_parse_table(table_name, opts)
         rows = self["PRAGMA table_info(?)", table_name].collect do |row|
           row.delete(:cid)
@@ -92,15 +104,21 @@ module Sequel
         end
         schema_parse_rows(rows)
       end
-
+      
+      # SQLite doesn't support getting the schema of all tables at once,
+      # so loop through the output of #tables to get them.
       def schema_parse_tables(opts)
         schemas = {}
         tables.each{|table| schemas[table] = schema_parse_table(table, opts)}
         schemas
       end
     end
-  
-    module DatasetMethods      
+    
+    # Instance methods for datasets that connect to an SQLite database
+    module DatasetMethods
+      # SQLite does not support pattern matching via regular expressions.
+      # SQLite is case insensitive (depending on pragma), so use LIKE for
+      # ILIKE.
       def complex_expression_sql(op, args)
         case op
         when :~, :'!~', :'~*', :'!~*'
@@ -113,23 +131,29 @@ module Sequel
         end
       end
       
-      def delete(opts = nil)
+      # SQLite performs a TRUNCATE style DELETE if no filter is specified.
+      # Since we want to always return the count of records, do a specific
+      # count in the case of no filter.
+      def delete(opts = {})
         # check if no filter is specified
-        unless (opts && opts[:where]) || @opts[:where]
-          @db.transaction do
+        opts = @opts.merge(opts)
+        unless opts[:where]
+          @db.transaction(opts[:server]) do
             unfiltered_count = count
-            @db.execute_dui delete_sql(opts)
+            execute_dui(delete_sql(opts))
             unfiltered_count
           end
         else
-          @db.execute_dui delete_sql(opts)
+          execute_dui(delete_sql(opts))
         end
       end
       
+      # Insert the values into the database.
       def insert(*values)
-        @db.execute_insert insert_sql(*values)
+        execute_insert(insert_sql(*values))
       end
-
+      
+      # Allow inserting of values directly from a dataset.
       def insert_sql(*values)
         if (values.size == 1) && values.first.is_a?(Sequel::Dataset)
           "INSERT INTO #{source_list(@opts[:from])} #{values.first.sql};"
@@ -138,9 +162,17 @@ module Sequel
         end
       end
       
+      # SQLite uses the nonstandard ` (backtick) for quoting identifiers.
       def quoted_identifier(c)
         "`#{c}`"
       end
+      
+      private
+      
+      # Call execute_insert on the database with the given SQL.
+      def execute_insert(sql, opts={})
+        @db.execute_insert(sql, {:server=>@opts[:server] || :default}.merge(opts))
+      end
     end
   end
 end

data/lib/sequel_core/adapters/sqlite.rb

@@ -2,22 +2,33 @@ require 'sqlite3'
 require 'sequel_core/adapters/shared/sqlite'
 
 module Sequel
+  # Top level module for holding all SQLite-related modules and classes
+  # for Sequel.
   module SQLite
+    # Database class for PostgreSQL databases used with Sequel and the
+    # ruby-sqlite3 driver.
     class Database < Sequel::Database
       include ::Sequel::SQLite::DatabaseMethods
       
       set_adapter_scheme :sqlite
       
+      # Mimic the file:// uri, by having 2 preceding slashes specify a relative
+      # path, and 3 preceding slashes specify an absolute path.
       def self.uri_to_options(uri) # :nodoc:
         { :database => (uri.host.nil? && uri.path == '/') ? nil : "#{uri.host}#{uri.path}" }
       end
-
+      
       private_class_method :uri_to_options
-
-      def connect
-        @opts[:database] = ':memory:' if @opts[:database].blank?
-        db = ::SQLite3::Database.new(@opts[:database])
-        db.busy_timeout(@opts.fetch(:timeout, 5000))
+      
+      # Connect to the database.  Since SQLite is a file based database,
+      # the only options available are :database (to specify the database
+      # name), and :timeout, to specify how long to wait for the database to
+      # be available if it is locked, given in milliseconds (default is 5000).
+      def connect(server)
+        opts = server_opts(server)
+        opts[:database] = ':memory:' if opts[:database].blank?
+        db = ::SQLite3::Database.new(opts[:database])
+        db.busy_timeout(opts.fetch(:timeout, 5000))
         db.type_translation = true
         # fix for timestamp translation
         db.translator.add_translator("timestamp") do |t, v|
@@ -26,58 +37,45 @@ module Sequel
         db
       end
       
+      # Return instance of Sequel::SQLite::Dataset with the given options.
       def dataset(opts = nil)
         SQLite::Dataset.new(self, opts)
       end
       
+      # Disconnect all connections from the database.
       def disconnect
         @pool.disconnect {|c| c.close}
       end
-    
-      def execute(sql)
-        begin
-          log_info(sql)
-          @pool.hold {|conn| conn.execute_batch(sql); conn.changes}
-        rescue SQLite3::Exception => e
-          raise Error::InvalidStatement, "#{sql}\r\n#{e.message}"
-        end
+      
+      # Run the given SQL with the given arguments and return the number of changed rows.
+      def execute_dui(sql, opts={})
+        _execute(sql, opts){|conn| conn.execute_batch(sql, opts[:arguments]); conn.changes}
       end
       
-      def execute_insert(sql)
-        begin
-          log_info(sql)
-          @pool.hold {|conn| conn.execute(sql); conn.last_insert_row_id}
-        rescue SQLite3::Exception => e
-          raise Error::InvalidStatement, "#{sql}\r\n#{e.message}"
-        end
+      # Run the given SQL with the given arguments and return the last inserted row id.
+      def execute_insert(sql, opts={})
+        _execute(sql, opts){|conn| conn.execute(sql, opts[:arguments]); conn.last_insert_row_id}
       end
       
-      def single_value(sql)
-        begin
-          log_info(sql)
-          @pool.hold {|conn| conn.get_first_value(sql)}
-        rescue SQLite3::Exception => e
-          raise Error::InvalidStatement, "#{sql}\r\n#{e.message}"
-        end
+      # Run the given SQL with the given arguments and yield each row.
+      def execute(sql, opts={}, &block)
+        _execute(sql, opts){|conn| conn.query(sql, opts[:arguments], &block)}
       end
       
-      def execute_select(sql, &block)
-        begin
-          log_info(sql)
-          @pool.hold {|conn| conn.query(sql, &block)}
-        rescue SQLite3::Exception => e
-          raise Error::InvalidStatement, "#{sql}\r\n#{e.message}"
-        end
+      # Run the given SQL with the given arguments and return the first value of the first row.
+      def single_value(sql, opts={})
+        _execute(sql, opts){|conn| conn.get_first_value(sql, opts[:arguments])}
       end
       
-      def transaction(&block)
-        @pool.hold do |conn|
-          if conn.transaction_active?
-            return yield(conn)
-          end
+      # Use the native driver transaction method if there isn't already a transaction
+      # in progress on the connection, always yielding a connection inside a transaction
+      # transaction.
+      def transaction(server=nil, &block)
+        synchronize(server) do |conn|
+          return yield(conn) if conn.transaction_active?
           begin
             result = nil
-            conn.transaction {result = yield(conn)}
+            conn.transaction{result = yield(conn)}
             result
           rescue ::Exception => e
             raise (SQLite3::Exception === e ? Error.new(e.message) : e) unless Error::Rollback === e
@@ -87,6 +85,20 @@ module Sequel
       
       private
       
+      # Log the SQL and the arguments, and yield an available connection.  Rescue
+      # any SQLite3::Exceptions and turn the into Error::InvalidStatements.
+      def _execute(sql, opts)
+        begin
+          log_info(sql, opts[:arguments])
+          synchronize(opts[:server]){|conn| yield conn}
+        rescue SQLite3::Exception => e
+          raise Error::InvalidStatement, "#{sql}\r\n#{e.message}"
+        end
+      end
+      
+      # SQLite does not need the pool to convert exceptions.
+      # Also, force the max connections to 1 if a memory database is being
+      # used, as otherwise each connection gets a separate database.
       def connection_pool_default_options
         o = super.merge(:pool_convert_exceptions=>false)
         # Default to only a single connection if a memory database is used,
@@ -96,19 +108,85 @@ module Sequel
       end
     end
     
+    # Dataset class for SQLite datasets that use the ruby-sqlite3 driver.
     class Dataset < Sequel::Dataset
       include ::Sequel::SQLite::DatasetMethods
       
       EXPLAIN = 'EXPLAIN %s'.freeze
+      PREPARED_ARG_PLACEHOLDER = ':'.freeze
+      
+      # SQLite already supports named bind arguments, so use directly.
+      module ArgumentMapper
+        include Sequel::Dataset::ArgumentMapper
+        
+        protected
+        
+        # Return a hash with the same values as the given hash,
+        # but with the keys converted to strings.
+        def map_to_prepared_args(hash)
+          args = {}
+          hash.each{|k,v| args[k.to_s] = v}
+          args
+        end
+        
+        private
+        
+        # Work around for the default prepared statement and argument
+        # mapper code, which wants a hash that maps.  SQLite doesn't
+        # need to do this, but still requires a value for the argument
+        # in order for the substitution to work correctly.
+        def prepared_args_hash
+          true
+        end
+        
+        # SQLite uses a : before the name of the argument for named
+        # arguments.
+        def prepared_arg(k)
+          "#{prepared_arg_placeholder}#{k}".lit
+        end
+      end
+      
+      # SQLite prepared statement uses a new prepared statement each time
+      # it is called, but it does use the bind arguments.
+      module PreparedStatementMethods
+        include ArgumentMapper
+        
+        private
+        
+        # Run execute_select on the database with the given SQL and the stored
+        # bind arguments.
+        def execute(sql, opts={}, &block)
+          super(sql, {:arguments=>bind_arguments}.merge(opts), &block)
+        end
+        
+        # Same as execute, explicit due to intricacies of alias and super.
+        def execute_dui(sql, opts={}, &block)
+          super(sql, {:arguments=>bind_arguments}.merge(opts), &block)
+        end
+        
+        # Same as execute, explicit due to intricacies of alias and super.
+        def execute_insert(sql, opts={}, &block)
+          super(sql, {:arguments=>bind_arguments}.merge(opts), &block)
+        end
+      end
       
+      # Prepare an unnamed statement of the given type and call it with the
+      # given values.
+      def call(type, hash, values=nil, &block)
+        prepare(type, nil, values).call(hash, &block)
+      end
+      
+      # Return an array of strings specifying a query explanation for the
+      # current dataset.
       def explain
         res = []
         @db.result_set(EXPLAIN % select_sql(opts), nil) {|r| res << r}
         res
       end
-
+      
+      # Yield a hash for each row in the dataset.
       def fetch_rows(sql)
-        @db.execute_select(sql) do |result|
+        execute(sql) do |result|
           @columns = result.columns.map {|c| c.to_sym}
           column_count = @columns.size
           result.each do |values|
@@ -118,7 +196,9 @@ module Sequel
           end
         end
       end
-
+      
+      # Use the ISO format for dates and timestamps, and quote strings
+      # using the ::SQLite3::Database.quote method.
       def literal(v)
         case v
         when LiteralString
@@ -133,6 +213,23 @@ module Sequel
           super
         end
       end
+      
+      # Prepare the given type of query with the given name and store
+      # it in the database.  Note that a new native prepared statement is
+      # created on each call to this prepared statement.
+      def prepare(type, name, values=nil)
+        ps = to_prepared_statement(type, values)
+        ps.extend(PreparedStatementMethods)
+        db.prepared_statements[name] = ps if name
+        ps
+      end
+      
+      private
+      
+      # SQLite uses a : before the name of the argument as a placeholder.
+      def prepared_arg_placeholder
+        PREPARED_ARG_PLACEHOLDER
+      end
     end
   end
 end

data/lib/sequel_core/connection_pool.rb

@@ -2,21 +2,8 @@
 # multiple connections and giving threads exclusive access to each
 # connection.
 class Sequel::ConnectionPool
-  # A hash of connections currently being used, key is the Thread,
-  # value is the connection.
-  attr_reader :allocated
-  
-  # An array of connections opened but not currently used
-  attr_reader :available_connections
-  
   # The proc used to create a new database connection.
   attr_accessor :connection_proc
-  
-  # The total number of connections opened, should
-  # be equal to available_connections.length +
-  # allocated.length
-  attr_reader :created_count
-  alias_method :size, :created_count
 
   # The maximum number of connections.
   attr_reader :max_size
@@ -25,7 +12,6 @@ class Sequel::ConnectionPool
   # this if you want to manipulate the variables safely.
   attr_reader :mutex
   
-
   # Constructs a new pool with a maximum size. If a block is supplied, it
   # is used to create new connections as they are needed.
   #
@@ -47,21 +33,50 @@ class Sequel::ConnectionPool
   #   a connection again (default 0.001)
   # * :pool_timeout - The amount of seconds to wait to acquire a connection
   #   before raising a PoolTimeoutError (default 5)
+  # * :servers - A hash of servers to use.  Keys should be symbols.  If not
+  #   present, will use a single :default server.  The server name symbol will
+  #   be passed to the connection_proc.
   def initialize(opts = {}, &block)
     @max_size = opts[:max_connections] || 4
     @mutex = Mutex.new
     @connection_proc = block
-
-    @available_connections = []
-    @allocated = {}
-    @created_count = 0
+    @servers = [:default]
+    @servers += opts[:servers].keys - @servers if opts[:servers] 
+    @available_connections = Hash.new{|h,k| h[:default]}
+    @allocated = Hash.new{|h,k| h[:default]}
+    @created_count = Hash.new{|h,k| h[:default]}
+    @servers.each do |s|
+      @available_connections[s] = []
+      @allocated[s] = {}
+      @created_count[s] = 0
+    end
     @timeout = opts[:pool_timeout] || 5
     @sleep_time = opts[:pool_sleep_time] || 0.001
     @convert_exceptions = opts.include?(:pool_convert_exceptions) ? opts[:pool_convert_exceptions] : true
   end
   
-  # Chooses the first available connection, or if none are available,
-  # creates a new connection.  Passes the connection to the supplied block:
+  # A hash of connections currently being used for the given server, key is the
+  # Thread, value is the connection.
+  def allocated(server=:default)
+    @allocated[server]
+  end
+  
+  # An array of connections opened but not currently used, for the given
+  # server.
+  def available_connections(server=:default)
+    @available_connections[server]
+  end
+  
+  # The total number of connections opened for the given server, should
+  # be equal to available_connections.length + allocated.length
+  def created_count(server=:default)
+    @created_count[server]
+  end
+  alias size created_count
+  
+  # Chooses the first available connection to the given server, or if none are
+  # available, creates a new connection.  Passes the connection to the supplied
+  # block:
   # 
   #   pool.hold {|conn| conn.execute('DROP TABLE posts')}
   # 
@@ -73,78 +88,83 @@ class Sequel::ConnectionPool
   # is available or the timeout expires.  If the timeout expires before a
   # connection can be acquired, a Sequel::Error::PoolTimeoutError is 
   # raised.
-  def hold
+  def hold(server=:default)
     begin
       t = Thread.current
       time = Time.new
       timeout = time + @timeout
       sleep_time = @sleep_time
-      if conn = owned_connection(t)
+      if conn = owned_connection(t, server)
         return yield(conn)
       end
-      until conn = acquire(t)
+      until conn = acquire(t, server)
         raise(::Sequel::Error::PoolTimeoutError) if Time.new > timeout
         sleep sleep_time
       end
       begin
         yield conn
       ensure
-        release(t, conn)
+        release(t, conn, server)
       end
     rescue Exception => e
       raise(@convert_exceptions && !e.is_a?(StandardError) ? RuntimeError.new(e.message) : e)
     end
   end
   
-  # Removes all connection currently available, optionally yielding each 
-  # connection to the given block. This method has the effect of 
-  # disconnecting from the database. Once a connection is requested using
-  # #hold, the connection pool creates new connections to the database.
-  def disconnect(&block)
+  # Removes all connection currently available on all servers, optionally
+  # yielding each connection to the given block. This method has the effect of 
+  # disconnecting from the database, assuming that no connections are currently
+  # being used. Once a connection is requested using #hold, the connection pool
+  # creates new connections to the database.
+  def disconnect
     @mutex.synchronize do
-      @available_connections.each {|c| block[c]} if block
-      @available_connections = []
-      @created_count = @allocated.size
+      @available_connections.each do |server, conns|
+        conns.each{|c| yield(c)} if block_given?
+        conns.clear
+        @created_count[server] = allocated(server).length
+      end
     end
   end
   
   private
 
-  # Returns the connection owned by the supplied thread, if any.
-  def owned_connection(thread)
-    @mutex.synchronize{@allocated[thread]}
+  # Returns the connection owned by the supplied thread for the given server,
+  # if any.
+  def owned_connection(thread, server)
+    @mutex.synchronize{@allocated[server][thread]}
   end
   
-  # Assigns a connection to the supplied thread, if one is available.
-  def acquire(thread)
+  # Assigns a connection to the supplied thread for the given server, if one
+  # is available.
+  def acquire(thread, server)
     @mutex.synchronize do
-      if conn = available
-        @allocated[thread] = conn
+      if conn = available(server)
+        allocated(server)[thread] = conn
       end
     end
   end
   
-  # Returns an available connection. If no connection is available,
-  # tries to create a new connection.
-  def available
-    @available_connections.pop || make_new
+  # Returns an available connection to the given server. If no connection is
+  # available, tries to create a new connection.
+  def available(server)
+    available_connections(server).pop || make_new(server)
   end
   
-  # Creates a new connection if the size of the pool is less than the
-  # maximum size.
-  def make_new
-    if @created_count < @max_size
-      @created_count += 1
-      @connection_proc ? @connection_proc.call : \
+  # Creates a new connection to the given server if the size of the pool for
+  # the server is less than the maximum size of the pool.
+  def make_new(server)
+    if @created_count[server] < @max_size
+      @created_count[server] += 1
+      @connection_proc ? @connection_proc.call(server) : \
         (raise Error, "No connection proc specified")
     end
   end
   
-  # Releases the connection assigned to the supplied thread.
-  def release(thread, conn)
+  # Releases the connection assigned to the supplied thread and server.
+  def release(thread, conn, server)
     @mutex.synchronize do
-      @allocated.delete(thread)
-      @available_connections << conn
+      allocated(server).delete(thread)
+      available_connections(server) << conn
     end
   end
 end
@@ -156,9 +176,6 @@ end
 # Note that using a single threaded pool with some adapters can cause
 # errors in certain cases, see Sequel.single_threaded=.
 class Sequel::SingleThreadedPool
-  # The single database connection for the pool
-  attr_reader :conn
-
   # The proc used to create a new database connection
   attr_writer :connection_proc
   
@@ -170,15 +187,20 @@ class Sequel::SingleThreadedPool
   #   to RuntimeError exceptions (default true)
   def initialize(opts={}, &block)
     @connection_proc = block
+    @conns = {}
     @convert_exceptions = opts.include?(:pool_convert_exceptions) ? opts[:pool_convert_exceptions] : true
   end
   
-  # Yields the connection to the supplied block. This method simulates the
-  # ConnectionPool#hold API.
-  def hold
+  # The connection for the given server.
+  def conn(server=:default)
+    @conns[server]
+  end
+  
+  # Yields the connection to the supplied block for the given server.
+  # This method simulates the ConnectionPool#hold API.
+  def hold(server=:default)
     begin
-      @conn ||= @connection_proc.call
-      yield @conn
+      yield(@conns[server] ||= @connection_proc.call(server))
     rescue Exception => e
       # if the error is not a StandardError it is converted into RuntimeError.
       raise(@convert_exceptions && !e.is_a?(StandardError) ? RuntimeError.new(e.message) : e)
@@ -188,7 +210,7 @@ class Sequel::SingleThreadedPool
   # Disconnects from the database. Once a connection is requested using
   # #hold, the connection is reestablished.
   def disconnect(&block)
-    block[@conn] if block && @conn
-    @conn = nil
+    @conns.values.each{|conn| yield(conn) if block_given?}
+    @conns = {}
   end
 end