J
Jeremy Evans
Sequel is a lightweight database access toolkit for Ruby.
* Sequel provides thread safety, connection pooling and a concise DSL
for constructing database queries and table schemas.
* Sequel also includes a lightweight but comprehensive ORM layer for
mapping records to Ruby objects and handling associated records.
* Sequel supports advanced database features such as prepared
statements, bound variables, stored procedures, master/slave
configurations, and database sharding.
* Sequel makes it easy to deal with multiple records without having
to break your teeth on SQL.
* Sequel currently has adapters for ADO, Amalgalite, DataObjects,
DB2, DBI, Firebird, Informix, JDBC, MySQL, ODBC, OpenBase, Oracle,
PostgreSQL and SQLite3.
Sequel 3.12.0 has been released and should be available on the gem
mirrors.
= Migration Changes
* A TimestampMigrator has been added to Sequel, and is
automatically used if any migration has a version greater than
20000100. This migrator operates similarly to the default
ActiveRecord migrator, in that it allows missing migrations.
It differs from the ActiveRecord migrator in that it supports
migrations with the same timestamp/version as well as a wide
variety of timestamp formats (though the ActiveRecord default
of YYYYMMDDHHMMSS is recommended and should be used in
portable code).
Sequel still defaults to the old migrator, but you can use the
new one without making changes to your old migrations. Just
make sure your new migration starts with a version greater than
20000100, and Sequel will automatically convert the previous
schema table to the new format.
* A new migration DSL was added:
Sequel.migration do
up do
end
down do
end
end
The old style of using a Sequel::Migration subclass is still
supported, but it is recommended that new code use the new DSL.
* The default migrator also had significant issues fixed. First,
it now saves the migration version after each migration, instead
of after all migrations, which means Sequel won't attempt to
apply already applied migrations if there was previously an error
when applying multiple migrations at once on a database that
didn't support transactional schema modification.
Second, duplicate migration versions in the default migrator now
raise an exception, as do missing migration versions. Neither
should happen when using the default migrator, which requires
consecutive integer versions, similar to the old ActiveRecord
migrator.
* Execution times for migrations are now logged to the database's
loggers.
= New Plugins
* A sharding plugin has been added that allows model objects to
work well with sharded databases. When using it, model objects
know which shard they were retrieved from, so when you save
the object, it is saved back to that shard. The sharding plugin
also works with associations, so associated records are retrieved
from the same shard the main object was retreived from. The
sharding plugin also works with both methods of eager loading, and
provides methods that you can use to create objects on specific
shards.
* An update_primary_key plugin has been added that allows Sequel
to work correctly if you modify the primary key of a model object.
This should not be necessary if you are using surrogate keys, but
if your database uses natural primary keys which can change, this
should be helpful.
* An association_pks plugin has been added that adds association_pks
and association_pks= methods to model objects for both one_to_many
and many_to_many associations. The association_pks method returns
an array of primary key values for the associated objects, and
the association_pks= method modifies the database to ensure that
the object is only associated to the objects specified by the
array of primary keys provided to it.
* A string_stripper plugin has been added that strips all strings
that are assigned to attribute values. This is useful for web
applications where you want to easily remove leading and trailing
whitespace in form entries before storing them in the database.
* A skip_create_refresh plugin has been added that skips the refresh
of after you save a new model object. On most databases, Sequel
refreshes the model object after inserting it in order to get
values for all of the columns. For performance reasons, you can
use this plugin to skip the refresh if it isn't necessary for you.
= Other New Features
* Sequel::Model#set_fields and update_fields were added. These
methods have a similar API to set_only and update_only, but they
operate differently. While set_only and update_only operate over
the hash, these methods operate over the array of fields,
so they don't raise errors if the hash contains fields not
in the array:
params = {:a=>1, :b=>2, :c=>3}
album = Album[1]
# raises Error because :a is not in the fields
album.set_only(params, [:b, :c])
# Just sets the value of album.b and album.c
album.set_fields(params, [:b, :c])
Other than handling entries in the hash that aren't in the array,
set_fields and update_fields also handle entries not in the hash
differently:
# Doesn't modify the object, since the hash is empty
album.set_only({}, [:b, :c])
# Sets album.b and album.c to nil, since they aren't in the hash
album.set_fields({}, [:b, :c])
* The :eager_loader association option has a new API, though the
previous API still works. Instead of accepting three arguments,
it can now accept a single hash argument, which will use the
:key_hash, :rows, and :association keys for the previous three
arguments. The hash will also contain a :self key whose value
is the dataset doing the eager load, which was not possible to
determine using the old API.
* Sequel::SQL::Expression#hash has been added so that the objects
are now safe to use as hash keys.
* A Dataset#order_prepend method has been added allowing you to
prepend to an existing order. This is useful if want to modify
a dataset's order such that it first orders by the columns you
provide, but for any rows where the columns you provide are
equal, uses the existing order to further order the dataset:
ds.order
albums__name).order_prependartists__name)
# ORDER BY artists.name, albums.name
* When creating foreign key columns, you can now use a :deferrable
option to set up a foreign key constraint that is not checked
until the end of the transaction:
DB.create_tablealbums) do
primary_key :id
String :name
foreign_key :artist_id, :artists, :deferrable=>true
end
* many_to_many associations now support a :join_table_block option
that is used by the add/remove/remove_all methods. It can modify
the dataset to ensure that certain columns are included when
inserting or to add a filter so that only certain records are
deleted. It's useful if you have a many_to_many association that
is filtered to only a subset of the matching rows in the join
table.
* The single_table_inheritance plugin now supports :model_map and
:key_map options to set up a custom mapping of column values to
model classes. For simple situations such as when you are mapping
integer values to certain classes, a :model_map hash is sufficient:
Employee.plugin :single_table_inheritance, :type_id,
:model_map=>{1=>:Staff, 2=>:Manager}
Here the :model_map keys are type_id column values, and the
:model_map values are symbols or strings specifying class names.
For more complex conditions, you can use a pair of procs:
Employee.plugin :single_table_inheritance, :type_name,
:model_map=>proc{|v| v.reverse},
:key_map=>proc{|klass| klass.name.reverse}
Here the type_name column is a string column holding the reverse
of the class's name.
* The single_table_inheritance plugin now correctly sets up subclass
filters for middle tables in a class hierarchy with more than 2
levels. For example, with this code:
class Employee < Sequel::Model; end
Employee.plugin :single_table_inheritance, :kind
class Manager < Employee; end
class Executive < Manager; end
Sequel previously would not return Executives if you used
Manager.all. It now correctly recognizes subclasses so that it
will return both Managers and Executives.
* Sequel::Model.qualified_primary_key_hash has been added, giving
you a hash that can be used for filtering. It is similar to
primary_key_hash, but it qualifies the keys with the model's
table. It's useful if you have joined the table to another table
that has columns with the same name, but you want to only look
for a single model object in that dataset.
* For consistency, you can now use Dataset#order_append as an alias
for order_more.
= Other Improvements
* Sequel now correctly removes schema entries when altering tables.
Previously, some adapters that had to query the existing schema
when altering tables resulted in the previous schema being cached.
* Sequel::Model::Errors#on now always returns nil if there are no
errors on the attribute. Previously, it would return an empty
array in certain cases. Additionally, Sequel::Model::Errors#empty?
now returns true if there are no errors, where it certain cases
it would return false even if there were no errors.
* The schema_dumper extension now works with tables specified as
Sequel::SQL::Identifiers.
* Sequel now recognizes the timestamp(N) with(out) time zone column
type.
* The lazy_attributes plugin no longer requires the core extensions
to work correctly.
* DatabaseDisconnectError support has been added to the ODBC adapter,
allowing Sequel to detect disconnects and remove the connection
from the connection pool.
* A leak of JDBC statement objects when using transactions was
fixed in the jdbc adapter.
* The jdbc adapter now gives a nicer error message if you use a
connection string that it doesn't recognize and there is an error
when connecting.
* Temporary table creation was fixed on Microsoft SQL Server, but
it is not recommended as it changes the name of the table. If
you use Microsoft SQL Server, you should prefix your temporary
table names with # and use the regular create table method.
* A large number of guides were added to Sequel to make it easier
for new and existing users to learn more about Sequel. The
following guides were added:
* Querying in Sequel
* Migration and Schema Modification
* Model Hooks
* Model Validations
* Sequel for SQL Users
* Sequel for ActiveRecord Users
* RDoc section support was added to Sequel:atabase, making the
method documentation easier to read.
= Backwards Compatibility
* Sequel:atabase now defines the indexes and tables methods, even
if the adapter does not implement them, similar to how connect
and execute are defined. Previously, you could use respond_to? to
check if the adapter supported them, now they raise
Sequel::NotImplemented if the database adapter does not implement
them.
* Sequel used to raise NotImplementedError in certain default
definitions of methods inside Sequel:atabase and Sequel:ataset,
when the methods were supposed to be overridden in subclasses.
Sequel now uses a Sequel::NotImplemented exception class for these
exceptions, which is a subclass of Sequel::Error.
* Sequel no longer applies all association options to the dataset
used to remove all many_to_many associated objects. You should
use the new :join_table_block option to get similar behavior if
you were filtering the many_to_many association based on columns
in the join table and you wanted remove_all to only remove the
related columns.
* Sequel now calls certain before and after hook actions in plugins
in a different order than before. This should not have an effect
unless you were relying on them being called in the previous order.
Now, when overriding before hooks in plugins, Sequel always does
actions before calling super, and when overriding after hooks in
plugins, Sequel always does actions after calling super.
* The hook_class_methods plugin no longer skips later after hooks if
a previous after hook returns false. That behavior now only occurs
for before hooks.
* Sequel now only removes primary key values when updating objects if
you are saving the entire object and you have not modified the
values of the primary keys. Previously, Sequel would remove
primary key values when updating even if you specified the primary
key column specifically or the primary key column was modified and
you used save_changes/update.
* Sequel now uses explicit methods instead of aliases for certain
methods. This should only affect you if for example you overrode
Dataset#group to do one thing and wanted Dataset#group_by to do
the default action. Now, Dataset#group_by, and methods like it, are
explicit methods that just call the methods they previously
aliased. This also means that if you were overriding Dataset#group
and explicitly aliasing group_by to it, you no longer need the
alias.
* The single_table_inheritance plugin now uses IN instead of = for
subclass filters. This could lead to poor performance if the
database has a very bad query planner.
* The private transaction_statement_object method was removed from
the JDBC adapter, and Sequel will no longer check for the presence
of the method in the transaction code.
* The Sequel::Migrator object is now a class instead of a module, and
has been pretty much rewritten. If you were using any methods of
it besides apply and run, they no longer work.
Thanks,
Jeremy
* {Website}[http://sequel.rubyforge.org]
* {Source code}[http://github.com/jeremyevans/sequel]
* {Blog}[http://sequel.heroku.com]
* {Bug tracking}[http://code.google.com/p/ruby-sequel/issues/list]
* {Google group}[http://groups.google.com/group/sequel-talk]
* {RDoc}[http://sequel.rubyforge.org/rdoc]
* Sequel provides thread safety, connection pooling and a concise DSL
for constructing database queries and table schemas.
* Sequel also includes a lightweight but comprehensive ORM layer for
mapping records to Ruby objects and handling associated records.
* Sequel supports advanced database features such as prepared
statements, bound variables, stored procedures, master/slave
configurations, and database sharding.
* Sequel makes it easy to deal with multiple records without having
to break your teeth on SQL.
* Sequel currently has adapters for ADO, Amalgalite, DataObjects,
DB2, DBI, Firebird, Informix, JDBC, MySQL, ODBC, OpenBase, Oracle,
PostgreSQL and SQLite3.
Sequel 3.12.0 has been released and should be available on the gem
mirrors.
= Migration Changes
* A TimestampMigrator has been added to Sequel, and is
automatically used if any migration has a version greater than
20000100. This migrator operates similarly to the default
ActiveRecord migrator, in that it allows missing migrations.
It differs from the ActiveRecord migrator in that it supports
migrations with the same timestamp/version as well as a wide
variety of timestamp formats (though the ActiveRecord default
of YYYYMMDDHHMMSS is recommended and should be used in
portable code).
Sequel still defaults to the old migrator, but you can use the
new one without making changes to your old migrations. Just
make sure your new migration starts with a version greater than
20000100, and Sequel will automatically convert the previous
schema table to the new format.
* A new migration DSL was added:
Sequel.migration do
up do
end
down do
end
end
The old style of using a Sequel::Migration subclass is still
supported, but it is recommended that new code use the new DSL.
* The default migrator also had significant issues fixed. First,
it now saves the migration version after each migration, instead
of after all migrations, which means Sequel won't attempt to
apply already applied migrations if there was previously an error
when applying multiple migrations at once on a database that
didn't support transactional schema modification.
Second, duplicate migration versions in the default migrator now
raise an exception, as do missing migration versions. Neither
should happen when using the default migrator, which requires
consecutive integer versions, similar to the old ActiveRecord
migrator.
* Execution times for migrations are now logged to the database's
loggers.
= New Plugins
* A sharding plugin has been added that allows model objects to
work well with sharded databases. When using it, model objects
know which shard they were retrieved from, so when you save
the object, it is saved back to that shard. The sharding plugin
also works with associations, so associated records are retrieved
from the same shard the main object was retreived from. The
sharding plugin also works with both methods of eager loading, and
provides methods that you can use to create objects on specific
shards.
* An update_primary_key plugin has been added that allows Sequel
to work correctly if you modify the primary key of a model object.
This should not be necessary if you are using surrogate keys, but
if your database uses natural primary keys which can change, this
should be helpful.
* An association_pks plugin has been added that adds association_pks
and association_pks= methods to model objects for both one_to_many
and many_to_many associations. The association_pks method returns
an array of primary key values for the associated objects, and
the association_pks= method modifies the database to ensure that
the object is only associated to the objects specified by the
array of primary keys provided to it.
* A string_stripper plugin has been added that strips all strings
that are assigned to attribute values. This is useful for web
applications where you want to easily remove leading and trailing
whitespace in form entries before storing them in the database.
* A skip_create_refresh plugin has been added that skips the refresh
of after you save a new model object. On most databases, Sequel
refreshes the model object after inserting it in order to get
values for all of the columns. For performance reasons, you can
use this plugin to skip the refresh if it isn't necessary for you.
= Other New Features
* Sequel::Model#set_fields and update_fields were added. These
methods have a similar API to set_only and update_only, but they
operate differently. While set_only and update_only operate over
the hash, these methods operate over the array of fields,
so they don't raise errors if the hash contains fields not
in the array:
params = {:a=>1, :b=>2, :c=>3}
album = Album[1]
# raises Error because :a is not in the fields
album.set_only(params, [:b, :c])
# Just sets the value of album.b and album.c
album.set_fields(params, [:b, :c])
Other than handling entries in the hash that aren't in the array,
set_fields and update_fields also handle entries not in the hash
differently:
# Doesn't modify the object, since the hash is empty
album.set_only({}, [:b, :c])
# Sets album.b and album.c to nil, since they aren't in the hash
album.set_fields({}, [:b, :c])
* The :eager_loader association option has a new API, though the
previous API still works. Instead of accepting three arguments,
it can now accept a single hash argument, which will use the
:key_hash, :rows, and :association keys for the previous three
arguments. The hash will also contain a :self key whose value
is the dataset doing the eager load, which was not possible to
determine using the old API.
* Sequel::SQL::Expression#hash has been added so that the objects
are now safe to use as hash keys.
* A Dataset#order_prepend method has been added allowing you to
prepend to an existing order. This is useful if want to modify
a dataset's order such that it first orders by the columns you
provide, but for any rows where the columns you provide are
equal, uses the existing order to further order the dataset:
ds.order
albums__name).order_prependartists__name)# ORDER BY artists.name, albums.name
* When creating foreign key columns, you can now use a :deferrable
option to set up a foreign key constraint that is not checked
until the end of the transaction:
DB.create_table
albums) doprimary_key :id
String :name
foreign_key :artist_id, :artists, :deferrable=>true
end
* many_to_many associations now support a :join_table_block option
that is used by the add/remove/remove_all methods. It can modify
the dataset to ensure that certain columns are included when
inserting or to add a filter so that only certain records are
deleted. It's useful if you have a many_to_many association that
is filtered to only a subset of the matching rows in the join
table.
* The single_table_inheritance plugin now supports :model_map and
:key_map options to set up a custom mapping of column values to
model classes. For simple situations such as when you are mapping
integer values to certain classes, a :model_map hash is sufficient:
Employee.plugin :single_table_inheritance, :type_id,
:model_map=>{1=>:Staff, 2=>:Manager}
Here the :model_map keys are type_id column values, and the
:model_map values are symbols or strings specifying class names.
For more complex conditions, you can use a pair of procs:
Employee.plugin :single_table_inheritance, :type_name,
:model_map=>proc{|v| v.reverse},
:key_map=>proc{|klass| klass.name.reverse}
Here the type_name column is a string column holding the reverse
of the class's name.
* The single_table_inheritance plugin now correctly sets up subclass
filters for middle tables in a class hierarchy with more than 2
levels. For example, with this code:
class Employee < Sequel::Model; end
Employee.plugin :single_table_inheritance, :kind
class Manager < Employee; end
class Executive < Manager; end
Sequel previously would not return Executives if you used
Manager.all. It now correctly recognizes subclasses so that it
will return both Managers and Executives.
* Sequel::Model.qualified_primary_key_hash has been added, giving
you a hash that can be used for filtering. It is similar to
primary_key_hash, but it qualifies the keys with the model's
table. It's useful if you have joined the table to another table
that has columns with the same name, but you want to only look
for a single model object in that dataset.
* For consistency, you can now use Dataset#order_append as an alias
for order_more.
= Other Improvements
* Sequel now correctly removes schema entries when altering tables.
Previously, some adapters that had to query the existing schema
when altering tables resulted in the previous schema being cached.
* Sequel::Model::Errors#on now always returns nil if there are no
errors on the attribute. Previously, it would return an empty
array in certain cases. Additionally, Sequel::Model::Errors#empty?
now returns true if there are no errors, where it certain cases
it would return false even if there were no errors.
* The schema_dumper extension now works with tables specified as
Sequel::SQL::Identifiers.
* Sequel now recognizes the timestamp(N) with(out) time zone column
type.
* The lazy_attributes plugin no longer requires the core extensions
to work correctly.
* DatabaseDisconnectError support has been added to the ODBC adapter,
allowing Sequel to detect disconnects and remove the connection
from the connection pool.
* A leak of JDBC statement objects when using transactions was
fixed in the jdbc adapter.
* The jdbc adapter now gives a nicer error message if you use a
connection string that it doesn't recognize and there is an error
when connecting.
* Temporary table creation was fixed on Microsoft SQL Server, but
it is not recommended as it changes the name of the table. If
you use Microsoft SQL Server, you should prefix your temporary
table names with # and use the regular create table method.
* A large number of guides were added to Sequel to make it easier
for new and existing users to learn more about Sequel. The
following guides were added:
* Querying in Sequel
* Migration and Schema Modification
* Model Hooks
* Model Validations
* Sequel for SQL Users
* Sequel for ActiveRecord Users
* RDoc section support was added to Sequel:
atabase, making themethod documentation easier to read.
= Backwards Compatibility
* Sequel:
atabase now defines the indexes and tables methods, evenif the adapter does not implement them, similar to how connect
and execute are defined. Previously, you could use respond_to? to
check if the adapter supported them, now they raise
Sequel::NotImplemented if the database adapter does not implement
them.
* Sequel used to raise NotImplementedError in certain default
definitions of methods inside Sequel:
atabase and Sequel:ataset,when the methods were supposed to be overridden in subclasses.
Sequel now uses a Sequel::NotImplemented exception class for these
exceptions, which is a subclass of Sequel::Error.
* Sequel no longer applies all association options to the dataset
used to remove all many_to_many associated objects. You should
use the new :join_table_block option to get similar behavior if
you were filtering the many_to_many association based on columns
in the join table and you wanted remove_all to only remove the
related columns.
* Sequel now calls certain before and after hook actions in plugins
in a different order than before. This should not have an effect
unless you were relying on them being called in the previous order.
Now, when overriding before hooks in plugins, Sequel always does
actions before calling super, and when overriding after hooks in
plugins, Sequel always does actions after calling super.
* The hook_class_methods plugin no longer skips later after hooks if
a previous after hook returns false. That behavior now only occurs
for before hooks.
* Sequel now only removes primary key values when updating objects if
you are saving the entire object and you have not modified the
values of the primary keys. Previously, Sequel would remove
primary key values when updating even if you specified the primary
key column specifically or the primary key column was modified and
you used save_changes/update.
* Sequel now uses explicit methods instead of aliases for certain
methods. This should only affect you if for example you overrode
Dataset#group to do one thing and wanted Dataset#group_by to do
the default action. Now, Dataset#group_by, and methods like it, are
explicit methods that just call the methods they previously
aliased. This also means that if you were overriding Dataset#group
and explicitly aliasing group_by to it, you no longer need the
alias.
* The single_table_inheritance plugin now uses IN instead of = for
subclass filters. This could lead to poor performance if the
database has a very bad query planner.
* The private transaction_statement_object method was removed from
the JDBC adapter, and Sequel will no longer check for the presence
of the method in the transaction code.
* The Sequel::Migrator object is now a class instead of a module, and
has been pretty much rewritten. If you were using any methods of
it besides apply and run, they no longer work.
Thanks,
Jeremy
* {Website}[http://sequel.rubyforge.org]
* {Source code}[http://github.com/jeremyevans/sequel]
* {Blog}[http://sequel.heroku.com]
* {Bug tracking}[http://code.google.com/p/ruby-sequel/issues/list]
* {Google group}[http://groups.google.com/group/sequel-talk]
* {RDoc}[http://sequel.rubyforge.org/rdoc]