sequel 4.36.0 → 5.61.0

data/doc/bin_sequel.rdoc

@@ -10,9 +10,7 @@ This is very useful for quick testing of ideas, and does not affect the environm
 
 If you've installed the sequel gem, then just running "sequel" should load the program, since rubygems should place the sequel binary in your load path.  However, if you want to run bin/sequel from the root of a repository checkout, you should probably do:
 
-  ruby -I lib bin/sequel
-
-The -I lib makes sure that you are using the repository checkout's code.
+  ruby bin/sequel
 
 == Choosing the Database to Connect to
 
@@ -91,6 +89,8 @@ To save this information to a file, use a standard shell redirection:
 
 The -d option dumps the migration in database-independent format, the -D option dumps it in database-specific format.
 
+Note that the support for dumping schema is fairly limited.  It doesn't handle database views, functions, triggers, schemas, partial indexes, functional indexes, and many other things.  You should probably use the database specific tools to handle those.
+
 The -S option dumps the schema cache for all tables in the database, which can speed up the usage of Sequel with models when using the schema_caching extension.  You should provide this option with the path to which to dump the schema:
 
   sequel -S /path/to/schema_cache.db postgres://host/database
@@ -103,6 +103,8 @@ Using the -C option, Sequel can copy the contents of one database to another, ev
 
 This copies the table structure, table data, indexes, and foreign keys from the MySQL database to the PostgreSQL database.
 
+Note that the support for copying is fairly limited.  It doesn't handle database views, functions, triggers, schemas, partial indexes, functional indexes, and many other things. Also, the data type conversion may not be exactly what you want.  It is best designed for quick conversions and testing.  For serious production use, use the database's tools to copy databases for the same database type, and for different database types, use the Sequel API.
+
 == Other Options
 
 Other options not mentioned above are explained briefly here.

data/doc/cheat_sheet.rdoc

@@ -6,7 +6,7 @@
 
   DB = Sequel.sqlite('my_blog.db')
   DB = Sequel.connect('postgres://user:password@localhost/my_db')
-  DB = Sequel.postgres('my_db', :user => 'user', :password => 'password', :host => 'localhost')
+  DB = Sequel.postgres('my_db', user: 'user', password: 'password', host: 'localhost')
   DB = Sequel.ado('mydb')
 
 == Open an SQLite memory database
@@ -18,7 +18,7 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 == Logging SQL statements
 
   require 'logger'
-  DB = Sequel.sqlite '', :loggers => [Logger.new($stdout)]
+  DB = Sequel.sqlite(loggers: [Logger.new($stdout)])
   # or
   DB.loggers << Logger.new($stdout)
 
@@ -38,22 +38,32 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 == Most dataset methods are chainable
 
-  dataset = DB[:managers].where(:salary => 5000..10000).order(:name, :department)
+  dataset = DB[:managers].where(salary: 5000..10000).order(:name, :department)
 
 == Insert rows
 
-  dataset.insert(:name => 'Sharon', :grade => 50)
+  dataset.insert(name: 'Sharon', grade: 50)
 
 == Retrieve rows
 
   dataset.each{|r| p r}
   dataset.all # => [{...}, {...}, ...]
   dataset.first # => {...}
+  dataset.last # => {...}
 
 == Update/Delete rows
 
   dataset.exclude(:active).delete
-  dataset.where('price < ?', 100).update(:active => true)
+  dataset.where{price < 100}.update(:active => true)
+  dataset.where(:active).update(:price => Sequel[:price] * 0.90)
+
+= Merge rows
+
+  dataset.
+    merge_using(:table, col1: :col2).
+    merge_insert(col3: :col4).
+    merge_delete{col5 > 30}.
+    merge_update(col3: Sequel[:col3] + :col4)
 
 == Datasets are Enumerable
 
@@ -67,8 +77,7 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 === Equality
 
-  dataset.where(:name => 'abc')
-  dataset.where('name = ?', 'abc')
+  dataset.where(name: 'abc')
 
 === Inequality
 
@@ -77,45 +86,49 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 === Inclusion
 
-  dataset.where(:value => 50..100)
+  dataset.where(value: 50..100)
   dataset.where{(value >= 50) & (value <= 100)}
 
-  dataset.where('value IN ?', [50,75,100])
-  dataset.where(:value=>[50,75,100])
-
-  dataset.where(:id=>other_dataset.select(:other_id))
+  dataset.where(value: [50,75,100])
+  dataset.where(id: other_dataset.select(:other_id))
 
 === Subselects as scalar values
 
-  dataset.where('price > (SELECT avg(price) + 100 FROM table)')
   dataset.where{price > dataset.select(avg(price) + 100)}
 
 === LIKE/Regexp
 
   DB[:items].where(Sequel.like(:name, 'AL%'))
-  DB[:items].where(:name => /^AL/)
+  DB[:items].where(name: /^AL/)
 
 === AND/OR/NOT
 
-  DB[:items].where{(x > 5) & (y > 10)}.sql 
+  DB[:items].where{(x > 5) & (y > 10)} 
   # SELECT * FROM items WHERE ((x > 5) AND (y > 10))
 
-  DB[:items].where(Sequel.or(:x => 1, :y => 2) & Sequel.~(:z => 3)).sql 
+  DB[:items].where(Sequel.or(x: 1, y: 2) & Sequel.~(z: 3)) 
   # SELECT * FROM items WHERE (((x = 1) OR (y = 2)) AND (z != 3))
 
 === Mathematical operators
 
-  DB[:items].where{x + y > z}.sql 
+  DB[:items].where{x + y > z} 
   # SELECT * FROM items WHERE ((x + y) > z)
 
-  DB[:items].where{price - 100 < avg(price)}.sql 
+  DB[:items].where{price - 100 < avg(price)} 
   # SELECT * FROM items WHERE ((price - 100) < avg(price))
 
+=== Raw SQL Fragments
+
+  dataset.where(Sequel.lit('id= 1'))
+  dataset.where(Sequel.lit('name = ?', 'abc'))
+  dataset.where(Sequel.lit('value IN ?', [50,75,100]))
+  dataset.where(Sequel.lit('price > (SELECT avg(price) + 100 FROM table)'))
+
 == Ordering
 
-  dataset.order(:kind)
-  dataset.reverse_order(:kind)
-  dataset.order(Sequel.desc(:kind), :name)
+  dataset.order(:kind) # kind
+  dataset.reverse(:kind) # kind DESC
+  dataset.order(Sequel.desc(:kind), :name) # kind DESC, name
 
 == Limit/Offset
 
@@ -125,11 +138,12 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 == Joins
 
-  DB[:items].left_outer_join(:categories, :id => :category_id).sql 
+  DB[:items].left_outer_join(:categories, id: :category_id) 
   # SELECT * FROM items
   # LEFT OUTER JOIN categories ON categories.id = items.category_id
 
-  DB[:items].join(:categories, :id => :category_id).join(:groups, :id => :items__group_id) 
+  DB[:items].join(:categories, id: :category_id).
+    join(:groups, id: Sequel[:items][:group_id]) 
   # SELECT * FROM items
   # INNER JOIN categories ON categories.id = items.category_id
   # INNER JOIN groups ON groups.id = items.group_id
@@ -142,79 +156,100 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
   dataset.avg(:price)
   dataset.sum(:stock)
 
-  dataset.group_and_count(:category)
+  dataset.group_and_count(:category).all
   dataset.select_group(:category).select_append{avg(:price)}
 
 == SQL Functions / Literals
 
-  dataset.update(:updated_at => Sequel.function(:NOW))
-  dataset.update(:updated_at => Sequel.lit('NOW()'))
+  dataset.update(updated_at: Sequel.function(:NOW))
+  dataset.update(updated_at: Sequel.lit('NOW()'))
 
-  dataset.update(:updated_at => Sequel.lit("DateValue('1/1/2001')"))
-  dataset.update(:updated_at => Sequel.function(:DateValue, '1/1/2001'))
+  dataset.update(updated_at: Sequel.lit("DateValue('1/1/2001')"))
+  dataset.update(updated_at: Sequel.function(:DateValue, '1/1/2001'))
 
 == Schema Manipulation
 
   DB.create_table :items do
     primary_key :id
-    String :name, :unique => true, :null => false
-    TrueClass :active, :default => true
+    String :name, unique: true, null: false
+    TrueClass :active, default: true
     foreign_key :category_id, :categories
-    DateTime :created_at
+    DateTime :created_at, default: Sequel::CURRENT_TIMESTAMP, :index=>true
     
-    index :created_at
+    index [:category_id, :active]
   end
 
   DB.drop_table :items
 
 == Aliasing
 
+  DB[:items].select(Sequel[:name].as(:item_name))
   DB[:items].select(Sequel.as(:name, :item_name))
-  DB[:items].select(:name___item_name)
-  DB[:items___items_table].select(:items_table__name___item_name)
+  DB[:items].select{name.as(:item_name)}
+  # SELECT name AS item_name FROM items
+
+  DB[Sequel[:items].as(:items_table)].select{items_table[:name].as(:item_name)}
   # SELECT items_table.name AS item_name FROM items AS items_table
 
 == Transactions
 
   DB.transaction do
-    dataset.insert(:first_name => 'Inigo', :last_name => 'Montoya')
-    dataset.insert(:first_name => 'Farm', :last_name => 'Boy')
-  end # Either both are inserted or neither are inserted
+    # BEGIN
+    dataset.insert(first_name: 'Inigo', last_name: 'Montoya')
+    dataset.insert(first_name: 'Farm', last_name: 'Boy')
+  end
+  # COMMIT
 
-Database#transaction is re-entrant:
 
-  DB.transaction do # BEGIN issued only here
+Transactions are reentrant:
+
+  DB.transaction do
+    # BEGIN
     DB.transaction do
-      dataset << {:first_name => 'Inigo', :last_name => 'Montoya'}
+      dataset.insert(first_name: 'Inigo', last_name: 'Montoya')
     end
-  end # COMMIT issued only here
+  end
+  # COMMIT
 
 Transactions are aborted if an error is raised:
 
   DB.transaction do
+    # BEGIN
     raise "some error occurred"
-  end # ROLLBACK issued and the error is re-raised
+  end
+  # ROLLBACK issued and the error is re-raised
 
 Transactions can also be aborted by raising Sequel::Rollback:
 
   DB.transaction do
-    raise(Sequel::Rollback) if something_bad_happened
-  end # ROLLBACK issued and no error raised
+    # BEGIN
+    raise(Sequel::Rollback)
+  end
+  # ROLLBACK issued and no error raised
 
 Savepoints can be used if the database supports it:
 
   DB.transaction do
-    dataset << {:first_name => 'Farm', :last_name => 'Boy'} # Inserted
-    DB.transaction(:savepoint=>true) do # This savepoint is rolled back
-      dataset << {:first_name => 'Inigo', :last_name => 'Montoya'} # Not inserted
-      raise(Sequel::Rollback) if something_bad_happened
+    dataset.insert(first_name: 'Farm', last_name: 'Boy') # Inserted
+    DB.transaction(savepoint: true) do # This savepoint is rolled back
+      dataset.insert(first_name: 'Inigo', last_name: 'Montoya') # Not inserted
+      raise(Sequel::Rollback)
     end
-    dataset << {:first_name => 'Prince', :last_name => 'Humperdink'} # Inserted
+    dataset.insert(first_name: 'Prince', last_name: 'Humperdink') # Inserted
   end
 
-== Miscellaneous:
+== Retrieving SQL
 
   dataset.sql # "SELECT * FROM items"
+  dataset.insert_sql(a: 1) # "INSERT INTO items (a) VALUES (1)"
+  dataset.update_sql(a: 1) # "UPDATE items SET a = 1"
   dataset.delete_sql # "DELETE FROM items"
-  dataset.columns # => array of columns in the result set, does a SELECT
+
+== Basic introspection
+
+  dataset.columns # => [:id, :name, ...]
+  DB.tables # => [:items, ...]
+  DB.views # => [:new_items, ...]
   DB.schema(:items) # => [[:id, {:type=>:integer, ...}], [:name, {:type=>:string, ...}], ...]
+  DB.indexes(:items) # => {:index_name => {:columns=>[:a], :unique=>false}, ...}
+  DB.foreign_key_list(:items) # => [{:name=>:items_a_fk, :columns=>[:a], :key=>[:id], :table=>:other_table}, ...]

data/doc/code_order.rdoc

@@ -1,13 +1,13 @@
 = Code Order
 
-In Sequel, the order in which code is executed is important.  This
+In Sequel, the order in which code is executed during initialization is important.  This
 guide provides the recommended way to order your Sequel code.  Some
 of these guidelines are not strictly necessary, but others are, and
 this guide will be specific about which are strictly necessary.
 
 == Require Sequel
 
-This is sort of a no brainer, but you need to require the library
+This is sort of a no-brainer, but you need to require the library
 first.  This is a strict requirement, none of the other code can
 be executed unless the library has been required first. Example:
 
@@ -18,13 +18,6 @@ be executed unless the library has been required first. Example:
 Global extensions are loaded with Sequel.extension, and affect
 other parts of Sequel or the general ruby environment.  It's not
 necessary to load them first, but it is a recommended practice.
-
-The exception to this is global extensions that integrate with
-Database-specific extensions, where the Database-specific
-extension should be loaded first (such as some of the pg_*
-extensions).  In those cases, the global extensions should be
-loaded after the Database-specific extensions.
-
 Example:
 
   Sequel.extension :blank
@@ -77,20 +70,33 @@ copied into the subclass when model subclasses are created.  Example:
 == Load Model Classes
 
 After you have established a database connection, and configured your
-global model configration and global plugins, you can load your model
+global model configuration and global plugins, you can load your model
 classes.  It's recommended to have a separate file for each model class,
 unless the model classes are very simple.  Example:
 
   Dir['./models/*.rb'].each{|f| require f}
 
-== Disconnect If Using Forking Webserver with Code Preloading
+== Finalize Associations and Freeze Model Classes and Database
+
+After all the models have been setup, you can finalize the associations.
+This can speed up association reflection methods by doing a lookup in
+advance to find the associated class, and cache related association
+information in the association itself.
+
+Additionally, in production and testing, you should freeze the
+model classes and Database instance, so that you can detect
+unsafe runtime modification of the configuration:
+
+  model_classes.each(&:finalize_associations)
+  model_classes.each(&:freeze)
+  DB.freeze
 
-If you are using a forking webserver such as unicorn or passenger, with
-a feature that loads your Sequel code before forking connections (code
-preloading), then you must disconnect your database connections before
-forking.  If you don't do this, you can end up with child processes
-sharing database connections and all sorts of weird behavior.  Sequel
-will automatically reconnect on an as needed basis in the child
-processes, so you only need to do the following in the parent process:
+The `subclasses` plugin can be used to keep track of all model classes
+that have been setup in your application. Finalizing their associations
+and freezing them can easily be achieved through the plugin:
 
-  DB.disconnect
+  # Register the plugin before setting up the models
+  Sequel::Model.plugin :subclasses
+  # ... setup models
+  # Now finalize associations & freeze models by calling the plugin:
+  Sequel::Model.freeze_descendents