module Sequel

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 Sequel.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.

The date_parse_input_handler extension allows for configuring how input to date parsing methods should be handled. By default, the extension does not change behavior. However, you can use the Sequel.date_parse_input_handler method to support custom handling of input strings to the date parsing methods. For example, if you want to implement a length check to prevent denial of service vulnerabilities in older versions of Ruby, you can do:

Sequel.extension :date_parse_input_handler
Sequel.date_parse_input_handler do |string|
  raise Sequel::InvalidValue, "string length (200) exceeds the limit 128" if string.bytesize > 128
  string
end

You can also use Sequel.date_parse_input_handler to modify the string that will be passed to the parsing methods. For example, you could truncate it:

Sequel.date_parse_input_handler do |string|
  string.b[0, 128]
end

Be aware that modern versions of Ruby will raise an exception if date parsing input exceeds 128 bytes.

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

or into individual datasets:

ds = DB[:items].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: lambda{|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(lambda{|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

:nocov:

The pg_range extension adds support for the PostgreSQL 9.2+ range types to Sequel. PostgreSQL range types are similar to ruby's Range class, representating an array of values. However, they are more flexible than ruby's ranges, allowing exclusive beginnings and endings (ruby's range only allows exclusive endings).

When PostgreSQL range values are retreived, they are parsed and returned as instances of Sequel::Postgres::PGRange. PGRange mostly acts like a Range, but it's not a Range as not all PostgreSQL range type values would be valid ruby ranges. If the range type value you are using is a valid ruby range, you can call PGRange#to_range to get a Range. However, if you call PGRange#to_range on a range type value uses features that ruby's Range does not support, an exception will be raised.

In addition to the parser, this extension comes with literalizers for PGRange and Range, so they can be used in queries and as bound variables.

To turn an existing Range into a PGRange, use Sequel.pg_range:

Sequel.pg_range(range)

If you have loaded the core_extensions extension, or you have loaded the core_refinements extension and have activated refinements for the file, you can also use Range#pg_range:

range.pg_range

You may want to specify a specific range type:

Sequel.pg_range(range, :daterange)
range.pg_range(:daterange)

If you specify the range database type, Sequel will automatically cast the value to that type when literalizing.

To use this extension, load it into the Database instance:

DB.extension :pg_range

See the schema modification guide for details on using range type columns in CREATE/ALTER TABLE statements.

This extension makes it easy to add support for other range types. In general, you just need to make sure that the subtype is handled and has the appropriate converter installed. For user defined types, you can do this via:

DB.add_conversion_proc(subtype_oid){|string| }

Then you can call Sequel::Postgres::PGRange::DatabaseMethods#register_range_type to automatically set up a handler for the range type. So if you want to support the timerange type (assuming the time type is already supported):

DB.register_range_type('timerange')

This extension integrates with the pg_array extension. If you plan to use arrays of range types, load the pg_array extension before the pg_range extension:

DB.extension :pg_array, :pg_range

Related module: Sequel::Postgres::PGRange

The round_timestamps extension will automatically round timestamp values to the database's supported level of precision before literalizing them.

For example, if the database supports millisecond precision, and you give it a Time value with microsecond precision, it will round it appropriately:

Time.at(1405341161.917999982833862)
# default: 2014-07-14 14:32:41.917999
# with extension: 2014-07-14 14:32:41.918000

The round_timestamps extension correctly deals with databases that support millisecond or second precision. In addition to handling Time values, it also handles DateTime values and Sequel::SQLTime values (for the TIME type).

To round timestamps for a single dataset:

ds = ds.extension(:round_timestamps)

To round timestamps for all datasets on a single database:

DB.extension(:round_timestamps)

Related module: Sequel::Dataset::RoundTimestamps