sequel 4.49.0 → 5.0.0

data/doc/reflection.rdoc

@@ -6,7 +6,7 @@ Sequel supports reflection information in multiple ways.
 
 You can get the adapter in use using Database#adapter_scheme:
 
-  DB.adapter_scheme # e.g. :postgres, :jdbc, :odbc
+  DB.adapter_scheme # :postgres, :jdbc, :odbc
 
 == Database Connected To
 
@@ -97,17 +97,17 @@ You can get an array of association symbols with Model.associations:
 
   Model.associations # [:association1, :association2, ...]
 
-You can get the association reflection for a single association via the Model.association_reflection.  Association reflections are subclasses of hash, for ease of use and introspection (and backwards compatibility):
+You can get the association reflection for a single association via the Model.association_reflection.  Association reflections are subclasses of hash:
 
-  Model.association_reflection(:association1) # {:name=>:association1, :type=>:many_to_one, :model=>Model, ...}
+  Model.association_reflection(:association1) # #<Sequel::Model::Associations::ManyToOneAssociationReflection Model.many_to_one :association1>
 
 You can get an array of all association reflections via Model.all_association_reflections:
 
-  Model.all_association_reflections # [{:name=>:association1, :type=>:many_to_one, :model=>Model, ...}, ...]
+  Model.all_association_reflections # [#<Sequel::Model::Associations::ManyToOneAssociationReflection Model.many_to_one :association1>, ...]
 
 Finally, you can get a hash of association reflections via Model.association_reflections:
 
-  Model.association_reflections # {:association1=>{:name=>:association1, :type=>:many_to_one, :model=>Model, ...}, ...}
+  Model.association_reflections # {:association1=>#<Sequel::Model::Associations::ManyToOneAssociationReflection Model.many_to_one :association1>, ...}
 
 == Validations Defined
 
@@ -118,4 +118,3 @@ When using the validation_class_methods plugin, you can use the validation_refle
 Similarly, when using the constraint_validations plugin, you can use the constraint_validation_reflections class method:
 
   Model.constraint_validation_reflections[:column] # => [[:presence, {}], [:max_length, {:argument=>255, :message=>'is just too long'}]]
-

data/doc/release_notes/5.0.0.txt

@@ -0,0 +1,159 @@
+= Major Changes
+
+* Datasets are now frozen by default.  Since Sequel's inception,
+  datasets have used a method-chaining API that returned modified
+  copies, but previously they still supported direct mutation.  Now,
+  datasets are always frozen and cannot be mutated. This allows many
+  additional default optimizations related to caching, and provides
+  greater thread safety.
+
+    ds = DB[:table]
+
+    # Before
+    ds.row_proc = lambda{|h| h}
+
+    # Now
+    ds = ds.with_row_proc(lambda{|h| h})
+
+* Symbol splitting to create qualified and/or aliased identifiers is
+  now disabled by default.  While symbol splitting allowed for shorter
+  code, it was not obvious and caused significant issues when using
+  column names with embedded double or triple underscores.  Sequel now
+  offers many ways to create qualified and/or aliased identifiers.
+
+    # Before
+    :table__column          # "table"."column"
+
+    # Now
+    :table__column          # "table__column"
+    Sequel[:table][:column] # "table"."column"
+
+    # To get back historical behavior
+    Sequel.split_symbols = true
+
+* Sequel no longer allows the use of plain ruby strings as SQL code
+  fragments in the dataset filtering methods, as that makes it
+  easier to introduce SQL injection vulnerabilities.  You can use
+  Sequel.lit to create literal strings (SQL code fragments), which
+  makes it easier to do security auditing of applications using
+  Sequel.
+
+    # Before
+    DB[:table].where("column = 1").all
+
+    # Now 
+    DB[:table].where(Sequel.lit("column = 1")).all
+    # or better
+    DB[:table].where(column: 1).all
+
+    # To get back historical behavior
+    DB.extension :auto_literal_strings
+
+= Backwards Compatibility
+
+* All adapters, extensions, plugins, features, and constants
+  deprecated in 4.49.0 have been removed.  Before upgrading to Sequel
+  5.0.0, upgrade to 4.49.0 and fix all deprecation warnings.
+
+* Support for ruby 1.8.7 has been dropped, the minimum ruby version is
+  now 1.9.2.
+
+* The {before,after,around}_validation hooks are now always called
+  when saving, even if the validate: false option is used.  This
+  allows you to use the before_validation hook to make changes
+  to the model instance that are required before validation and
+  before saving even if not validating.
+
+* Getting column values for newly created model instances after
+  insertion now happens before after_create is called, instead of
+  after.
+
+* Sequel now immediately attempts to the connect to the database
+  when a Database instance is created, in order to fail fast if the
+  connection parameters are invalid.
+
+* The validates_unique method in the validation_helpers plugin
+  now only checks for uniqueness by default if the record is new or
+  one of the related columns has been modified by default.
+
+* Database schema modification methods and schema generator methods
+  now return nil instead of some internal value.
+
+* Many cases where Sequel used Kernel#send internally have been
+  switched to Kernel#public_send so they only call public methods.
+
+* Model association hooks are now nil instead of empty arrays by
+  default.
+
+* Internal uses of instance_eval with a block have been changed to
+  instance_exec.  This allows them to be used with lambdas that
+  take no arguments.
+
+* Most internal constants are now frozen, unless there is a
+  requirement that they be modified at runtime.
+  
+* The Model @was_new instance variable is now no longer set when
+  saving new model instances.
+
+* The private Sequel::Postgres::PGArray::Parser#new_entry_buffer
+  method in the pg_array extension has been removed.
+
+* Modifying Model.input_transformer_order in the input_transformer
+  plugin no longer has an effect.
+
+= New Features
+
+* Database#add_index :if_not_exists option is now supported on
+  PostgreSQL 9.5+.
+
+* SQL::Subscript#expression has been added to retrieve the
+  expression that is subscripted.
+
+= Other Improvements
+
+* Threaded connection pools no longer block while new connections
+  are being made.  Previously, attempting to establish a new
+  connection blocked all connection pool activity until the new
+  connection was made.
+
+* Many minor performance improvements have been made.
+
+* The class_table_inheritance plugin now raises an error during
+  Model#update if a query does not modify a single row, just as
+  the default Model#update does.
+
+* ConnectionPool#size is now thread-safe in both threaded
+  connection pools. Internal callers that already have the
+  connection pool mutex should switch to using #_size (a new
+  private method).
+
+* Registration of new serialization formats in the serialization
+  plugin is now thread-safe.
+
+* If transactional schema modifications are not supported, a
+  savepoint will not automatically be created when adding
+  indexes for new tables inside transactions.  This fixes issues
+  when making schema changes inside transactions on MySQL.
+
+* Attempting to create a prepared statement using a dataset that
+  uses a delayed evaluation now raises an error, because the
+  prepared statement would not respect the delayed evaluation.
+
+* The bin/sequel -M option now uses base 10.  Previously, it
+  used the Kernel#Integer default, which was base 8 if there was
+  a preceding 0.
+
+= Deprecated Features
+
+These deprecated features will be removed in Sequel 5.1.0.
+
+* Model.allowed_columns in the base plugin is now deprecated. Use
+  the whitelist_security plugin if you want to call it.
+
+* Model use_after_commit_rollback class and instance accessors are
+  now deprecated.
+
+* Defining the Model#_before_validation method is now deprecated.
+  You can change to using before_validation.
+
+* The private Model.plugin_module_defined? method is now deprecated.

data/doc/schema_modification.rdoc

@@ -25,27 +25,27 @@ type for the given database.  So while you specified +String+, Sequel will actua
 +text+ depending on the underlying database.  Here's a list of all ruby classes that Sequel will
 convert to database types:
 
-  create_table(:columns_types) do       # common database type used
-    Integer :a0                         # integer
-    String :a1                          # varchar(255)
-    String :a2, :size=>50               # varchar(50)
-    String :a3, :fixed=>true            # char(255)
-    String :a4, :fixed=>true, :size=>50 # char(50)
-    String :a5, :text=>true             # text
-    File :b                             # blob
-    Fixnum :c                           # integer
-    Bignum :d                           # bigint
-    Float :e                            # double precision
-    BigDecimal :f                       # numeric
-    BigDecimal :f2, :size=>10           # numeric(10)
-    BigDecimal :f3, :size=>[10, 2]      # numeric(10, 2)
-    Date :g                             # date
-    DateTime :h                         # timestamp
-    Time :i                             # timestamp
-    Time :i2, :only_time=>true          # time
-    Numeric :j                          # numeric
-    TrueClass :k                        # boolean
-    FalseClass :l                       # boolean
+  create_table(:columns_types) do     # common database type used
+    Integer :a0                       # integer
+    String :a1                        # varchar(255)
+    String :a2, size: 50              # varchar(50)
+    String :a3, fixed: true           # char(255)
+    String :a4, fixed: true, size: 50 # char(50)
+    String :a5, text: true            # text
+    File :b                           # blob
+    Fixnum :c                         # integer
+    Bignum :d                         # bigint
+    Float :e                          # double precision
+    BigDecimal :f                     # numeric
+    BigDecimal :f2, size: 10          # numeric(10)
+    BigDecimal :f3, size: [10, 2]     # numeric(10, 2)
+    Date :g                           # date
+    DateTime :h                       # timestamp
+    Time :i                           # timestamp
+    Time :i2, only_time: true         # time
+    Numeric :j                        # numeric
+    TrueClass :k                      # boolean
+    FalseClass :l                     # boolean
   end
 
 Note that in addition to the ruby class name, Sequel also pays attention to the column options when
@@ -89,7 +89,7 @@ method, the fourth argument is the options hash.  The following options are supp
           options for the index.
 :null :: Mark the column as allowing NULL values (if true),
          or not allowing NULL values (if false).  If unspecified, will default
-         to whatever the database default is.
+         to whatever the database default is (usually true).
 :primary_key :: Mark this column as the primary key.  This is used instead of the
                 primary key method if you want a non-autoincrementing primary key.
 :primary_key_constraint_name :: The name to give the primary key constraint.
@@ -98,7 +98,7 @@ method, the fourth argument is the options hash.  The following options are supp
          as +primary_key+ or +foreign_key+.
 :unique :: Mark the column as unique, generally has the same effect as
            creating a unique index on the column.
-:unique_constraint_name :: The name to give the unique key constraint.
+:unique_constraint_name :: The name to give the unique constraint.
 
 === Other methods
 
@@ -112,14 +112,14 @@ You've seen this one used already.  It's used to create an autoincrementing inte
 
 If you want an autoincrementing 64-bit integer:
 
-  create_table(:a0){primary_key :id, :type=>:Bignum}
+  create_table(:a0){primary_key :id, type: :Bignum}
 
 If you want to create a primary key column that doesn't use an autoincrementing integer, you should
 not use this method.  Instead, you should use the :primary_key option to the +column+ method or type
 method:
 
-  create_table(:a1){Integer :id, :primary_key=>true} # Non autoincrementing integer primary key
-  create_table(:a2){String :name, :primary_key=>true} # varchar(255) primary key
+  create_table(:a1){Integer :id, primary_key: true} # Non autoincrementing integer primary key
+  create_table(:a2){String :name, primary_key: true} # varchar(255) primary key
 
 If you want to create a composite primary key, you should call the +primary_key+ method with an
 array of column symbols.  You can provide a specific name to use for the primary key constraint
@@ -128,7 +128,7 @@ via the :name option:
   create_table(:items) do
     Integer :group_id
     Integer :position
-    primary_key [:group_id, :position], :name=>:items_pk
+    primary_key [:group_id, :position], name: :items_pk
   end
 
 If provided with an array, +primary_key+ does not create a column, it just sets up the primary key constraint.
@@ -147,7 +147,7 @@ as its third argument.  A simple example is:
 
 +foreign_key+ accepts the same options as +column+.  For example, to have a unique foreign key with varchar(16) type:
 
-  foreign_key :column_name, :table, :unique=>true, :type=>'varchar(16)'
+  foreign_key :column_name, :table, unique: true, type: 'varchar(16)'
 
 +foreign_key+ also accepts some specific options:
 
@@ -186,7 +186,7 @@ When using an array of symbols, you can also provide a :name option to name the
     String :artist_name
     String :artist_location
     String :name
-    foreign_key [:artist_name, :artist_location], :artists, :name=>'albums_artist_name_location_fkey'
+    foreign_key [:artist_name, :artist_location], :artists, name: 'albums_artist_name_location_fkey'
   end
 
 If you want to add a foreign key for a single column with a named constraint, you must use
@@ -196,7 +196,7 @@ the array form with a single symbol:
     primary_key :id
     Integer :artist_id
     String :name
-    foreign_key [:artist_id], :artists, :name=>'albums_artist_id_fkey'
+    foreign_key [:artist_id], :artists, name: 'albums_artist_id_fkey'
   end
 
 ==== +index+
@@ -204,18 +204,18 @@ the array form with a single symbol:
 +index+ creates indexes on the table.  For single columns, calling index is the same as using the
 <tt>:index</tt> option when creating the column:
 
-  create_table(:a){Integer :id, :index=>true}
+  create_table(:a){Integer :id, index: true}
   # Same as:
   create_table(:a) do
     Integer :id
     index :id
   end
 
-  create_table(:a){Integer :id, :index=>{:unique=>true}}
+  create_table(:a){Integer :id, index: {unique: true}}
   # Same as:
   create_table(:a) do
     Integer :id
-    index :id, :unique=>true
+    index :id, unique: true
   end
 
 Similar to the +primary_key+ and +foreign_key+ methods, calling +index+ with an array of symbols
@@ -241,11 +241,11 @@ The +unique+ method creates a unique constraint on the table.  A unique constrai
 operates identically to a unique index, so the following three +create_table+ blocks are
 pretty much identical:
 
-  create_table(:a){Integer :a, :unique=>true}
+  create_table(:a){Integer :a, unique: true}
 
   create_table(:a) do
     Integer :a
-    index :a, :unique=>true
+    index :a, unique: true
   end
 
   create_table(:a) do
@@ -304,23 +304,23 @@ constraint, as that makes it easier to drop the constraint later if necessary.
 
 +create_join_table+ is a shortcut that you can use to create simple many-to-many join tables:
 
-  create_join_table(:artist_id=>:artists, :album_id=>:albums)
+  create_join_table(artist_id: :artists, album_id: :albums)
 
 which expands to:
 
   create_table(:albums_artists) do
-    foreign_key :album_id, :albums, :null=>false
-    foreign_key :artist_id, :artists, :null=>false
+    foreign_key :album_id, :albums
+    foreign_key :artist_id, :artists
     primary_key [:album_id, :artist_id]
     index [:artist_id, :album_id]
   end
 
-== <tt>create_table :as=></tt>
+== <tt>create_table :as</tt>
 
 To create a table from the result of a SELECT query, instead of passing a block
 to +create_table+, provide a dataset to the :as option:
 
-  create_table(:older_items, :as=>DB[:items].where{updated_at < Date.today << 6})
+  create_table(:older_items, as: DB[:items].where{updated_at < Date.today << 6})
 
 == +alter_table+
 
@@ -336,7 +336,7 @@ argument is the column name, the second is the type, and the third is an options
 hash:
 
   alter_table(:albums) do
-    add_column :copies_sold, Integer, :default=>0
+    add_column :copies_sold, Integer, default: 0
   end
 
 === +drop_column+
@@ -374,6 +374,12 @@ Sequel will not add a column, but will add a composite primary key constraint:
     add_primary_key [:album_id, :artist_id]
   end
 
+It is possible to specify a name for the primary key constraint: via the :name option:
+
+  alter_table(:albums_artists) do
+    add_primary_key [:album_id, :artist_id], :name=>:albums_artists_pkey
+  end
+
 If you just want to take an existing single column and make it a primary key, call
 +add_primary_key+ with an array with a single symbol:
 
@@ -396,14 +402,14 @@ array with a single element.  It's encouraged to provide a name when adding the
 via the :name option:
 
   alter_table(:albums) do
-    add_foreign_key [:artist_id], :artists, :name=>:albums_artist_id_fkey
+    add_foreign_key [:artist_id], :artists, name: :albums_artist_id_fkey
   end
 
 To set up a multiple column foreign key constraint, use an array with multiple column
 symbols:
 
   alter_table(:albums) do
-    add_foreign_key [:artist_name, :artist_location], :artists, :name=>:albums_artist_name_location_fkey
+    add_foreign_key [:artist_name, :artist_location], :artists, name: :albums_artist_name_location_fkey
   end
 
 === +drop_foreign_key+
@@ -420,13 +426,13 @@ an array.  It's encouraged to use the :name option to provide the constraint nam
 drop, though on some databases Sequel may be able to find the name through introspection:
 
   alter_table(:albums) do
-    drop_foreign_key [:artist_id], :name=>:albums_artist_id_fkey
+    drop_foreign_key [:artist_id], name: :albums_artist_id_fkey
   end
 
 An array is also used to drop a composite foreign key constraint:
 
   alter_table(:albums) do
-    drop_foreign_key [:artist_name, :artist_location], :name=>:albums_artist_name_location_fkey
+    drop_foreign_key [:artist_name, :artist_location], name: :albums_artist_name_location_fkey
   end
 
 If you do not provide a :name option and Sequel is not able to determine the name
@@ -445,7 +451,7 @@ It accepts the same options as +create_table+'s +index+ method, and you can set
 a multiple column index using an array:
 
   alter_table(:albums_artists) do
-    add_index [:album_id, :artist_id], :unique=>true
+    add_index [:album_id, :artist_id], unique: true
   end
 
 === +drop_index+
@@ -461,7 +467,7 @@ Just like +drop_column+, it is often used in the +down+ block of a migration.
 To drop an index with a specific name, use the <tt>:name</tt> option:
 
   alter_table(:albums) do
-    drop_index :artist_id, :name=>:artists_id_index
+    drop_index :artist_id, name: :artists_id_index
   end
 
 === +add_full_text_index+, +add_spatial_index+
@@ -480,7 +486,7 @@ method:
 
 There is no method to add an unnamed constraint, but you can pass +nil+ as the first
 argument of +add_constraint+ to do so.  However, it's not recommended to do that
-as it is difficult to drop such a constraint.
+as it is more difficult to drop such a constraint.
 
 === +add_unique_constraint+
 
@@ -491,6 +497,12 @@ method.  This usually has the same effect as adding a unique index.
     add_unique_constraint [:artist_id, :name]
   end
 
+You can also specify a name via the :name option when adding the constraint:
+
+  alter_table(:albums) do
+    add_unique_constraint [:artist_id, :name], name: :albums_artist_id_name_ukey
+  end
+
 === +drop_constraint+
 
 This method drops an existing named constraint:
@@ -506,9 +518,9 @@ For that reason, you should not add unnamed constraints that you ever might need
 On some databases, you must specify the type of constraint via a <tt>:type</tt> option:
 
   alter_table(:albums) do
-    drop_constraint(:albums_pk, :type=>:primary_key)
-    drop_constraint(:albums_fk, :type=>:foreign_key)
-    drop_constraint(:albums_uk, :type=>:unique)
+    drop_constraint(:albums_pk, type: :primary_key)
+    drop_constraint(:albums_fk, type: :foreign_key)
+    drop_constraint(:albums_uk, type: :unique)
   end
 
 === +set_column_default+
@@ -597,9 +609,6 @@ the table if the table already exists.  On some databases, it uses
 <tt>IF NOT EXISTS</tt>, on others it does a separate query to check for
 existence.
 
-This should not be used inside migrations, as if the table does not
-exist, it may mess up the migration.
-
 === +rename_table+
 
 You can rename an existing table using +rename_table+.  Like +rename_column+,
@@ -623,9 +632,6 @@ is the same as:
     primary_key :id
   end
 
-It should not be used inside migrations, as if the table does not exist, it may
-mess up the migration.
-
 === <tt>create_table?</tt>
 
 <tt>create_table?</tt> only creates the table if it does
@@ -643,8 +649,6 @@ is the same as:
     end
   end
 
-Like <tt>create_table!</tt>, it should not be used inside migrations.
-
 === +create_view+ and +create_or_replace_view+
 
 These can be used to create views.  The difference between them is that
@@ -662,4 +666,3 @@ second argument:
 arguments:
 
   drop_view(:gold_albums, :platinum_albums)
-