sequel 3.46.0 → 3.47.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f41a65970b01417999c117602accf3a2eb0acb64
-  data.tar.gz: 70f3a0b14da5779276cea3fc752b06d69b95fdee
+  metadata.gz: 145949fd1421f21d5a6f4c980bb3c68ad9d79cbc
+  data.tar.gz: 26ae6dfbcb667675caa5b2de7d89a63472fc1c62
 SHA512:
-  metadata.gz: ac4bbb6968ce5890ec6e3ba61cafc982d5508fc7aa4cab016f15fb67a237145f7461b82ad2aa6bb1cd5f90bb5327d8c616823a61fccc0d40457886cdccd3dfb6
-  data.tar.gz: f3c47bbc24033387b7cc225c58f73646bf19a477f69963f053eace7e8d8fb02b97fc78043a42d5a9d23d49b7ff1d1363de37fdeef396d177925f6f30face34b4
+  metadata.gz: 05bf4a0d1b5ec9b9870a7544e56971ddfbba7c244f909a8fb1acdd035463ba4b05a587f81a492c8f38adb53bc2c8e6b9d5faac7194de563fa29e0ecf2482ea93
+  data.tar.gz: 456c3859c61bba059d5ff24dcb0dc3ea79984c919ec1f0e38ef0f7f63a2b94e86d2fd6ab15ed0e7283860509ba081beb2a0f5322bf650f18277ff67b9d720c7a

data/CHANGELOG

@@ -1,3 +1,99 @@
+=== 3.47.0 (2013-05-01)
+
+* Don't fail for missing conversion proc in pg_typecast_on_load plugin (jeremyevans)
+
+* Rename PGRangeOp #starts_before and #ends_after to #ends_before and #starts_after (soupmatt) (#655)
+
+* Add Database#supports_schema_parsing? for checking for schema parsing support (jeremyevans)
+
+* Handle hstore[] types on PostgreSQL if using pg_array and pg_hstore extensions (jeremyevans)
+
+* Don't reset conversion procs when loading pg_* extensions (jeremyevans)
+
+* Handle domain types when parsing the schema on PostgreSQL (jeremyevans)
+
+* Handle domain types in composite types in the pg_row extension (jeremyevans)
+
+* Add Database.extension, for loading an extension into all future databases (jeremyevans)
+
+* Support a :search_path Database option for setting PostgreSQL search_path (jeremyevans)
+
+* Support a :convert_infinite_timestamps Database option in the postgres adapter (jeremyevans)
+
+* Support a :use_iso_date_format Database option in the postgres adapter, for per-Database specific behavior (jeremyevans)
+
+* Add Model.default_set_fields_options, for having a model-wide default setting (jeremyevans)
+
+* Make Model.map, .to_hash, and .to_hash_groups work without a query when using the static_cache plugin (jeremyevans)
+
+* Support :hash_dup and Proc Model inherited instance variable types (jeremyevans)
+
+* Handle aliased tables in the pg_row plugin (jeremyevans)
+
+* Add input_transformer plugin, for automatically transform input to model column setters (jeremyevans)
+
+* Add auto_validations plugin, for automatically adding not null, type, and unique validations (jeremyevans)
+
+* Add validates_not_null to validation_helpers (jeremyevans)
+
+* Add :setter, :adder, :remover, and :clearer association options for overriding the default modification behavior (jeremyevans)
+
+* Add Database#register_array_type to the pg_array extension, for registering database-specific array types (jeremyevans)
+
+* Speed up fetching model instances when using update_primary_key plugin (jeremyevans)
+
+* In the update_primary_key plugin, if the primary key column changes, clear related associations (jeremyevans)
+
+* Add :allow_missing_migration_files option to migrators, for not raising if migration files are missing (bporterfield) (#652)
+
+* Fix race condition related to prepared_sql for newly prepared statements (jeremyevans) (#651)
+
+* Support :keep_reference=>false Database option for not adding reference to Sequel::DATABASES (jeremyevans)
+
+* Make Postgres::HStoreOp#- explicitly cast a string argument to text, to avoid PostgreSQL assuming it is an hstore (jeremyevans)
+
+* Add validates_schema_types validation for validating column values are instances of an appropriate class (jeremyevans)
+
+* Allow validates_type validation to accept an array of allowable classes (jeremyevans)
+
+* Add Database#schema_type_class for getting the ruby class or classes related to the type symbol (jeremyevans)
+
+* Add error_splitter plugin, for splitting multi-column errors into separate errors per column (jeremyevans)
+
+* Skip validates_unique validation if underlying columns are not valid (jeremyevans)
+
+* Allow Model#modified! to take an optional column argument and mark that column as being modified (jeremyevans)
+
+* Allow Model#modified? to take an optional column argument and check if that column has been modified (jeremyevans)
+
+* Make Model.count not issue a database query if using the static_cache plugin (jeremyevans)
+
+* Handle more corner cases in the many_to_one_pk_lookup plugin (jeremyevans)
+
+* Handle database connection during initialization in jdbc adapter (jeremyevans) (#646)
+
+* Add Database.after_initialize, which takes a block and calls the block with each newly created Database instance (ged) (#641)
+
+* Add a guide detailing PostgreSQL-specific support (jeremyevans)
+
+* Make model plugins deal with frozen instances (jeremyevans)
+
+* Allow freezing of model instances for models without primary keys (jeremyevans)
+
+* Reflect constraint_validations extension :allow_nil=>true setting in the database constraints (jeremyevans)
+
+* Add Plugins.after_set_dataset for easily running code after set_dataset (jeremyevans)
+
+* Add Plugins.inherited_instance_variables for easily setting class instance variables when subclassing (jeremyevans)
+
+* Add Plugins.def_dataset_methods for easily defining class methods that call dataset methods (jeremyevans)
+
+* Make lazy_attributes plugin no longer depend on identity_map plugin (jeremyevans)
+
+* Make Dataset#get with an array of values handle case where no row is returned (jeremyevans)
+
+* Make caching plugin handle memcached API for deletes if ignore_exceptions option is used (rintaun) (#639)
+
 === 3.46.0 (2013-04-02)
 
 * Add Dataset#cross_apply and Dataset#outer_apply on Microsoft SQL Server (jeremyevans)

data/Rakefile

@@ -129,6 +129,13 @@ begin
   spec = lambda do |name, files, d|
     lib_dir = File.join(File.dirname(File.expand_path(__FILE__)), 'lib')
     ENV['RUBYLIB'] ? (ENV['RUBYLIB'] += ":#{lib_dir}") : (ENV['RUBYLIB'] = lib_dir)
+
+    desc "#{d} with -w, some warnings filtered"
+    task "#{name}_w" do
+      ENV['RUBYOPT'] ? (ENV['RUBYOPT'] += " -w") : (ENV['RUBYOPT'] = '-w')
+      sh "#{FileUtils::RUBY} -S rake #{name} 2>&1 | egrep -v \"(spec/.*: warning: (possibly )?useless use of == in void context|: warning: instance variable @.* not initialized|: warning: method redefined; discarding old|: warning: previous definition of)|rspec\""
+    end
+
     desc d
     spec_class.new(name) do |t|
       t.send spec_files_meth, files
@@ -201,7 +208,6 @@ desc "Report code statistics (KLOCs, etc) from the application"
 task :stats do
   STATS_DIRECTORIES = [%w(Code lib/), %w(Spec spec)].map{|name, dir| [ name, "./#{dir}" ] }.select { |name, dir| File.directory?(dir)}
   require "./extra/stats"
-  verbose = true
   CodeStatistics.new(*STATS_DIRECTORIES).to_s
 end
 

data/bin/sequel

@@ -17,7 +17,7 @@ load_dirs = []
 exclusive_options = []
 loggers = []
 
-opts = OptionParser.new do |opts|
+options = OptionParser.new do |opts|
   opts.banner = "Sequel: The Database Toolkit for Ruby"
   opts.define_head "Usage: sequel [options] <uri|path> [file]"
   opts.separator ""
@@ -107,6 +107,7 @@ opts = OptionParser.new do |opts|
     exit
   end
 end
+opts = options
 opts.parse!
 
 db = ARGV.shift
@@ -146,18 +147,19 @@ begin
     exit
   end
   if dump_migration
-    Sequel.extension :schema_dumper
+    DB.extension :schema_dumper
     puts DB.dump_schema_migration(:same_db=>dump_migration==:same_db)
     exit
   end
   if dump_schema
-    Sequel.extension :schema_caching
+    DB.extension :schema_caching
     DB.tables.each{|t| DB.schema(Sequel::SQL::Identifier.new(t))}
     DB.dump_schema_cache(dump_schema)
     exit
   end
   if copy_databases
-    Sequel.extension :migration, :schema_dumper
+    Sequel.extension :migration
+    DB.extension :schema_dumper
 
     db2 = ARGV.shift
     error_proc["Error: Must specify database connection string or path to yaml file as second argument for database you want to copy to"] if db2.nil? || db2.empty?

data/doc/active_record.rdoc

@@ -441,7 +441,7 @@ You can think of <tt>Sequel::Model::Errors</tt> as a subset of <tt>ActiveRecord:
 Unlike ActiveRecord, Sequel's behavior depends on how you configure it.  In Sequel, you can set flags at the global, class, and instance level that change the behavior of Sequel.  Here's a brief description of the flags:
 
 +raise_on_save_failure+ :: Whether to raise an error instead of returning nil on a failure to save/create/save_changes/etc due to a validation failure or a before_* hook returning false. By default, an error is raised, when this is set to false, nil is returned instead.
-+raise_on_typecast_failure+ :: Whether to raise an error when unable to typecast data for a column (default: true). This should be set to false if you want to use validations to display nice error messages to the user (e.g. most web applications). You can use the +validates_not_string+ validation in connection with this option to check for typecast failures for columns that aren't blobs or strings.
++raise_on_typecast_failure+ :: Whether to raise an error when unable to typecast data for a column (default: true). This should be set to false if you want to use validations to display nice error messages to the user (e.g. most web applications). You can use the +validates_schema_types+ validation in connection with this option to check for typecast failures.
 +require_modification+ :: Whether to raise an error if an UPDATE or DELETE query related to a model instance does not modify exactly 1 row. If set to false, Sequel  will not check the number of rows modified (default: true if the database supports it). 
 +strict_param_setting+ :: Whether new/set/update and their variants should raise an error if an invalid key is used. A key is invalid if no setter method exists for that key or the access to the setter method is restricted (e.g. due to it being a primary key field). If set to false, silently skip any key where the setter method doesn't exist or access to it is restricted.
 +typecast_empty_string_to_nil+ :: Whether to typecast the empty string ('') to nil for columns that are not string or blob. In most cases the empty string would be the way to specify a NULL SQL value in string form (nil.to_s == ''), and an empty string would not usually be typecast correctly for other types, so the default is true. 

data/doc/advanced_associations.rdoc

@@ -418,11 +418,15 @@ ActiveRecord:
 Sequel::Model:
 
   class Asset < Sequel::Model
-    many_to_one :attachable, :reciprocal=>:assets, \
+    many_to_one :attachable, :reciprocal=>:assets,
+      :setter=>(proc do |attachable|
+        self[:attachable_id] = (attachable.pk if attachable)
+        self[:attachable_type] = (attachable.class.name if attachable)
+      end),
       :dataset=>(proc do
         klass = attachable_type.constantize
         klass.where(klass.primary_key=>attachable_id)
-      end), \
+      end),
       :eager_loader=>(proc do |eo|
         id_map = {}
         eo[:rows].each do |asset|
@@ -438,45 +442,20 @@ Sequel::Model:
           end
         end
       end)
-  
-    private
-
-    def _attachable=(attachable)
-      self[:attachable_id] = (attachable.pk if attachable)
-      self[:attachable_type] = (attachable.class.name if attachable)
-    end 
   end 
 
   class Post < Sequel::Model
-    one_to_many :assets, :key=>:attachable_id, :reciprocal=>:attachable, :conditions=>{:attachable_type=>'Post'}
-  
-    private
-
-    def _add_asset(asset)
-      asset.update(:attachable_id=>pk, :attachable_type=>'Post')
-    end
-    def _remove_asset(asset)
-      asset.update(:attachable_id=>nil, :attachable_type=>nil)
-    end
-    def _remove_all_assets
-      assets_dataset.update(:attachable_id=>nil, :attachable_type=>nil)
-    end
+    one_to_many :assets, :key=>:attachable_id, :reciprocal=>:attachable, :conditions=>{:attachable_type=>'Post'},
+      :adder=>proc{|asset| asset.update(:attachable_id=>pk, :attachable_type=>'Post')},
+      :remover=>proc{|asset| asset.update(:attachable_id=>nil, :attachable_type=>nil)},
+      :clearer=>proc{assets_dataset.update(:attachable_id=>nil, :attachable_type=>nil)}
   end
 
   class Note < Sequel::Model
-    one_to_many :assets, :key=>:attachable_id, :reciprocal=>:attachable, :conditions=>{:attachable_type=>'Note'}     
-
-    private
-
-    def _add_asset(asset)
-      asset.update(:attachable_id=>pk, :attachable_type=>'Note')
-    end
-    def _remove_asset(asset)
-      asset.update(:attachable_id=>nil, :attachable_type=>nil)
-    end
-    def _remove_all_assets
-      assets_dataset.update(:attachable_id=>nil, :attachable_type=>nil)
-    end
+    one_to_many :assets, :key=>:attachable_id, :reciprocal=>:attachable, :conditions=>{:attachable_type=>'Note'},
+      :adder=>proc{|asset| asset.update(:attachable_id=>pk, :attachable_type=>'Note')},
+      :remover=>proc{|asset| asset.update(:attachable_id=>nil, :attachable_type=>nil)},
+      :clearer=>proc{assets_dataset.update(:attachable_id=>nil, :attachable_type=>nil)}
   end
 
   @asset.attachable = @post

data/doc/association_basics.rdoc

@@ -747,7 +747,13 @@ method that is preceeded by an underscore that does the actual
 modification.  The public method without the underscore handles caching
 and callbacks, and shouldn't be overridden by the user.
 
-=== _<i>association</i>=
+In addition to overriding the private method in your class, you can also
+use association options to change which method Sequel defines.  The
+only difference between the two is that if you use an association option
+to change the method Sequel defines, you cannot call super to get the
+default behavior.
+
+=== _<i>association</i>= (:setter option)
 
 Let's say you want to set a specific field whenever associating an object
 using the association setter method.  For example, let's say you have
@@ -775,7 +781,7 @@ The above example is contrived, as you would generally use a before_save model
 hook to handle such a modification.  However, if you only modify the album's
 artist using the artist= method, this approach may perform better.
 
-=== \_add_<i>association</i>
+=== \_add_<i>association</i> (:adder option)
 
 Continuing with the same example, here's how would you handle the same case if
 you also wanted to handle the Artist#add_album method:
@@ -790,7 +796,7 @@ you also wanted to handle the Artist#add_album method:
     end
   end
 
-=== \_remove_<i>association</i>
+=== \_remove_<i>association</i> (:remover option)
 
 Continuing with the same example, here's how would you handle the same case if
 you also wanted to handle the Artist#remove_album method:
@@ -805,7 +811,7 @@ you also wanted to handle the Artist#remove_album method:
     end
   end
 
-=== \_remove_all_<i>association</i>
+=== \_remove_all_<i>association</i> (:clearer option)
 
 Continuing with the same example, here's how would you handle the same case if
 you also wanted to handle the Artist#remove_all_albums method:
@@ -1507,6 +1513,62 @@ Like the :left_primary_key option, but :left_primary_key references the method n
 Like the :right_primary_key option, but :right_primary_key references the column
 name, while :right_primary_key_method references the method name.
 
+=== Private Method Overriding Options
+
+These options override the private methods that Sequel defines to do
+the actual work of associating and deassociating objects.
+
+==== :setter [*_to_one associations]
+
+This overrides the default behavior when you call an association setter
+method.  Let's say you want to set a specific field whenever associating an object
+using the association setter method.
+
+  class Album < Sequel::Model
+    many_to_one :artist, :setter=>(proc do |artist|
+      if artist
+        self.artist_id = artist.id
+        self.file_under = "#{artist.name}-#{name}"
+      else
+        self.artist_id = nil
+        self.file_under = name
+      end
+    end)
+  end
+
+==== :adder [*_to_many associations]
+
+Continuing with the same example, here's how would you handle the same case if
+you also wanted to handle the Artist#add_album method:
+
+  class Artist < Sequel::Model
+    one_to_many :albums, :adder=>(proc do |album|
+      album.update(:artist_id => id, :file_under=>"#{name}-#{album.name}")
+    end)
+  end
+
+==== :remover [*_to_many associations]
+
+Continuing with the same example, here's how would you handle the same case if
+you also wanted to handle the Artist#remove_album method:
+
+  class Artist < Sequel::Model
+    one_to_many :albums, :remover=>(proc do |album|
+      album.update(:artist_id => nil, :file_under=>album.name)
+    end)
+  end
+
+==== :clearer [*_to_many associations]
+
+Continuing with the same example, here's how would you handle the same case if
+you also wanted to handle the Artist#remove_all_albums method:
+
+  class Artist < Sequel::Model
+    one_to_many :albums, :clearer=>(proc do
+      albums_dataset.update(:artist_id => nil, :file_under=>:name)
+    end)
+  end
+
 === Advanced Options
 
 ==== :reciprocal

data/doc/migration.rdoc

@@ -356,6 +356,10 @@ With the +TimestampMigrator+, you are trading reliability for convenience.  That
 trade, especially if simultaneous related schema changes by separate developers are unlikely, but
 you should give it some thought before using it.
 
+== Ignoring missing migrations
+
+In some cases, you may want to allow a migration in the database that does not exist in the filesystem (deploying to an older version of code without running a down migration when deploy auto-migrates, for example). If required, you can pass <tt>:allow_missing_migration_files => true<tt> as an option. This will stop errors from being raised if there are migrations in the database that do not exist in the filesystem.
+
 == Modifying existing migrations
 
 Just don't do it.

data/doc/opening_databases.rdoc

@@ -355,11 +355,17 @@ use pg are encouraged to install sequel_pg.
 The following additional options are supported:
 
 :charset :: Same as :encoding, :encoding takes precedence
+:convert_infinite_timestamps :: Whether infinite timestamps/dates should be converted on retrieval.  By default, no
+                                conversion is done, so an error is raised if you attempt to retrieve an infinite
+                                timestamp/date.  You can set this to :nil to convert to nil, :string to leave
+                                as a string, or :float to convert to an infinite float.
 :encoding :: Set the client_encoding to the given string
 :connect_timeout :: Set the number of seconds to wait for a connection (default 20, only respected
                     if using the pg library).
 :sslmode :: Set to 'disable', 'allow', 'prefer', 'require' to choose how to treat SSL (only
             respected if using the pg library)
+:use_iso_date_format :: This can be set to false to not force the ISO date format.  Sequel forces
+                        it by default to allow for an optimization.
 
 === sqlite
 

data/doc/postgresql.rdoc

@@ -0,0 +1,302 @@
+= PostgreSQL-specific Support in Sequel
+
+Sequel's core database and dataset functions are designed to support the features
+shared by most common SQL database implementations.  However, Sequel's database
+adapters extend the core support to include support for database-specific features.
+
+By far the most extensive database-specific support in Sequel is for PostgreSQL. This
+support is roughly broken into the following areas:
+
+* Database Types
+* DDL Support
+* DML Support
+* sequel_pg
+
+Note that while this guide is extensive, it is not exhaustive.  There are additional
+rarely used PostgreSQL features that Sequel supports which are not mentioned here.
+
+== Adapter/Driver Specific Support
+
+Some of this this support depends on the specific adapter or underlying driver in use.  
+<tt>postgres only</tt> will denote support specific to the postgres adapter (i.e.
+not available when connecting to PostgreSQL via the jdbc, do, or swift adapters).
+<tt>postgres/pg only</tt> will denote support specific to the postgres adapter when
+pg is used as the underlying driver (i.e. not available when using the postgres-pr or
+postgres drivers).
+
+== PostgreSQL-specific Database Type Support
+
+Sequel's default support on PostgreSQL only includes common database types.  However,
+Sequel ships with support for many PostgreSQL-specific types via extensions.  In general,
+you load these extensions via <tt>Database#extension</tt>.  For example, to load support
+for arrays, you would do:
+
+  DB.extension :pg_array
+
+The following PostgreSQL-specific type extensions are available:
+
+pg_array :: arrays (single and multidimensional, for any scalar type), as a ruby Array-like object
+pg_hstore :: hstore, as a ruby Hash-like object
+pg_inet :: inet/cidr, as ruby IPAddr objects
+pg_interval :: interval, as ActiveSupport::Duration objects
+pg_json :: json, as either ruby Array-like or Hash-like objects
+pg_range :: ranges (for any scalar type), as a ruby Range-like object
+pg_row :: row-valued/composite types, as a ruby Hash-like or Sequel::Model object
+
+In general, these extensions just add support for Database objects to return retrieved
+column values as the appropriate type (<tt>postgres only</tt>), and support for literalizing
+the objects correctly for use in an SQL string, or using them as bound variable values (<tt>postgres/pg only</tt>).
+
+There are also type-specific extensions that make it easy to use database functions
+and operators related to the type.  These extensions are:
+
+pg_array_ops :: array-related functions and operators
+pg_hstore_ops :: hstore-related functions and operators
+pg_range_ops :: range-related functions and operators
+pg_row_ops :: row-valued/composite type syntax support
+
+== PostgreSQL-specific DDL Support
+
+=== Exclusion Constraints
+
+In +create_table+ blocks, you can use the +exclude+ method to set up exclusion constraints:
+
+  DB.create_table(:table) do
+    daterange :during
+    exclude([[:during, '&&']], :name=>:table_during_excl)
+  end
+  # CREATE TABLE "table" ("during" daterange,
+  #   CONSTRAINT "table_during_excl" EXCLUDE USING gist ("during" WITH &&))
+
+You can also add exclusion constraints in +alter_table+ blocks using add_exclusion_constraint:
+
+  DB.alter_table(:table) do
+    add_exclusion_constraint([[:during, '&&']], :name=>:table_during_excl)
+  end
+  # ALTER TABLE "table" ADD CONSTRAINT "table_during_excl" EXCLUDE USING gist ("during" WITH &&)
+
+=== Adding Foreign Key Constraints Without Initial Validation
+
+You can add a <tt>:not_valid=>true</tt> option when adding constraints to existing tables so
+that it doesn't check if all current rows are valid:
+
+  DB.alter_table(:table) do
+    # Assumes t_id column already exists
+    add_foreign_key([:t_id], :table, :not_valid=>true, :name=>:table_fk)
+  end
+  # ALTER TABLE "table" ADD CONSTRAINT "table_fk" FOREIGN KEY ("t_id") REFERENCES "table" NOT VALID
+
+Such constraints will be enforced for newly inserted and updated rows, but not for existing rows. After
+all existing rows have been fixed, you can validate the constraint:
+
+  DB.alter_table(:table) do
+    validate_constraint(:table_fk)
+  end
+  # ALTER TABLE "table" VALIDATE CONSTRAINT "table_fk"
+
+=== Creating Indexes Concurrently
+
+You can create indexes concurrently using the <tt>:concurrently=>true</tt> option:
+
+  DB.add_index(:table, :t_id, :concurrently=>true)
+  # CREATE INDEX CONCURRENTLY "table_t_id_index" ON "table" ("t_id")
+
+Similarly, you can drop indexes concurrently as well:
+
+  DB.drop_index(:table, :t_id, :concurrently=>true)
+  # DROP INDEX CONCURRENTLY "table_t_id_index"
+
+=== Specific Conversions When Altering Column Types
+
+When altering a column type, PostgreSQL allows the user to specify how to do the
+conversion via a USING clause, and Sequel supports this using the <tt>:using</tt> option:
+
+  DB.alter_table(:table) do
+    # Assume unix_time column is stored as an integer, and you want to change it to timestamp
+    set_column_type :unix_time, Time, :using=>(Sequel.cast('epoch', Time) + Sequel.cast('1 second', :interval) * :unix_time)
+  end
+  # ALTER TABLE "table" ALTER COLUMN "unix_time" TYPE timestamp
+  #   USING (CAST('epoch' AS timestamp) + (CAST('1 second' AS interval) * "unix_time"))
+
+=== Creating Unlogged Tables
+
+PostgreSQL allows users to create unlogged tables, which are faster but not crash safe.  Sequel
+allows you do create an unlogged table by specifying the <tt>:unlogged=>true</tt> option to +create_table+:
+
+  DB.create_table(:table, :unlogged=>true){Integer :i}
+  # CREATE UNLOGGED TABLE "table" ("i" integer)
+
+=== Creating/Dropping Schemas, Languages, Functions, and Triggers
+
+Sequel has built in support for creating and dropping PostgreSQL schemas, procedural languages, functions, and triggers:
+
+  DB.create_schema(:s)
+  # CREATE SCHEMA "s"
+  DB.drop_schema(:s)
+  # DROP SCHEMA "s"
+
+  DB.create_language(:plperl)
+  # CREATE LANGUAGE plperl
+  DB.drop_language(:plperl)
+  # DROP LANGUAGE plperl
+
+  DB.create_function(:set_updated_at, <<-SQL, :language=>:plpgsql, :returns=>:trigger)
+    BEGIN
+      NEW.updated_at := CURRENT_TIMESTAMP;
+      RETURN NEW;
+    END;
+  SQL
+  # CREATE FUNCTION set_updated_at() RETURNS trigger LANGUAGE plpgsql AS '
+  #  BEGIN
+  #    NEW.updated_at := CURRENT_TIMESTAMP;
+  #    RETURN NEW;
+  #  END;'
+  DB.drop_function(:set_updated_at)
+  # DROP FUNCTION set_updated_at()
+
+  DB.create_trigger(:table, :trg_updated_at, :set_updated_at, :events=>[:insert, :update], :each_row=>true)
+  # CREATE TRIGGER trg_updated_at BEFORE INSERT OR UPDATE ON "table" FOR EACH ROW EXECUTE PROCEDURE set_updated_at()
+  DB.drop_trigger(:table, :trg_updated_at)
+  # DROP TRIGGER trg_updated_at ON "table"
+
+== PostgreSQL-specific DML Support
+
+=== Returning Rows From Insert, Update, and Delete Statements
+
+Sequel supports the ability to return rows from insert, update, and delete statements, via
+<tt>Dataset#returning</tt>:
+
+  DB[:table].returning.insert
+  # INSERT INTO "table" DEFAULT VALUES RETURNING *
+
+  DB[:table].returning(:id).delete
+  # DELETE FROM "table" RETURNING "id"
+
+  DB[:table].returning(:id, Sequel.*(:id, :id).as(:idsq)).update(:id=>2)
+  # UPDATE "table" SET "id" = 2 RETURNING "id", ("id" * "id") AS "idsq"
+
+When returning is used, instead of returning the number of rows affected (for updated/delete)
+or the serial primary key value (for insert), it will return an array of hashes with the
+returned results.
+
+=== Distinct On Specific Columns
+
+Sequel allows passing columns to <tt>Dataset#distinct</tt>, which will make the dataset return
+rows that are distinct on just those columns:
+
+  DB[:table].distinct(:id).all
+  # SELECT DISTINCT ON ("id") * FROM "table"
+
+=== Using a Cursor to Process Large Datasets <tt>postgres only</tt>
+
+The postgres adapter offers a <tt>Dataset#use_cursor</tt> method to process large result sets
+without keeping all rows in memory:
+
+  DB[:table].use_cursor.each{|row| }
+  # BEGIN;
+  # DECLARE sequel_cursor NO SCROLL CURSOR WITHOUT HOLD FOR SELECT * FROM "table";
+  # FETCH FORWARD 1000 FROM sequel_cursor
+  # FETCH FORWARD 1000 FROM sequel_cursor
+  # ...
+  # FETCH FORWARD 1000 FROM sequel_cursor
+  # CLOSE sequel_cursor
+  # COMMIT
+
+=== Truncate Modifiers
+
+Sequel supports PostgreSQL-specific truncate options:
+
+  DB[:table].truncate(:cascade => true, :only=>true, :restart=>true)
+  # TRUNCATE TABLE ONLY "table" RESTART IDENTITY CASCADE
+
+=== COPY Support <tt>postgres/pg and jdbc/postgres only</tt> 
+
+PostgreSQL's COPY feature is pretty much the fastest way to get data in or out of the database.
+Sequel supports getting data out of the database via <tt>Database#copy_table</tt>, either for
+a specific table or for an arbitrary dataset:
+
+  DB.copy_table(:table, :format=>:csv)
+  # COPY "table" TO STDOUT (FORMAT csv)
+  DB.copy_table(DB[:table], :format=>:csv)
+  # COPY (SELECT * FROM "table") TO STDOUT (FORMAT csv)
+
+It supports putting data into the database via <tt>Database#copy_into</tt>:
+
+  DB.copy_into(:table, :format=>:csv, :columns=>[:column1, :column2], :data=>"1,2\n2,3\n")
+  # COPY "table"("column1", "column2") FROM STDIN (FORMAT csv)
+
+=== Anonymous Function Execution
+
+You can execute anonymous functions using a database procedural language via <tt>Database#do</tt> (the
+plpgsql language is the default):
+
+  DB.do <<-SQL
+    DECLARE r record;
+    BEGIN
+     FOR r IN SELECT table_schema, table_name FROM information_schema.tables
+       WHERE table_type = 'VIEW' AND table_schema = 'public'
+     LOOP
+       EXECUTE 'GRANT ALL ON ' || quote_ident(r.table_schema) || '.' || quote_ident(r.table_name) || ' TO webuser';
+     END LOOP;
+    END;
+  SQL
+
+=== Listening On and Notifying Channels
+
+You can use <tt>Database#notify</tt> to send notification to channels:
+
+  DB.notify(:channel)
+  # NOTIFY "channel"
+
+<tt>postgres/pg only</tt> You can listen on channels via <tt>Database#listen</tt>.  Note that
+this blocks until the listening thread is notified:
+
+  DB.listen(:channel)
+  # LISTEN "channel"
+  # after notification received:
+  # UNLISTEN *
+
+Note that +listen+ by default only listens for a single notification.  If you want to loop and process
+notifications:
+
+  DB.listen(:channel, :loop=>true){|channel| p channel}
+
+=== Locking Tables
+
+Sequel makes it easy to lock tables, though it is generally better to let the database
+handle locking:
+
+  DB[:table].lock('EXCLUSIVE') do
+    DB[:table].insert(:id=>DB[:table].max(:id)+1)
+  end
+  # BEGIN;
+  # LOCK TABLE "table" IN EXCLUSIVE MODE;
+  # SELECT max("id") FROM "table" LIMIT 1;
+  # INSERT INTO "table" ("id") VALUES (2) RETURNING NULL;
+  # COMMIT;
+
+== sequel_pg (<tt>postgres/pg only</tt>)
+
+When the postgres adapter is used with the pg driver, Sequel automatically checks for sequel_pg, and
+loads it if it is available.  sequel_pg is a C extension that optimizes the fetching of rows, generally
+resulting in a 2-6x speedup.  It is highly recommended to install sequel_pg if you are using the
+postgres adapter with pg.
+
+sequel_pg has additional optimizations when using the Dataset +map+, +to_hash+,
++to_hash_groups+, +select_hash+, +select_hash_groups+, +select_map+, and +select_order_map+ methods,
+which avoids creating intermediate hashes and can add further speedups.
+
+In addition to optimization, sequel_pg also adds streaming support if used on PostgreSQL 9.2. Streaming
+support is similar to using a cursor, but it is faster and more transparent.
+
+You can enable the streaming support:
+
+  DB.extension(:pg_streaming)
+
+Then you can stream individual datasets:
+
+  DB[:table].stream.each{|row| }
+
+Or stream all datasets by default:
+
+  DB.stream_all_queries = true