sequel 3.26.0 → 3.27.0

data/CHANGELOG

@@ -1,3 +1,29 @@
+=== 3.27.0 (2011-09-01)
+
+* Add support for native prepared statements to the tinytds adapter (jeremyevans)
+
+* Add support for native prepared statements and stored procedures to the mysql2 adapter (jeremyevans)
+
+* Support dropping primary key, foreign key, and unique constraints on MySQL via the drop_constraint :type option (jeremyevans)
+
+* Add Sequel::SQLTime class for handling SQL time columns (jeremyevans)
+
+* Typecast DateTime objects to Date for date columns (jeremyevans)
+
+* When typecasting Date objects to timestamps, make the resulting objects always have no fractional date components (jeremyevans)
+
+* Add Model.dataset_module for simplifying many def_dataset_method calls (jeremyevans)
+
+* Make prepared_statements_safe plugin work on classes without datasets (jeremyevans)
+
+* Make Dataset#hash work correctly when referencing SQL::Expression instances (jeremyevans)
+
+* Handle allowed mass assignment methods correctly when including modules in classes or extending instances with modules (jeremyevans)
+
+* Fix Model#hash to work correctly with composite primary keys and with no primary key (jeremyevans)
+
+* Model#exists? now returns false without issuing a query for new model objects (jeremyevans)
+
 === 3.26.0 (2011-08-01)
 
 * Fix bug in default connection pool if a disconnect error is raised and the disconnection_proc also raises an error (jeremyevans)

data/Rakefile

@@ -1,6 +1,5 @@
 require "rake"
 require "rake/clean"
-require "rake/gempackagetask"
 
 NAME = 'sequel'
 VERS = lambda do
@@ -56,7 +55,7 @@ end
 
 desc "Make local version of website"
 task :website do
-  sh %{www/make_www.rb}
+  sh %{#{RUBY} www/make_www.rb}
 end
 
 desc "Make rdoc for website"
@@ -160,5 +159,5 @@ end
 
 desc "Check syntax of all .rb files"
 task :check_syntax do
-  Dir['**/*.rb'].each{|file| print `#{ENV['RUBY'] || :ruby} -c #{file} | fgrep -v "Syntax OK"`}
+  Dir['**/*.rb'].each{|file| print `#{RUBY} -c #{file} | fgrep -v "Syntax OK"`}
 end

data/doc/mass_assignment.rdoc

@@ -0,0 +1,54 @@
+= Sequel::Model Mass Assignment
+
+Most Model methods that take a hash of attribute keys and values, including <tt>Model.new</tt>, <tt>Model.create</tt>, <tt>Model#set</tt> and <tt>Model#update</tt> are subject to Sequel's mass assignment rules.
+When you pass a hash to these methods, each key has an <tt>=</tt> appended to it (the setter method), and if the setter method exists and access to it is not restricted, Sequel will call the setter method with the hash value.
+By default, there are two types of setter methods that are restricted.  
+The first is methods like <tt>typecast_on_assignment=</tt> and <tt>==</tt>, which don't affect columns.
+These methods cannot be enabled for mass assignment.
+The second is primary key setters.
+To enable use of primary key setters, you need to call +unrestrict_primary_key+ for that model:
+
+  Post.unrestrict_primary_key
+
+Since mass assignment by default allows modification of all column values except for primary key columns, it can be a security risk in some cases.
+Sequel has multiple ways of securing mass assignment.
+The first way is using +set_allowed_columns+:
+
+  Post.set_allowed_columns :title, :body, :category
+
+This explicitly sets which methods are allowed (<tt>title=</tt>, <tt>body=</tt>, and <tt>category=</tt>), all other methods will not be allowed.
+This method is useful in simple applications where the same columns are allowed in all cases, but not appropriate when different columns are allowed in different scenarios (e.g. admin access vs. user access).
+To handle cases where different columns are allowed in different cases, you can use +set_only+ or +update_only+:
+
+  # user case
+  post.set_only(params[:post], :title, :body)
+  # admin case
+  post.set_only(params[:post], :title, :body, :deleted)
+
+In this case, only the <tt>title=</tt> and <tt>body=</tt> methods will be allowed in the mass assignment.
+
+By default, if an invalid setter method call is attempted, Sequel raises a <tt>Sequel::Error</tt> exception.  You can have Sequel silently ignore invalid calls by doing:
+
+  # Global default
+  Sequel::Model.strict_param_setting = false
+  # Class level
+  Post.strict_param_setting = false
+  # Instance level
+  post.strict_param_setting = false
+
+These mass assignment methods have been around a long time, but starting in Sequel 3.12.0, the +set_fields+ or +update_fields+ methods were added, and these may be a better mass assignment choice for most users.
+These methods take two arguments, the attributes hash as the first argument, and a single array of valid field names as the second argument:
+
+  post.set_fields(params[:post], [:title, :body])
+
++set_fields+ and +update_fields+ differ in implementation from +set_only+ and +update_only+.
+With +set_only+ and +update_only+, the hash is iterated over and it checks each method call attempt to see if it is valid.
+With +set_fields+ and +update_fields+, the array is iterated over, and it just looks up the value in the hash and calls the appropriate setter method.
+
++set_fields+ and +update_fields+ are designed for the case where you are expecting specific fields in the input, and want to ignore the other fields.
+They work great for things like HTML forms where the form fields are static.
++set_only+ and +update_only+ are designed for cases where you are not sure what fields are going to be present in the input, but still want to make sure only certain setter methods can be called.
+They work great for flexible APIs.
+
+In all of the mass assignment cases, methods starting with +set+ will set the attributes without saving the object, while methods starting with +update+ will set the attributes and then save the changes to the object.
+

data/doc/migration.rdoc

@@ -2,6 +2,7 @@
 
 This guide is based on http://guides.rubyonrails.org/migrations.html
 
+
 == Overview
 
 Migrations make it easy to alter your database's schema in a systematic manner.
@@ -13,7 +14,7 @@ create the necessary database structure manually using Sequel's schema
 modification methods or another database tool.  However, if you are dealing
 with other developers, you'll have to send them all of the changes you are
 making.  Even if you aren't dealing with other developers, you generally have
-to make the schema changes in 3 places (development, testing, and then
+to make the schema changes in 3 places (development, testing, and 
 production), and it's probably easier to use the migrations system to apply
 the schema changes than it is to keep track of the changes manually and
 execute them manually at the appropriate time.
@@ -26,6 +27,8 @@ you generally need to use run Sequel's migrator with <tt>bin/sequel -m</tt>:
 Migrations in Sequel use a very simple DSL via the <tt>Sequel.migration</tt>
 method, and inside the DSL, use the <tt>Sequel::Database</tt> schema
 modification methods such as +create_table+ and +alter_table+.
+See the {schema modification guide}[link:files/doc/schema_modification_rdoc.html] 
+for details on the schema modification methods you can use.
 
 == A Basic Migration
 
@@ -45,7 +48,7 @@ Here is a fairly basic Sequel migration:
   end
 
 This migration has an +up+ block which adds an artist table with an integer primary key named id,
-and a varchar or text column (depending on the database) named name that doesn't accept NULL values.
+and a varchar or text column (depending on the database) named +name+ that doesn't accept +NULL+ values.
 Migrations should include both up and +down+ blocks, with the +down+ block reversing
 the change made by up.  However, if you never need to be able to migrate down
 (i.e. you are one of the people that doesn't make mistakes), you can leave out
@@ -142,7 +145,7 @@ Migrations themselves do not contain any schema modification methods, but they m
 any of the <tt>Sequel::Database</tt> modification methods, of which there are many.  The main
 ones are +create_table+ and +alter_table+, but Sequel also comes with numerous other schema
 modification methods, most of which are shortcuts for +alter_table+ (all of these methods are
-described in more detail later):
+described in more detail in the {schema modification guide}[link:files/doc/schema_modification_rdoc.html]):
 
 * add_column
 * add_index
@@ -344,539 +347,12 @@ reverses the changes made by the +up+ block:
     down{...}
   end
 
-== Schema modification methods
-
-Inside your migration's down and +up+ blocks is where you will call the +Database+ schema modification methods.
-Here's a brief description of the most common schema modification methods:
-
-=== +create_table+
-
-+create_table+ is the most common schema modification method, and it's used for adding new tables
-to the schema.  You provide it with the name of the table as a symbol, as well a block:
-
-  create_table(:artists) do
-    primary_key :id
-    String :name
-  end
-
-Not that if you want a primary key for the table, you need to specify it, Sequel does not create one
-by default.
-
-==== Column types
-
-Most method calls inside the create_table block will create columns, since +method_missing+ calls +column+
-Columns are generally created by specifying the column type as the method
-name, followed by the column name symbol to use, and after that any options that should be used.
-If the method is a ruby class name that Sequel recognizes, Sequel will transform it into the appropriate
-type for the given database.  So while you specified +String+, Sequel will actually use +varchar+ or
-+text+ depending on the underlying database.  Here's a list of all of 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
-  end
-
-Note that in addition to the ruby class name, Sequel also pays attention to the column options when
-determining which database type to use.
-
-Also note that this conversion is only done if you use a supported ruby class name.  In all other
-cases, Sequel uses the type specified verbatim:
-
-  create_table(:columns_types) do  # database type used
-    string :a1                     # string
-    datetime :a2                   # datetime
-    blob :a3                       # blob
-    inet :a4                       # inet
-  end
-
-In addition to specifying the types as methods, you can use the +column+ method and specify the types
-as the second argument, either as ruby classes, symbols, or strings:
-
-  create_table(:columns_types) do  # database type used
-    column :a1, :string            # string
-    column :a2, String             # varchar(255)
-    column :a3, 'string'           # string
-    column :a4, :datetime          # datetime
-    column :a5, DateTime           # timestamp
-    column :a6, 'timestamp(6)'     # timestamp(6)
-  end
-
-==== Column options
-
-When using the type name as method, the third argument is an options hash, and when using the +column+
-method, the fourth argument is the options hash.  The following options are supported:
-
-:default :: The default value for the column.
-:index :: Create an index on this column.
-: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.
-:size :: The size of the column, generally used with string
-         columns to specify the maximum number of characters the column will hold.
-         An array of two integers can be provided to set the size and the
-         precision, respectively, of decimal columns.
-:unique :: Mark the column as unique, generally has the same effect as
-           creating a unique index on the column.
-:unsigned :: Make the column type unsigned, only useful for integer
-             columns.
-
-==== Other methods
-
-In addition to the +column+ method and other methods that create columns, there are a other methods that can be used:
-
-==== +primary_key+
-
-You've seen this one used already.  It's used to create an autoincrementing integer primary key column.
-
-  create_table(:a0){primary_key :id}
-
-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
-
-If you want to create a composite primary key, you should call the +primary_key+ method with an
-array of column symbols:
-
-  create_table(:items) do
-    Integer :group_id
-    Integer :position
-    primary_key [:group_id, :position]
-  end 
-
-If provided with an array, +primary_key+ does not create a column, it just sets up the primary key constraint.
-
-==== +foreign_key+
-
-+foreign_key+ is used to create a foreign key column that references a column in another table (or the same table).
-It takes the column name as the first argument, the table it references as the second argument, and an options hash
-as it's third argument.  A simple example is:
-
-  create_table(:albums) do
-    primary_key :id
-    foreign_key :artist_id, :artists
-    String :name
-  end
-
-+foreign_key+ accepts some specific options:
-
-:deferrable :: Makes the foreign key constraint checks deferrable, so they aren't checked
-               until the end of the transaction.
-:key :: For foreign key columns, the column in the associated table
-        that this column references.  Unnecessary if this column
-        references the primary key of the associated table, at least
-        on most databases.
-:on_delete :: Specify the behavior of this foreign key column when the row with the primary key
-              it references is deleted , can be :restrict, :cascade, :set_null, or :set_default.
-:on_update :: Specify the behavior of this foreign key column when the row with the primary key
-              it references modifies the value of the primary key, can be
-              :restrict, :cascade, :set_null, or :set_default.
-
-Like +primary_key+, if you provide +foreign_key+ with an array of symbols, it will not create a
-column, but create a foreign key constraint:
-
-  create_table(:artists) do
-    String :name
-    String :location
-    primary_key [:name, :location]
-  end
-  create_table(:albums) do
-    String :artist_name
-    String :artist_location
-    String :name
-    foreign_key [:artist_name, :artist_location], :artists
-  end
-
-==== +index+
-
-+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}
-  # Same as:
-  create_table(:a) do
-    Integer :id
-    index :id
-  end
-
-Similar to the +primary_key+ and +foreign_key+ methods, calling +index+ with an array of symbols
-will create a multiple column index:
-
-  create_table(:albums) do
-    primary_key :id
-    foreign_key :artist_id, :artists
-    Integer :position
-    index [:artist_id, :position]
-  end
-
-The +index+ method also accepts some options:
-
-:name :: The name of the index (generated based on the table and column names if not provided).
-:type :: The type of index to use (only supported by some databases)
-:unique :: Make the index unique, so duplicate values are not allowed.
-:where :: Create a partial index (only supported by some databases)
-
-==== +unique+
-
-The +unique+ method creates a unique constraint on the table.  A unique constraint generally
-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) do
-    Integer :a
-    index :a, :unique=>true
-  end
-
-  create_table(:a) do
-    Integer :a
-    unique :a
-  end
-
-Just like +index+, +unique+ can set up a multiple column unique constraint, where the
-combination of the columns must be unique:
-
-  create_table(:a) do
-    Integer :a
-    Integer :b
-    unique [:a, :b]
-  end
-
-==== +full_text_index+ and +spatial_index+
-
-Both of these create specialized index types supported by some databases.  They
-both take the same options as +index+.
-
-==== +constraint+
-
-+constraint+ creates a named table constraint:
-
-  create_table(:artists) do
-    primary_key :id
-    String :name
-    constraint(:name_min_length){char_length(name) > 2}
-  end
-  
-Instead of using a block, you can use arguments that will be handled similarly
-to <tt>Dataset#filter</tt>:
-
-  create_table(:artists) do
-    primary_key :id
-    String :name
-    constraint(:name_length_range, :char_length.sql_function(:name)=>3..50)
-  end
-  
-==== +check+
-
-+check+ operates just like +constraint+, except that it doesn't take a name
-and it creates an unnamed constraint
-
-  create_table(:artists) do
-    primary_key :id
-    String :name
-    check{char_length(name) > 2}
-  end
-  
-=== +alter_table+
-
-+alter_table+ is used to alter existing tables, changing their columns, indexes,
-or constraints.  It it used just like +create_table+, accepting a block which
-is instance_evaled, and providing its own methods:
-
-==== +add_column+
-
-One of the most common methods, +add_column+ is used to add a column to the table.
-Its API is similar to that of +create_table+'s +column+ method, where the first
-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
-  end
-
-When adding a column, it's a good idea to provide a default value, unless you
-want the value for all rows to be set to NULL.
-
-==== +drop_column+
-
-As you may expect, +drop_column+ takes a column name and drops the column.  It's
-often used in the +down+ block of a migration to drop a column added in an +up+ block:
-
-  alter_table(:albums) do
-    drop_column :copies_sold
-  end
-
-==== +rename_column+
-
-+rename_column+ is used to rename a column.  It takes the old column name as the first
-argument, and the new column name as the second argument:
-
-  alter_table(:albums) do
-    rename_column :copies_sold, :total_sales
-  end
-
-==== +add_primary_key+
-
-If you forgot to include a primary key on the table, and want to add one later, you
-can use +add_primary_key+.  A common use of this is to make many_to_many association
-join tables into real models:
-
-  alter_table(:albums_artists) do
-    add_primary_key :id
-  end
-
-Just like +create_table+'s +primary_key+ method, if you provide an array of symbols,
-Sequel will not add a column, but will add a composite primary key constraint:
-
-  alter_table(:albums_artists) do
-    add_primary_key [:album_id, :artist_id]
-  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:
-
-  alter_table(:artists) do
-    add_primary_key [:id]
-  end
+or they should use the reversible migrations feature with a +change+ block:
 
-==== +add_foreign_key+
-
-+add_foreign_key+ can be used to add a new foreign key column or constraint to a table.
-Like +add_primary_key+, if you provide it with a symbol as the first argument, it
-creates a new column:
-
-  alter_table(:albums) do
-    add_foreign_key :artist_id, :artists
-  end
-
-If you want to add a new foreign key constraint to an existing column, you provide an
-array with a single element:
-
-  alter_table(:albums) do
-    add_foreign_key [:artist_id], :artists
-  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
-  end
-
-==== +add_index+
-
-+add_index+ works just like +create_table+'s +index+ method, creating a new index on
-the table:
-
-  alter_table(:albums) do
-    add_index :artist_id
-  end
-
-It accepts the same options as +create_table+'s +index+ method, and you can set up
-a multiple column index using an array:
-
-  alter_table(:albums_artists) do
-    add_index [:album_id, :artist_id], :unique=>true
-  end
-
-==== +drop_index+
-
-As you may expect, +drop_index+ drops an existing index:
-
-  alter_table(:albums) do
-    drop_index :artist_id
-  end
-
-Just like +drop_column+, it is often used in the +down+ block of a migration.
-
-==== +add_full_text_index+, +add_spatial_index+
-
-Corresponding to +create_table+'s +full_text_index+ and +spatial_index+ methods,
-these two methods create new indexes on the table.
-
-==== +add_constraint+
-
-This adds a named constraint to the table, similar to +create_table+'s +constraint+
-method:
-
-  alter_table(:albums) do
-    add_constraint(:name_min_length){char_length(name) > 2}
-  end
-
-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 recommend to do that
-as it is difficult to drop such a constraint.
-
-==== +add_unique_constraint+
-
-This adds a unique constraint to the table, similar to +create_table+'s +unique+
-method.  This usually has the same effect as adding a unique index.
-
-  alter_table(:albums) do
-    add_unique_constraint [:artist_id, :name]
-  end
-
-==== +drop_constraint+
-
-This method drops an existing named constraint:
-
-  alter_table(:albums) do
-    drop_constraint(:name_min_length)
-  end
-
-There is no database independent method to drop an unnamed constraint.  Generally, the
-database will give it a name automatically, and you will have to figure out what it is.
-For that reason, you should not add unnamed constraints that you ever might need to remove.
-
-==== +set_column_default+
-
-This modifies the default value of a column:
-
-  alter_table(:albums) do
-    set_column_default :copies_sold, 0
-  end
-
-==== +set_column_type+
-
-This modifies a column's type.  Most databases will attempt to convert existing values in
-the columns to the new type:
-
-  alter_table(:albums) do
-    set_column_type :copies_sold, Bignum
-  end
-
-You can specify the type as a string or symbol, in which case it is used verbatim, or as a supported
-ruby class, in which case it gets converted to an appropriate database type.
-
-==== +set_column_allow_null+
-
-This changes the NULL or NOT NULL setting of a column:
-
-  alter_table(:albums) do
-    set_column_allow_null :artist_id, true    # NULL
-    set_column_allow_null :copies_sold, false # NOT NULL
-  end
-
-=== Other +Database+ schema modification methods
-
-<tt>Sequel::Database</tt> has many schema modification instance methods,
-most of which are shortcuts to the same methods in +alter_table+.  The
-following +Database+ instance methods just call +alter_table+ with a
-block that calls the method with the same name inside the +alter_table+
-block with all arguments after the first argument (which is used as
-the table name):
-
-* +add_column+
-* +drop_column+
-* +rename_column+
-* +add_index+
-* +drop_index+
-* +set_column_default+
-* +set_column_type+
-
-For example, the following two method calls do the same thing:
-
-  alter_table(:artists){add_column :copies_sold, Integer}
-  add_column :artists, :copies_sold, Integer
-
-There are some other schema modification methods that have no +alter_table+
-counterpart:
-
-==== +drop_table+
-
-+drop_table+ takes multiple arguments and treats all arguments as a
-table name to drop:
-
-  drop_table(:albums_artists, :albums, :artists)
-
-Note that when dropping tables, you may need to drop them in a specific order
-if you are using foreign keys and the database is enforcing referential
-integrity.  In general, you need to drop the tables containing the foreign
-keys before the tables containing the primary keys they reference.
-
-==== +rename_table+
-
-You can rename an existing table using +rename_table+.  Like +rename_column+,
-the first argument is the current name, and the second is the new name:
-
-  rename_table(:artist, :artists)
-
-==== <tt>create_table!</tt>
-
-<tt>create_table!</tt> with the bang drops the table unconditionally (swallowing
-any errors) before attempting to create it, so:
-
-  create_table!(:artists)
-    primary_key :id
-  end
-
-is the same as:
-
-  drop_table(:artists) rescue nil
-  create_table(:artists)
-    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> with a question mark only creates the table if it does
-not already exist, so:
-
-  create_table!(:artists)
-    primary_key :id
+  Sequel.migration do
+    change{...}
   end
 
-is the same as:
-
-  create_table(:artists)
-    primary_key :id
-  end unless table_exists?(:artists)
-
-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
-+create_or_replace_view+ will unconditionally replace an existing view of
-the same name, while +create_view+ will probably raise an error.  Both methods
-take the name as the first argument, and either an string or a dataset as the
-second argument:
-
-  create_view(:gold_albums, DB[:albums].filter{copies_sold > 500000})
-  create_or_replace_view(:gold_albums, "SELECT * FROM albums WHERE copies_sold > 500000")
-
-==== +drop_view+
-
-+drop_view+ drops existing views.  Just like +drop_table+, it can accept multiple
-arguments:
-
-  drop_view(:gold_albums, :platinum_albums)
-
 == What to put in your migration's +down+ block
 
 It's usually easy to determine what you should put in your migration's +up+ block,