module Sequel::SequelMethods
Sequel doesn't pay much attention to timezones by default, but you can set it to handle timezones if you want. There are three separate timezone settings:
All three timezones have getter and setter methods. You can set all three
timezones to the same value at once via
Sequel.default_timezone=
.
The only timezone values that are supported by default are
:utc
(convert to UTC), :local
(convert to local
time), and nil
(don't convert). If you need to convert to
a specific timezone, or need the timezones being used to change based on
the environment (e.g. current user), you need to use the
named_timezones
extension (and use DateTime
as
the datetime_class
). Sequel also
ships with a thread_local_timezones
extensions which allows
each thread to have its own timezone values for each of the timezones.
Attributes
The timezone you want the application to use. This is the timezone that incoming times from the database and typecasting are converted to.
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
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
The timezone that incoming data that Sequel needs to typecast is assumed to be already in (if they don't include an offset).
Public Instance Methods
Convert the given Time
/DateTime
object into the
database timezone, used when literalizing objects in an SQL string.
# File lib/sequel/timezones.rb, line 49 def application_to_database_timestamp(v) convert_output_timestamp(v, Sequel.database_timezone) 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 82 def 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, or use the keep_reference: false
Database option.
For details, see the “Connecting to a Database” guide. To set up a primary/replica or sharded database connection, see the “Primary/Replica Database Configurations and Sharding” guide.
# File lib/sequel/core.rb, line 122 def 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 135 def 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
Converts the object to the given output_timezone
.
# File lib/sequel/timezones.rb, line 54 def convert_output_timestamp(v, output_timezone) if output_timezone if v.is_a?(DateTime) case output_timezone when :utc v.new_offset(0) when :local v.new_offset(local_offset_for_datetime(v)) else convert_output_datetime_other(v, output_timezone) end else case output_timezone when :utc v.getutc when :local v.getlocal else convert_output_time_other(v, output_timezone) end end else v end end
Converts the given object from the given input timezone to the
application_timezone
using
convert_input_timestamp
and
convert_output_timestamp
.
# File lib/sequel/timezones.rb, line 83 def convert_timestamp(v, input_timezone) if v.is_a?(Date) && !v.is_a?(DateTime) # Dates handled specially as they are assumed to already be in the application_timezone if datetime_class == DateTime DateTime.civil(v.year, v.month, v.day, 0, 0, 0, application_timezone == :local ? Rational(Time.local(v.year, v.month, v.day).utc_offset, 86400) : 0) else Time.public_send(application_timezone == :utc ? :utc : :local, v.year, v.month, v.day) end else convert_output_timestamp(convert_input_timestamp(v, input_timezone), application_timezone) end rescue InvalidValue raise rescue => e raise convert_exception_class(e, InvalidValue) 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 128 def core_extensions? false end
The current concurrency primitive, Thread.current by default.
# File lib/sequel/core.rb, line 144 def current Thread.current end
Convert the given object into an object of
Sequel.datetime_class
in the
application_timezone
. Used when converting datetime/timestamp
columns returned by the database.
# File lib/sequel/timezones.rb, line 103 def database_to_application_timestamp(v) convert_timestamp(v, Sequel.database_timezone) end
Sets the database, application, and typecasting timezones to the given timezone.
# File lib/sequel/timezones.rb, line 108 def default_timezone=(tz) self.database_timezone = tz self.application_timezone = tz self.typecast_timezone = tz end
The elapsed seconds since the given timer object was created. The timer object should have been created via Sequel.start_timer.
# File lib/sequel/core.rb, line 334 def elapsed_seconds_since(timer) start_timer - timer end
Load all Sequel extensions given. Extensions
are just files that exist under sequel/extensions
in the load
path, and are just required.
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(:blank) Sequel.extension(:core_extensions, :named_timezones)
# File lib/sequel/core.rb, line 156 def extension(*extensions) extensions.each{|e| orig_require("sequel/extensions/#{e}")} 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 162 def json_parser_error_class JSON::ParserError 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 168 def object_to_json(obj, *args, &block) obj.to_json(*args, &block) end
Alias of original require method, as Sequel.require does a relative require for backwards compatibility.
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 174 def parse_json(json) JSON.parse(json, :create_additions=>false) 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 192 def 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
For backwards compatibility only. require_relative should be used instead.
# File lib/sequel/core.rb, line 203 def require(files, subdir=nil) # Use Kernel.require_relative to work around JRuby 9.0 bug Array(files).each{|f| Kernel.require_relative "#{"#{subdir}/" if subdir}#{f}"} end
Splits the symbol into three parts, if symbol splitting is enabled (not the default). 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 215 def split_symbol(sym) unless v = Sequel.synchronize{SPLIT_SYMBOL_CACHE[sym]} if split_symbols? v = case s = sym.to_s when /\A((?:(?!__).)+)__((?:(?!___).)+)___(.+)\z/ [$1.freeze, $2.freeze, $3.freeze].freeze when /\A((?:(?!___).)+)___(.+)\z/ [nil, $1.freeze, $2.freeze].freeze when /\A((?:(?!__).)+)__(.+)\z/ [$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
Setting this to true enables Sequel's historical behavior of splitting symbols on double or triple underscores:
:table__column # table.column :column___alias # column AS alias :table__column___alias # table.column AS alias
It is only recommended to turn this on for backwards compatibility until such symbols have been converted to use newer Sequel APIs such as:
Sequel[:table][:column] # table.column Sequel[:column].as(:alias) # column AS alias Sequel[:table][:column].as(:alias) # table.column AS alias
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.
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:
# 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 266 def 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 272 def split_symbols? @split_symbols end
A timer object that can be passed to Sequel.elapsed_seconds_since to return the number of seconds elapsed.
# File lib/sequel/core.rb, line 321 def start_timer Process.clock_gettime(Process::CLOCK_MONOTONIC) 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 279 def string_to_date(string) Date.parse(string, Sequel.convert_two_digit_years) rescue => e raise convert_exception_class(e, InvalidValue) 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 289 def string_to_datetime(string) 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
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 303 def string_to_time(string) SQLTime.parse(string) rescue => e raise convert_exception_class(e, InvalidValue) 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. In general, this should only be used around the minimal possible code such as Hash#[], Hash#[]=, Hash#delete, Array#<<, and Array#delete.
# File lib/sequel/core.rb, line 314 def synchronize(&block) @single_threaded ? yield : @data_mutex.synchronize(&block) end
If a mutex is given, synchronize access using it. If nil is given, just yield to the block. This is designed for cases where a mutex may or may not be provided.
# File lib/sequel/core.rb, line 181 def synchronize_with(mutex) if mutex mutex.synchronize{yield} else yield end 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 360 def 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
Convert the given object into an object of
Sequel.datetime_class
in the
application_timezone
. Used when typecasting values when
assigning them to model datetime attributes.
# File lib/sequel/timezones.rb, line 117 def typecast_to_application_timestamp(v) convert_timestamp(v, Sequel.typecast_timezone) 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 384 def virtual_row(&block) vr = VIRTUAL_ROW case block.arity when -1, 0 vr.instance_exec(&block) else block.call(vr) end end
Private Instance Methods
Return a hash of date information parsed from the given string.
# File lib/sequel/core.rb, line 397 def _date_parse(string) Date._parse(string) end
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 403 def adapter_method(adapter, *args, &block) options = args.last.is_a?(Hash) ? args.pop : OPTS 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
Convert the given DateTime
to the given input_timezone,
keeping the same time and just modifying the timezone.
# File lib/sequel/timezones.rb, line 125 def convert_input_datetime_no_offset(v, input_timezone) case input_timezone when nil, :utc v # DateTime assumes UTC if no offset is given when :local offset = local_offset_for_datetime(v) v.new_offset(offset) - offset else convert_input_datetime_other(v, input_timezone) end end
Convert the given DateTime
to the given input_timezone that is
not supported by default (i.e. one other than nil
,
:local
, or :utc
). Raises an
InvalidValue
by default. Can be overridden in extensions.
# File lib/sequel/timezones.rb, line 140 def convert_input_datetime_other(v, input_timezone) raise InvalidValue, "Invalid input_timezone: #{input_timezone.inspect}" end
Convert the given Time
to the given input_timezone that is not
supported by default (i.e. one other than nil
,
:local
, or :utc
). Raises an
InvalidValue
by default. Can be overridden in extensions.
# File lib/sequel/timezones.rb, line 147 def convert_input_time_other(v, input_timezone) raise InvalidValue, "Invalid input_timezone: #{input_timezone.inspect}" end
Converts the object from a String
, Array
,
Date
, DateTime
, or Time
into an
instance of Sequel.datetime_class
. If given an array or a
string that doesn't contain an offset, assume that the array/string is
already in the given input_timezone
.
# File lib/sequel/timezones.rb, line 154 def convert_input_timestamp(v, input_timezone) case v when String v2 = Sequel.string_to_datetime(v) if !input_timezone || _date_parse(v).has_key?(:offset) v2 else # Correct for potentially wrong offset if string doesn't include offset if v2.is_a?(DateTime) convert_input_datetime_no_offset(v2, input_timezone) else case input_timezone when nil, :local v2 when :utc (v2 + v2.utc_offset).utc else convert_input_time_other((v2 + v2.utc_offset).utc, input_timezone) end end end when Array y, mo, d, h, mi, s, ns, off = v if datetime_class == DateTime s += Rational(ns, 1000000000) if ns if off DateTime.civil(y, mo, d, h, mi, s, off) else convert_input_datetime_no_offset(DateTime.civil(y, mo, d, h, mi, s), input_timezone) end elsif off s += Rational(ns, 1000000000) if ns Time.new(y, mo, d, h, mi, s, (off*86400).to_i) else case input_timezone when nil, :local Time.local(y, mo, d, h, mi, s, (ns ? ns / 1000.0 : 0)) when :utc Time.utc(y, mo, d, h, mi, s, (ns ? ns / 1000.0 : 0)) else convert_input_time_other(Time.utc(y, mo, d, h, mi, s, (ns ? ns / 1000.0 : 0)), input_timezone) end end when Hash ary = [:year, :month, :day, :hour, :minute, :second, :nanos].map{|x| (v[x] || v[x.to_s]).to_i} if (offset = (v[:offset] || v['offset'])) ary << offset end convert_input_timestamp(ary, input_timezone) when Time if datetime_class == DateTime v.to_datetime else v end when DateTime if datetime_class == DateTime v else v.to_time end else raise InvalidValue, "Invalid convert_input_timestamp type: #{v.inspect}" end end
Convert the given DateTime
to the given output_timezone that
is not supported by default (i.e. one other than nil
,
:local
, or :utc
). Raises an
InvalidValue
by default. Can be overridden in extensions.
# File lib/sequel/timezones.rb, line 223 def convert_output_datetime_other(v, output_timezone) raise InvalidValue, "Invalid output_timezone: #{output_timezone.inspect}" end
Convert the given Time
to the given output_timezone that is
not supported by default (i.e. one other than nil
,
:local
, or :utc
). Raises an
InvalidValue
by default. Can be overridden in extensions.
# File lib/sequel/timezones.rb, line 230 def convert_output_time_other(v, output_timezone) raise InvalidValue, "Invalid output_timezone: #{output_timezone.inspect}" end
Convert the timezone setter argument. Returns argument given by default, exists for easier overriding in extensions.
# File lib/sequel/timezones.rb, line 236 def convert_timezone_setter_arg(tz) tz end
Takes a DateTime dt, and returns the correct local offset for that dt, daylight savings included, in fraction of a day.
# File lib/sequel/timezones.rb, line 241 def local_offset_for_datetime(dt) time_offset_to_datetime_offset Time.local(dt.year, dt.month, dt.day, dt.hour, dt.min, dt.sec).utc_offset end
Caches offset conversions to avoid excess Rational math.
# File lib/sequel/timezones.rb, line 246 def time_offset_to_datetime_offset(offset_secs) if offset = Sequel.synchronize{@local_offsets[offset_secs]} return offset end Sequel.synchronize{@local_offsets[offset_secs] = Rational(offset_secs, 86400)} end