sequel 5.83.1 → 5.84.0

data/doc/bin_sequel.rdoc

@@ -1,146 +0,0 @@
-= bin/sequel
-
-bin/sequel is the name used to refer to the "sequel" command line tool that ships with the sequel gem.  By default, bin/sequel provides an IRB shell with the +DB+ constant set to a Sequel::Database object created using the database connection string provided on the command line.  For example, to connect to a new in-memory SQLite database using the sqlite adapter, you can use the following:
-
-  sequel sqlite:/
-
-This is very useful for quick testing of ideas, and does not affect the environment, since the in-memory SQLite database is destroyed when the program exits.
-
-== Running from a git checkout
-
-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 bin/sequel
-
-== Choosing the Database to Connect to
-
-=== Connection String
-
-In general, you probably want to provide a connection string argument to bin/sequel, indicating the adapter and database connection information you want to use.  For example:
-
-  sequel sqlite:/
-  sequel postgres://user:pass@host/database_name
-  sequel mysql2://user:pass@host/database_name
-
-See the {Connecting to a database guide}[rdoc-ref:doc/opening_databases.rdoc] for more details about and examples of connection strings.
-
-=== YAML Connection File
-
-Instead of specifying the database connection using a connection string, you can provide the path to a YAML configuration file containing the connection information.  This YAML file can contain a single options hash, or it can contain a nested hash, where the top-level hash uses environment keys with hash values for
-each environment.  Using the -e option with a yaml connection file, you can choose which environment to use if using a nested hash.
-
-  sequel -e production config/database.yml
-
-Note that bin/sequel does not directly support ActiveRecord YAML configuration files, as they use different names for some options.
-
-=== Mock Connection
-
-If you don't provide a connection string or YAML connection file, Sequel will start with a mock database.  The mock database allows you to play around with Sequel without any database at all, and can be useful if you just want to test things out and generate SQL without actually getting results from a database.
-
-  sequel
-
-Sequel also has the ability to use the mock adapter with database-specific syntax, allowing you to pretend you are connecting to a specific type of database without actually connecting to one.  To do that, you need to use a connection string:
-
-  sequel mock://postgres
-
-== Not Just an IRB shell
-
-bin/sequel is not just an IRB shell, it can also do far more.
-
-=== Execute Code
-
-bin/sequel can also be used to execute other ruby files with +DB+ preset to the database given on the command line:
-
-  sequel postgres://host/database_name path/to/some_file.rb
-
-On modern versions of Linux, this means that you can use bin/sequel in a shebang line:
-
-  #!/path/to/bin/sequel postgres://host/database_name
-
-If you want to quickly execute a small piece of ruby code, you can use the -c option:
-
-  sequel -c "p DB.tables" postgres://host/database_name
-
-Similarly, if data is piped into bin/sequel, it will be executed:
-
-  echo "p DB.tables" | sequel postgres://host/database_name
-
-=== Migrate Databases
-
-With -m option, Sequel will migrate the database given using the migration directory provided by -m:
-
-  sequel -m /path/to/migrations/dir postgres://host/database
-
-You can use the -M attribute to set the version to migrate to:
-
-  sequel -m /path/to/migrations/dir -M 3 postgres://host/database
-
-See the {migration guide}[rdoc-ref:doc/migration.rdoc] for more details about migrations.
-
-=== Dump Schemas
-
-Using the -d or -D options, Sequel will dump the database's schema in Sequel migration format to the standard output:
-
-  sequel -d postgres://host/database
-
-To save this information to a file, use a standard shell redirection:
-
-  sequel -d postgres://host/database > /path/to/migrations/dir/001_base_schema.rb
-
-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
-
-=== Copy Databases
-
-Using the -C option, Sequel can copy the contents of one database to another, even between different database types.  Using this option, you provide two connection strings on the command line:
-
-  sequel -C mysql://host1/database postgres://host2/database2
-
-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.
-
-=== -E
-
--E logs all SQL queries to the standard output, so you can see all SQL that Sequel is sending the database.
-
-=== -I include_directory
-
--I is similar to ruby -I, and specifies an additional $LOAD_PATH directory.
-
-=== -l log_file
-
--l is similar to -E, but logs all SQL queries to the given file.
-
-=== -L load_directory
-
--L loads all *.rb files under the given directory.  This is usually used to load Sequel::Model classes into bin/sequel.
-
-=== -N
-
--N skips testing the connection when creating the Database object.  This is rarely needed.
-
-=== -r require_lib
-
--r is similar to ruby -r, requiring the given library.
-
-=== -t
-
--t tells bin/sequel to output full backtraces in the case of an error, which can aid in debugging.
-
-=== -h
-
--h prints the usage information for bin/sequel.
-
-=== -v
-
--v prints the Sequel version in use.

data/doc/cheat_sheet.rdoc

@@ -1,255 +0,0 @@
-= Cheat Sheet   
-
-== Open a database
-
-  require 'sequel'
-
-  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.ado('mydb')
-
-== Open an SQLite memory database
-
-Without a filename argument, the sqlite adapter will setup a new sqlite database in memory.
-
-  DB = Sequel.sqlite
-
-== Logging SQL statements
-
-  require 'logger'
-  DB = Sequel.sqlite(loggers: [Logger.new($stdout)])
-  # or
-  DB.loggers << Logger.new($stdout)
-
-== Using raw SQL
-
-  DB.run "CREATE TABLE users (name VARCHAR(255) NOT NULL, age INT(3) NOT NULL)"
-  dataset = DB["SELECT age FROM users WHERE name = ?", name]
-  dataset.map(:age)
-  DB.fetch("SELECT name FROM users") do |row|
-    p row[:name]
-  end
-
-== Create a dataset
-
-  dataset = DB[:items]
-  dataset = DB.from(:items)
-
-== Most dataset methods are chainable
-
-  dataset = DB[:managers].where(salary: 5000..10000).order(:name, :department)
-
-== Insert rows
-
-  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(: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
-
-  dataset.map{|r| r[:name]}
-  dataset.map(:name) # same as above
-
-  dataset.inject(0){|sum, r| sum + r[:value]}
-  dataset.sum(:value) # better
-
-== Filtering (see also {Dataset Filtering}[rdoc-ref:doc/dataset_filtering.rdoc])
-
-=== Equality
-
-  dataset.where(name: 'abc')
-
-=== Inequality
-
-  dataset.where{value > 100}
-  dataset.exclude{value <= 100}
-
-=== Inclusion
-
-  dataset.where(value: 50..100)
-  dataset.where{(value >= 50) & (value <= 100)}
-
-  dataset.where(value: [50,75,100])
-  dataset.where(id: other_dataset.select(:other_id))
-
-=== Subselects as scalar values
-
-  dataset.where{price > dataset.select(avg(price) + 100)}
-
-=== LIKE/Regexp
-
-  DB[:items].where(Sequel.like(:name, 'AL%'))
-  DB[:items].where(name: /^AL/)
-
-=== AND/OR/NOT
-
-  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)) 
-  # SELECT * FROM items WHERE (((x = 1) OR (y = 2)) AND (z != 3))
-
-=== Mathematical operators
-
-  DB[:items].where{x + y > z} 
-  # SELECT * FROM items WHERE ((x + y) > z)
-
-  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) # kind
-  dataset.reverse(:kind) # kind DESC
-  dataset.order(Sequel.desc(:kind), :name) # kind DESC, name
-
-== Limit/Offset
-
-  dataset.limit(30) # LIMIT 30
-  dataset.limit(30, 10) # LIMIT 30 OFFSET 10
-  dataset.limit(30).offset(10) # LIMIT 30 OFFSET 10
-
-== Joins
-
-  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: 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
-	
-== Aggregate functions methods
-
-  dataset.count #=> record count
-  dataset.max(:price)
-  dataset.min(:price)
-  dataset.avg(:price)
-  dataset.sum(:stock)
-
-  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.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
-    foreign_key :category_id, :categories
-    DateTime :created_at, default: Sequel::CURRENT_TIMESTAMP, index: true
-    
-    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.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
-    # BEGIN
-    dataset.insert(first_name: 'Inigo', last_name: 'Montoya')
-    dataset.insert(first_name: 'Farm', last_name: 'Boy')
-  end
-  # COMMIT
-
-
-Transactions are reentrant:
-
-  DB.transaction do
-    # BEGIN
-    DB.transaction do
-      dataset.insert(first_name: 'Inigo', last_name: 'Montoya')
-    end
-  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
-
-Transactions can also be aborted by raising Sequel::Rollback:
-
-  DB.transaction do
-    # BEGIN
-    raise(Sequel::Rollback)
-  end
-  # ROLLBACK issued and no error raised
-
-Savepoints can be used if the database supports it:
-
-  DB.transaction do
-    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.insert(first_name: 'Prince', last_name: 'Humperdink') # Inserted
-  end
-
-== 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"
-
-== 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,104 +0,0 @@
-= Code Order
-
-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
-first.  This is a strict requirement, none of the other code can
-be executed unless the library has been required first. Example:
-
-  require 'sequel'
-
-== Add Global Extensions
-
-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.
-Example:
-
-  Sequel.extension :blank
-
-== Add Extensions Applied to All Databases/Datasets
-
-If you want database or datasets extensions applied to all databases
-and datasets, you must use Sequel::Database.extension to load the
-extension before connecting to a database.  If you connect to a
-database before using Sequel::Database.extension, it will not have
-that extension loaded. Example:
-
-  Sequel::Database.extension :columns_introspection
-
-== Connect to Databases
-
-Connecting to a database is required before running any queries against
-that database, or creating any datasets or models.  You cannot create
-model classes without having a database object created first.  The
-convention for an application with a single Database instance is to
-store that instance in a constant named DB.  Example:
-
-  DB = Sequel.connect('postgres://user:pass@host/database')
-
-== Add Extensions Specific to a Database or All Datasets in that Database
-
-If you want specific databases to use specific extensions, or have all
-datasets in that database use a specific extension, you need to load that
-extension into the database after creating it using
-Sequel::Database#extension.  Example:
-
-  DB.extension :pg_array
-
-== Configure Global Model Behavior
-
-If you want to change the configuration for all model classes, you must do
-so before loading your model classes, as configuration is copied into the
-subclass when model subclasses are created.  Example:
-
-  Sequel::Model.raise_on_save_failure = false
-
-== Add Global Model Plugins
-
-If you want to load a plugin into all models classes, you must do so
-before loading your model classes, as plugin specific data may need to be
-copied into the subclass when model subclasses are created.  Example:
-
-  Sequel::Model.plugin :prepared_statements
-
-== Load Model Classes
-
-After you have established a database connection, and configured your
-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}
-
-== 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
-
-`model_classes` is not a Sequel method, it indicates an array of model
-classes you defined. Instead of listing them manually, 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:
-
-  # 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