module Sequel
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
Top level module for Sequel
There are some module methods that are added via metaprogramming, one for each supported adapter. For example:
DB = Sequel.sqlite # Memory database DB = Sequel.sqlite('blog.db') DB = Sequel.postgres('database_name', :user=>'user', :password=>'password', :host=>'host', :port=>5432, :max_connections=>10)
If a block is given to these methods, it is passed the opened Database object, which is closed (disconnected) when the block exits, just like a block passed to connect. For example:
Sequel.sqlite('blog.db'){|db| puts db[:users].count}
For a more expanded introduction, see the README. For a quicker introduction, see the cheat sheet.
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
The duplicate_columns_handler extension allows you to customize handling of duplicate column names in your queries on a per-database or per-dataset level.
For example, you may want to raise an exception if you join 2 tables together which contains a column that will override another columns.
To use the extension, you need to load the extension into the database:
DB.extension :duplicate_columns_handler
A database option is introduced: :on_duplicate_columns. It accepts a Symbol or any object that responds to :call.
:on_duplicate_columns => :raise :on_duplicate_columns => :warn :on_duplicate_columns => :ignore :on_duplicate_columns => proc { |columns| arbitrary_condition? ? :raise : :warn }
You may also configure duplicate columns handling for a specific dataset:
ds.on_duplicate_columns(:warn) ds.on_duplicate_columns(:raise) ds.on_duplicate_columns(:ignore) ds.on_duplicate_columns { |columns| arbitrary_condition? ? :raise : :warn } ds.on_duplicate_columns(proc { |columns| arbitrary_condition? ? :raise : :warn })
If :raise is specified, a Sequel::DuplicateColumnError is raised. If :warn is specified, you will receive a warning via `warn`. If a callable is specified, it will be called. If no on_duplicate_columns is specified, the default is :warn.
Related module: Sequel::DuplicateColumnsHandler
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
frozen-string-literal: true
Constants
- ADAPTER_MAP
Hash of adapters that have been used. The key is the adapter scheme symbol, and the value is the Database subclass.
- AdapterNotFound
Error raised when the adapter requested doesn't exist or can't be loaded.
- BeforeHookFailed
Exception class raised when
raise_on_save_failure
is set and a before hook returns false or an around hook doesn't call super or yield.- COLUMN_REF_RE1
- COLUMN_REF_RE2
- COLUMN_REF_RE3
- CheckConstraintViolation
Error raised when Sequel determines a database check constraint has been violated.
- ConstraintViolation
Generic error raised when Sequel determines a database constraint has been violated.
- DATABASES
Array of all databases to which Sequel has connected. If you are developing an application that can connect to an arbitrary number of databases, delete the database objects from this or they will not get garbage collected.
- DEFAULT_INFLECTIONS_PROC
Proc that is instance evaled to create the default inflections for both the model inflector and the inflector extension.
- DatabaseConnectionError
Error raised when the Sequel is unable to connect to the database with the connection parameters it was given.
- DatabaseDisconnectError
Error raised by adapters when they determine that the connection to the database has been lost. Instructs the connection pool code to remove that connection from the pool so that other connections can be acquired automatically.
- DatabaseError
Generic error raised by the database adapters, indicating a problem originating from the database server. Usually raised because incorrect SQL syntax is used.
- ForeignKeyConstraintViolation
Error raised when Sequel determines a database foreign key constraint has been violated.
- InvalidOperation
Error raised on an invalid operation, such as trying to update or delete a joined or grouped dataset.
- InvalidValue
Error raised when attempting an invalid type conversion.
- MAJOR
The major version of Sequel. Only bumped for major changes.
- MINOR
The minor version of Sequel. Bumped for every non-patch level release, generally around once a month.
- MassAssignmentRestriction
Raised when a mass assignment method is called in strict mode with either a restricted column or a column without a setter method.
- NoExistingObject
Exception class raised when
require_modification
is set and an UPDATE or DELETE statement to modify the dataset doesn't modify a single row.- NotNullConstraintViolation
Error raised when Sequel determines a database NOT NULL constraint has been violated.
- OPTS
Frozen hash used as the default options hash for most options.
- PoolTimeout
Error raised when the connection pool cannot acquire a database connection before the timeout.
- Rollback
Error that you should raise to signal a rollback of the current transaction. The transaction block will catch this exception, rollback the current transaction, and won't reraise it (unless a reraise is requested).
- SHARED_ADAPTER_MAP
Hash of shared adapters that have been registered. The key is the adapter scheme symbol, and the value is the Sequel module containing the shared adapter.
- SPLIT_SYMBOL_CACHE
- SerializationFailure
Error raised when Sequel determines a serialization failure/deadlock in the database.
- TINY
The tiny version of Sequel. Usually 0, only bumped for bugfix releases that fix regressions from previous versions.
- UnbindDuplicate
- UndefinedAssociation
Raised when an undefined association is used when eager loading.
- UniqueConstraintViolation
Error raised when Sequel determines a database unique constraint has been violated.
- VERSION
The version of Sequel you are using, as a string (e.g. “2.11.0”)
- VIRTUAL_ROW
Attributes
Sequel converts two digit years in
Date
s and DateTime
s by default, so 01/02/03 is
interpreted at January 2nd, 2003, and 12/13/99 is interpreted as December
13, 1999. You can override this to treat those dates as January 2nd, 0003
and December 13, 0099, respectively, by:
Sequel.convert_two_digit_years = false
Sequel can use either Time
or
DateTime
for times returned from the database. It defaults to
Time
. To change it to DateTime
:
Sequel.datetime_class = DateTime
For ruby versions less than 1.9.2, Time
has a limited range
(1901 to 2038), so if you use datetimes out of that range, you need to
switch to DateTime
. Also, before 1.9.2, Time
can
only handle local and UTC times, not other timezones. Note that
Time
and DateTime
objects have a different API,
and in cases where they implement the same methods, they often implement
them differently (e.g. + using seconds on Time
and days on
DateTime
).
Set whether sequel is being used in single threaded mode. by default, Sequel uses a thread-safe connection pool, which isn't as fast as the single threaded connection pool, and also has some additional thread safety checks. If your program will only have one thread, and speed is a priority, you should set this to true:
Sequel.single_threaded = true
Public Class Methods
Delegate to Sequel::Model, only for backwards compatibility.
# File lib/sequel/model.rb, line 7 def self.cache_anonymous_models Sequel::Deprecation.deprecate("Sequel.cache_anonymous_models", "Use Sequel::Model.cache_anonymous_models") Model.cache_anonymous_models end
Delegate to Sequel::Model, only for backwards compatibility.
# File lib/sequel/model.rb, line 13 def self.cache_anonymous_models=(v) Sequel::Deprecation.deprecate("Sequel.cache_anonymous_models=", "Use Sequel::Model.cache_anonymous_models=") Model.cache_anonymous_models = v end
Returns true if the passed object could be a specifier of conditions, false otherwise. Currently, Sequel considers hashes and arrays of two element arrays as condition specifiers.
Sequel.condition_specifier?({}) # => true Sequel.condition_specifier?([[1, 2]]) # => true Sequel.condition_specifier?([]) # => false Sequel.condition_specifier?([1]) # => false Sequel.condition_specifier?(1) # => false
# File lib/sequel/core.rb, line 72 def self.condition_specifier?(obj) case obj when Hash true when Array !obj.empty? && !obj.is_a?(SQL::ValueList) && obj.all?{|i| i.is_a?(Array) && (i.length == 2)} else false end end
Creates a new database object based on the supplied connection string and optional arguments. The specified scheme determines the database class used, and the rest of the string specifies the connection options. For example:
DB = Sequel.connect('sqlite:/') # Memory database DB = Sequel.connect('sqlite://blog.db') # ./blog.db DB = Sequel.connect('sqlite:///blog.db') # /blog.db DB = Sequel.connect('postgres://user:password@host:port/database_name') DB = Sequel.connect('sqlite:///blog.db', :max_connections=>10)
You can also pass a single options hash:
DB = Sequel.connect(:adapter=>'sqlite', :database=>'./blog.db')
If a block is given, it is passed the opened Database
object,
which is closed when the block exits. For example:
Sequel.connect('sqlite://blog.db'){|db| puts db[:users].count}
If a block is not given, a reference to this database will be held in
Sequel::DATABASES
until it is removed manually. This is by
design, and used by Sequel::Model
to pick the default
database. It is recommended to pass a block if you do not want the
resulting Database object to remain in
memory until the process terminates.
For details, see the “Connecting to a Database” guide. To set up a master/slave or sharded database connection, see the “Master/Slave Databases and Sharding” guide.
# File lib/sequel/core.rb, line 115 def self.connect(*args, &block) Database.connect(*args, &block) end
Convert the exception
to the given class. The given class
should be Sequel::Error
or a subclass. Returns an instance of
klass
with the message and backtrace of
exception
.
# File lib/sequel/core.rb, line 128 def self.convert_exception_class(exception, klass) return exception if exception.is_a?(klass) e = klass.new("#{exception.class}: #{exception.message}") e.wrapped_exception = exception e.set_backtrace(exception.backtrace) e end
Assume the core extensions are not loaded by default, if the core_extensions extension is loaded, this will be overridden.
# File lib/sequel/core.rb, line 121 def self.core_extensions? false end
Load all Sequel extensions given. Extensions are
just files that exist under sequel/extensions
in the load
path, and are just required. Generally, extensions modify the behavior of
Database
and/or Dataset
, but Sequel ships with some extensions that modify other
classes that exist for backwards compatibility. In some cases, requiring an
extension modifies classes directly, and in others, it just loads a module
that you can extend other classes with. Consult the documentation for each
extension you plan on using for usage.
Sequel.extension(:schema_dumper) Sequel.extension(:pagination, :query)
# File lib/sequel/core.rb, line 146 def self.extension(*extensions) extensions.each{|e| Kernel.require "sequel/extensions/#{e}"} end
Set the method to call on identifiers going into the database. This affects the literalization of identifiers by calling this method on them before they are input. Sequel upcases identifiers in all SQL strings for most databases, so to turn that off:
Sequel.identifier_input_method = nil
to downcase instead:
Sequel.identifier_input_method = :downcase
Other String instance methods work as well.
# File lib/sequel/core.rb, line 161 def self.identifier_input_method=(value) # SEQUEL5: Remove Database.identifier_input_method = value end
Set the method to call on identifiers coming out of the database. This affects the literalization of identifiers by calling this method on them when they are retrieved from the database. Sequel downcases identifiers retrieved for most databases, so to turn that off:
Sequel.identifier_output_method = nil
to upcase instead:
Sequel.identifier_output_method = :upcase
Other String instance methods work as well.
# File lib/sequel/core.rb, line 178 def self.identifier_output_method=(value) # SEQUEL5: Remove Database.identifier_output_method = value end
Yield the Inflections module if a block is given, and return the Inflections module.
# File lib/sequel/model/inflections.rb, line 6 def self.inflections yield Inflections if block_given? Inflections end
The exception classed raised if there is an error parsing JSON. This can be overridden to use an alternative json implementation.
# File lib/sequel/core.rb, line 185 def self.json_parser_error_class JSON::ParserError end
The preferred method for writing Sequel migrations, using a DSL:
Sequel.migration do up do create_table(:artists) do primary_key :id String :name end end down do drop_table(:artists) end end
Designed to be used with the Migrator
class, part of the
migration
extension.
# File lib/sequel/extensions/migration.rb, line 289 def self.migration(&block) MigrationDSL.create(&block) end
Convert given object to json and return the result. This can be overridden to use an alternative json implementation.
# File lib/sequel/core.rb, line 191 def self.object_to_json(obj, *args) obj.to_json(*args) end
Parse the string as JSON and return the result. This can be overridden to use an alternative json implementation.
# File lib/sequel/core.rb, line 197 def self.parse_json(json) JSON.parse(json, :create_additions=>false) end
Set whether to quote identifiers for all databases by default. By default, Sequel quotes identifiers in all SQL strings, so to turn that off:
Sequel.quote_identifiers = false
# File lib/sequel/core.rb, line 205 def self.quote_identifiers=(value) # SEQUEL5: Remove Database.quote_identifiers = value end
Convert each item in the array to the correct type, handling multi-dimensional arrays. For each element in the array or subarrays, call the converter, unless the value is nil.
# File lib/sequel/core.rb, line 213 def self.recursive_map(array, converter) array.map do |i| if i.is_a?(Array) recursive_map(i, converter) elsif !i.nil? converter.call(i) end end end
Require all given files
which should be in the same or a
subdirectory of this file. If a subdir
is given, assume all
files
are in that subdir. This is used to ensure that the
files loaded are from the same version of Sequel
as this file.
# File lib/sequel/core.rb, line 227 def self.require(files, subdir=nil) Array(files).each{|f| super("#{File.dirname(__FILE__).untaint}/#{"#{subdir}/" if subdir}#{f}")} end
Splits the symbol into three parts, if symbol splitting is enabled. Each part will either be a string or nil. If symbol splitting is disabled, returns an array with the first and third parts being nil, and the second part beind a string version of the symbol.
For columns, these parts are the table, column, and alias. For tables, these parts are the schema, table, and alias.
# File lib/sequel/core.rb, line 243 def self.split_symbol(sym) unless v = Sequel.synchronize{SPLIT_SYMBOL_CACHE[sym]} if split_symbols? v = case s = sym.to_s when COLUMN_REF_RE1 [$1.freeze, $2.freeze, $3.freeze].freeze when COLUMN_REF_RE2 [nil, $1.freeze, $2.freeze].freeze when COLUMN_REF_RE3 [$1.freeze, $2.freeze, nil].freeze else [nil, s.freeze, nil].freeze end else v = [nil,sym.to_s.freeze,nil].freeze end Sequel.synchronize{SPLIT_SYMBOL_CACHE[sym] = v} end v end
Sequel by default will split symbols, treating:
:table__column # table.column :column___alias # column AS alias :table__column___alias # table.column AS alias
This can cause problems if any identifiers in the database use a double or triple underscore. When Sequel was first created, using symbols with double or triple underscores was the only way to represent qualified or aliased identifiers. Sequel now offers many ways to create qualified and aliased identifiers, so there is less of a need for this now. This allows you to turn off symbol splitting, potentially avoiding problems if you have identifiers that use double underscores:
Sequel.split_symbols = false
Note that Sequel::Database instances do their own caching of literalized symbols, and changing this setting does not affect those caches. It is recommended that if you want to change this setting, you do so directly after requiring Sequel, before creating any Sequel::Database instances.
Also note that disabling symbol splitting will also disable the handling of double underscores in virtual row methods, causing such methods to yield regular identifers instead of qualified identifiers. To make sure the code works when splitting symbols is both disabled and enabled, you can use Sequel::SQL::QualifyingMethods#[].
# Sequel.split_symbols = true Sequel.expr{table__column} # table.column Sequel.expr{table[:column]} # table.column # Sequel.split_symbols = false Sequel.expr{table__column} # table__column Sequel.expr{table[:column]} # table.column
# File lib/sequel/core.rb, line 298 def self.split_symbols=(v) Sequel.synchronize{SPLIT_SYMBOL_CACHE.clear} @split_symbols = v end
Whether Sequel currently splits symbols into qualified/aliased identifiers.
# File lib/sequel/core.rb, line 304 def self.split_symbols? @split_symbols end
Converts the given string
into a Date
object.
Sequel.string_to_date('2010-09-10') # Date.civil(2010, 09, 10)
# File lib/sequel/core.rb, line 311 def self.string_to_date(string) begin Date.parse(string, Sequel.convert_two_digit_years) rescue => e raise convert_exception_class(e, InvalidValue) end end
Converts the given string
into a Time
or
DateTime
object, depending on the value of
Sequel.datetime_class
.
Sequel.string_to_datetime('2010-09-10 10:20:30') # Time.local(2010, 09, 10, 10, 20, 30)
# File lib/sequel/core.rb, line 323 def self.string_to_datetime(string) begin if datetime_class == DateTime DateTime.parse(string, convert_two_digit_years) else datetime_class.parse(string) end rescue => e raise convert_exception_class(e, InvalidValue) end end
Converts the given string
into a Sequel::SQLTime
object.
v = Sequel.string_to_time('10:20:30') # Sequel::SQLTime.parse('10:20:30') DB.literal(v) # => '10:20:30'
# File lib/sequel/core.rb, line 339 def self.string_to_time(string) begin SQLTime.parse(string) rescue => e raise convert_exception_class(e, InvalidValue) end end
Unless in single threaded mode, protects access to any mutable global data structure in Sequel. Uses a non-reentrant mutex, so calling code should be careful.
# File lib/sequel/core.rb, line 353 def self.synchronize(&block) @single_threaded ? yield : @data_mutex.synchronize(&block) end
Uses a transaction on all given databases with the given options. This:
Sequel.transaction([DB1, DB2, DB3]){}
is equivalent to:
DB1.transaction do DB2.transaction do DB3.transaction do end end end
except that if Sequel::Rollback is raised by the block, the transaction is rolled back on all databases instead of just the last one.
Note that this method cannot guarantee that all databases will commit or rollback. For example, if DB3 commits but attempting to commit on DB2 fails (maybe because foreign key checks are deferred), there is no way to uncommit the changes on DB3. For that kind of support, you need to have two-phase commit/prepared transactions (which Sequel supports on some databases).
# File lib/sequel/core.rb, line 379 def self.transaction(dbs, opts=OPTS, &block) unless opts[:rollback] rescue_rollback = true opts = Hash[opts].merge!(:rollback=>:reraise) end pr = dbs.reverse.inject(block){|bl, db| proc{db.transaction(opts, &bl)}} if rescue_rollback begin pr.call rescue Sequel::Rollback nil end else pr.call end end
The version of Sequel you are using, as a string (e.g. “2.11.0”)
# File lib/sequel/version.rb, line 17 def self.version VERSION end
If the supplied block takes a single argument, yield an
SQL::VirtualRow
instance to the block argument. Otherwise,
evaluate the block in the context of a SQL::VirtualRow
instance.
Sequel.virtual_row{a} # Sequel::SQL::Identifier.new(:a) Sequel.virtual_row{|o| o.a{}} # Sequel::SQL::Function.new(:a)
# File lib/sequel/core.rb, line 403 def self.virtual_row(&block) vr = VIRTUAL_ROW case block.arity when -1, 0 vr.instance_exec(&block) else block.call(vr) end end
Private Class Methods
Helper method that the database adapter class methods that are added to Sequel via metaprogramming use to parse arguments.
# File lib/sequel/core.rb, line 417 def self.adapter_method(adapter, *args, &block) options = args.last.is_a?(Hash) ? args.pop : {} opts = {:adapter => adapter.to_sym} opts[:database] = args.shift if args.first.is_a?(String) if args.any? raise ::Sequel::Error, "Wrong format of arguments, either use (), (String), (Hash), or (String, Hash)" end connect(opts.merge(options), &block) end