viking-sequel 3.10.0

data/doc/opening_databases.rdoc

@@ -0,0 +1,296 @@
+= Connecting to a database
+
+All Sequel activity begins with connecting to a database, which creates a
+Sequel::Database object. The Database object is used to create datasets and execute
+queries. Sequel provides a powerful and flexible mechanism for connecting to
+databases.  There are two main ways to establish database connections:
+
+1. Using the Sequel.connect method
+2. Using the specialized adapter method (Sequel.sqlite, Sequel.postgres, etc.)
+
+The connection options needed depend on the adapter being used, though most adapters
+share the same basic connection options.
+
+If you are only connecting to a single database, it is recommended that you store the
+database object in a constant named DB.  This should never be required, but it is the
+convention that most Sequel code uses.
+
+== Using the Sequel.connect method
+
+The connect method usually takes a well-formed URI, which is parsed into connection options needed to open
+the database connection.  The scheme/protocol part of the URI is used to determine the adapter to use:
+
+  DB = Sequel.connect('postgres://user:password@localhost/blog') # Uses the postgres adapter
+
+You can use URI query parameters to specify options:
+
+  DB = Sequel.connect('postgres://localhost/blog?user=user&password=password')
+
+You can also pass an additional option hash with the connection string:
+
+  DB = Sequel.connect('postgres://localhost/blog' :user=>'user', :password=>'password')
+
+You can also just use an options hash without a connection string.  If you do this, you must
+provide the adapter to use:
+
+  DB = Sequel.connect(:adapter=>'postgres', :host=>'localhost', :database=>'blog', :user=>'user', :password=>'password')
+
+All of the above statements are equivalent.
+
+== Using the specialized adapter method
+
+The specialized adapter method is similar to Sequel.connect with an options hash, except that it
+automatically populates the :adapter option and assumes the first argument is the :database option,
+unless the first argument is a hash. So the following statements are equivalent to the previous statements.
+
+  DB = Sequel.postgres('blog', :host=>'localhost', :user=>'user', :password=>'password')
+  DB = Sequel.postgres(:host=>'localhost', :user=>'user', :password=>'password', :database=>'blog')
+
+== Passing a block to either method
+
+Both the Sequel.connect method and the specialized adapter methods take a block.  If you
+provide a block to the method, Sequel will create a Database object and pass it as an argument
+to the block.  When the block returns, Sequel will disconnect the database connection.
+For example:
+
+  Sequel.connect('sqlite://blog.db'){|db| puts db[:users].count}  
+
+== General connection options
+
+These options are shared by all adapters unless otherwise noted.
+
+* :adapter - The adapter to use
+* :database - The name of the database to which to connect
+* :default_schema - The database schema to use by default.
+* :host - The hostname of the database server to which to connect
+* :logger - An array of SQL loggers to log to
+* :loggers - An array of SQL loggers to log to
+* :password - The password for the user account
+* :servers - A hash with symbol keys and hash or proc values, used with master/slave/partitioned database configurations
+* :single_threaded - Whether to use a single-threaded (non-thread safe) connection pool
+* :test - Whether to test that a valid database connection can be made (false by default)
+* :user - The user account name to use logging in
+
+The following options can be specified and are passed to the the database's internal connection pool.
+
+* :after_connect - A proc called after a new connection is made, with the connection object (default: nil)
+* :max_connections - The maximum size of the connection pool (default: 4 connections on most databases)
+* :pool_sleep_time - The number of seconds to sleep before trying to acquire a connection again (default: 0.001 seconds)
+* :pool_timeout - The number of seconds to wait if a connection cannot be acquired before raising an error (default: 5 seconds)
+
+== Adapter specific connection options
+
+The following sections explain the options and behavior specific to each adapter.
+If the library the adapter requires is different from the name of the adapter
+scheme, it is listed specifically, otherwise you can assume that is requires the
+library with the same name.
+
+=== ado
+
+Requires: win32ole 
+
+The ADO adapter provides connectivity to ADO databases in Windows. It relies
+on WIN32OLE library, so it isn't usable on other operating systems (except
+possibly through WINE, but that's fairly unlikely).
+
+The following options are supported:
+* :driver - The driver to use.  The default if not specified is 'SQL Server'.
+* :command_timeout - Sets the time in seconds to wait while attempting
+  to execute a command before cancelling the attempt and generating
+  an error. Specifically, it sets the ADO CommandTimeout property.
+  If this property is not set, the default of 30 seconds is used.
+* :conn_string - The full ADO connection string.  If this is provided,
+  the general connection options are ignored.
+* :provider - Sets the Provider of this ADO connection (for example, "SQLOLEDB")
+
+=== amalgalite 
+
+Amalgalite is an ruby extension that provides self contained access to SQLite,
+so you don't need to install SQLite separately.  As amalgalite is a file backed
+database, the :host, :user, and :password options are not used.
+
+* :database - The name of the database file
+* :timeout - The busy timeout period given in milliseconds
+
+Without a database argument, assumes a memory database, so you can do:
+
+  Sequel.amalgalite
+
+Handles paths in the connection string similar to the SQLite adapter, so see
+the sqlite section below for details.
+
+=== db2 
+
+Requires: db2/db2cli
+
+I'm not even sure exactly how this works, or if it works at all (I've never heard from
+anyone who attempted to use it).  It uses the SQL_HANDLE_DBC constant to
+get a handle, and respects the :database, :user, and :password options.  It doesn't
+appear to respect the :host or :port options.
+
+=== dbi 
+
+Allows access to a multitude of databases via ruby-dbi.  Additional options:
+
+* :db_type - Specifying 'mssql' allows Microsoft SQL Server specific syntax to
+  be used.  Otherwise has no effect.
+
+DBI connection strings are a preprocessed a bit, and are specified with a dbi-
+in front of the protocol.  Examples:
+
+  dbi-ado://...
+  dbi-db2://...
+  dbi-frontbase://...
+  dbi-interbase://...
+  dbi-msql://...
+  dbi-mysql://...
+  dbi-odbc://...
+  dbi-oracle://...
+  dbi-pg://...
+  dbi-proxy://...
+  dbi-sqlite://...
+  dbi-sqlrelay://...
+
+While the DBI adapter does work, it is recommended that you use another adapter
+if your database supports it.
+
+=== do 
+
+Requires: data_objects
+
+The DataObjects adapter supports PostgreSQL, MySQL, and SQLite.  One possible
+advantage of using DataObjects is that it does the typecasting in C, which may
+be faster than the other adapters.
+
+Similar to the JDBC adapter, the DO adapter only cares about connection strings,
+which can either be the String argument given to Sequel.connect directly or contained
+in a :uri or :url option.  The DO adapter passes through the connection string
+directly to DataObjects, it does no processing of it.
+
+Connection string examples:
+
+  do:sqlite3::memory:
+  do:postgres://user:password@host/database
+  do:mysql://user:password@host/database
+
+=== firebird 
+
+Requires: fb (using code at http://github.com/wishdev/fb)
+
+Does not support the :port option.
+
+=== informix 
+
+Does not support the :host or :port options.
+
+=== jdbc 
+
+Requires: java
+
+Houses Sequel's JDBC support when running on JRuby.
+Support for individual database types is done using sub adapters.
+There are currently subadapters for PostgreSQL, MySQL, SQLite, H2,
+Oracle, MSSQL, and AS400.  All except Oracle, MSSQL, and AS400 can load the
+JDBC gem, for those you need to have the .jar in your CLASSPATH
+or load the Java class manually.
+
+You just use the JDBC connection string directly, which can be specified
+via the string given to Sequel.connect or via the :uri, :url, or :database options.
+Sequel does no preprocessing of the string, it passes it directly to JDBC.
+So if you have problems getting a connection string to work, look up the JDBC
+documentation.
+
+Example connections strings:
+
+  jdbc:sqlite::memory:
+  jdbc:postgresql://localhost/database?user=username
+  jdbc:mysql://localhost/test?user=root&password=root
+  jdbc:h2:mem:
+  
+You can also use JNDI connection strings:
+
+  jdbc:jndi:java:comp/env/jndi_resource_name
+
+The following additional options are supported:
+
+* :convert_types - If set to false, does not attempt to convert some Java types to ruby types.
+  Setting to false roughly doubles performance when selecting large numbers of rows.
+  Note that you can't provide this option inside the connection string (as that is passed
+  directly to JDBC), you have to pass it as a separate option.
+
+=== mysql 
+
+The MySQL adapter does not support the pure-ruby MySQL adapter that used to ship with
+ActiveRecord, it requires the native adapter.
+
+The following additional options are supported:
+
+* :auto_is_null - If set to true, makes "WHERE primary_key IS NULL" select the last inserted id.
+* :charset - Same as :encoding, :encoding takes precedence.
+* :compress - Whether to compress data sent/received via the socket connection.
+* :config_default_group - The default group to read from the in the MySQL config file.
+* :config_local_infile - If provided, sets the Mysql::OPT_LOCAL_INFILE option on the connection with the given value.
+* :encoding - Specify the encoding/character set to use for the connection.
+* :socket - Can be used to specify a Unix socket file to connect to instead of a TCP host and port.
+* :timeout - Sets the wait_timeout for the connection, defaults to 1 month.
+
+=== odbc 
+
+The ODBC adapter allows you to connect to any database with the appropriate ODBC drivers installed.  
+The :database option given ODBC database should be the DSN (Descriptive Service Name) from the ODBC configuration.
+
+  Sequel.odbc('mydb', :user => "user", :password => "password")
+
+The :host and :port options are not respected. The following additional options are supported:
+
+* :db_type - Can be specified as 'mssql' or 'progress' to use SQL syntax specific to those databases.
+* :driver - The name of the ODBC driver to utilize.
+
+=== openbase 
+
+The :port option is ignored.
+
+=== oracle 
+
+Requires: oci8
+
+The following additional options are supported:
+
+* :privilege - The Oracle privilege level.
+
+=== postgres
+
+Requires: pg (or postgres if pg is not available)
+
+The Sequel postgres adapter works with the pg, postgres, and postgres-pr ruby libraries.
+The pg library is the best supported, as it supports real bound variables and prepared statements.
+
+The following additional options are supported:
+
+* :charset - Same as :encoding, :encoding takes precedence
+* :encoding - Set the client_encoding to the given string
+
+=== sqlite
+
+As SQLite is a file-based database, the :host and :port options are ignored, and
+the :database option should be a path to the file.
+
+Examples:
+
+  # In Memory databases:
+  Sequel.sqlite
+  Sequel.connect('sqlite:/') 
+  Sequel.sqlite(':memory:')
+
+  # Relative Path
+  Sequel.sqlite('blog.db')
+  Sequel.sqlite('./blog.db')
+  Sequel.connect('sqlite://blog.db')
+
+  # Absolute Path
+  Sequel.sqlite('/var/sqlite/blog.db')
+  Sequel.connect('sqlite:///var/sqlite/blog.db') 
+
+The following additional options are supported:
+
+* :timeout - the busy timeout to use in milliseconds (default: 5000).

data/doc/prepared_statements.rdoc

@@ -0,0 +1,104 @@
+= Prepared Statements and Bound Variables
+
+Sequel has support for prepared statements and bound variables.  No matter which
+database you are using, the Sequel prepared statement/bound variable API remains
+the same.  There is native support for prepared statements/bound variables on
+the following databases:
+
+* PostgreSQL (using the pg driver, requires type specifiers)
+* MySQL (prepared statements only, as the ruby mysql driver doesn't support
+  bound variables)
+* SQLite (a new native prepared statement is used for each call, though)
+* JDBC
+
+Support on other databases is emulated via string interpolation.
+
+== Placeholders
+
+Generally, when using prepared statements (and certainly when using bound
+variables), you need to put placeholders in your SQL to indicate where you
+want your bound arguments to appear.  Database support and syntax vary
+significantly for placeholders (e.g. :name, $1, ?).  Sequel abstracts all of
+that and allows you to specify placeholders by using the :$name format for
+placeholders, e.g.:
+
+  ds = DB[:items].filter(:name=>:$n)
+
+== Bound Variables
+
+Using bound variables for this query is simple:
+
+  ds.call(:select, :n=>'Jim')
+
+This will do the equivalent of selecting records that have the name 'Jim'. It
+returns all records, and can take a block that is passed to Dataset#all.
+
+Deleting or returning the first record works similarly:
+
+  ds.call(:first, :n=>'Jim') # First record with name 'Jim'
+  ds.call(:delete, :n=>'Jim') # Delete records with name 'Jim'
+
+For inserting/updating records, you should also specify a value hash, which
+may itself contain placeholders:
+
+  # Insert record with 'Jim', note that the previous filter is ignored
+  ds.call(:insert, {:n=>'Jim'}, :name=>:$n)
+  # Change name to 'Bob' for all records with name of 'Jim'
+  ds.call(:update, {:n=>'Jim', :new_n=>'Bob'}, :name=>$:new_n)
+
+== Prepared Statements
+
+Prepared statement support is similar to bound variable support, but you
+use Dataset#prepare with a name, and Dataset#call or Database#call later with the values:
+
+  ds = DB[:items].filter(:name=>:$n)
+  ps = ds.prepare(:select, :select_by_name)
+  ps.call(:n=>'Jim')
+  DB.call(:select_by_name, :n=>'Jim') # same as above
+
+The Dataset#prepare method returns a prepared statement, and also stores a
+copy of the prepared statement in the database for later use.  For insert
+and update queries, the hash to insert/update is passed to prepare:
+
+  ps1 = DB[:items].prepare(:insert, :insert_with_name, :name=>:$n)
+  ps1.call(:n=>'Jim')
+  DB.call(:insert_with_name, :n=>'Jim') # same as above
+  ds = DB[:items].filter(:name=>:$n)
+  ps2 = ds.prepare(:update, :update_name, :name=>:$new_n)
+  ps2.call(:n=>'Jim', :new_n=>'Bob')
+  DB.call(:update_name, :n=>'Jim', :new_n=>'Bob') # same as above
+
+== Database support
+
+=== PostgreSQL
+
+If you are using the ruby-postgres or postgres-pr driver, PostgreSQL uses the
+default emulated support.  If you are using ruby-pg, there is native support,
+but it requires type specifiers most of the time.  This is easy if you have
+direct control over the SQL string, but since Sequel abstracts that, the types
+have to be specified another way.  This is done by adding a __* suffix to the
+placeholder symbol (e.g. :$name__text, which will be compiled to "$1::text"
+in the SQL).  Prepared statements are always server side.
+
+=== SQLite
+
+SQLite supports bound variables and prepared statements exactly the same, since
+a new native prepared statement is created and executed for each call.
+
+=== MySQL
+
+The MySQL ruby driver does not support bound variables, so the the bound
+variable methods fall back to string interpolation.  It uses server side
+prepared statements.
+
+=== JDBC
+
+JDBC supports both prepared statements and bound variables.  Whether these
+are server side or client side depends on the JDBC driver.  For PostgreSQL
+over JDBC, you can add the prepareThreshold=N parameter to the connection
+string, which will use a server side prepared statement after N calls to
+the prepared statement.
+
+=== All Others
+
+Support is emulated using interpolation.

data/doc/reflection.rdoc

@@ -0,0 +1,84 @@
+= Reflection
+
+Sequel supports reflection information in multiple ways.
+
+== Adapter in Use
+
+You can get the adapter in use using Database.adapter_scheme.  As this is a class method, you generally need to do DB.class.adapter_scheme:
+
+  DB.class.adapter_scheme # e.g. :postgres, :jdbc, :odbc
+
+== Database Connected To
+
+In some cases, the adapter scheme will be the same as the database to which you are connecting.  However, many adapters support multiple databases.  You can use the Database#database_type method to get the type of database to which you are connecting:
+
+  DB.database_type # :postgres, :h2, :mssql
+
+== Tables in the Database
+
+On many database types/adapters, Database#tables exists and gives an array of table name symbols:
+
+  DB.tables # [:table1, :table2, :table3, ...]
+
+== Indexes on a table
+
+On a few database types/adapters, Database#indexes takes a table name gives a hash of index information.  Keys are index names, values are subhashes with the keys :columns and :unique :
+
+  DB.indexes(:table1) # {:index1=>{:columns=>[:column1], :unique=>false}, :index2=>{:columns=>[:column2, :column3], :unique=>true}}
+
+Index information generally does not include partial indexes, functional indexes, or indexes on the primary key of the table.
+
+== Column Information for a Table
+
+Database#schema takes a table symbol and returns column information in an array with each element being an array with two elements.  The first elements of the subarray is a column symbol, and the second element is a hash of information about that column.  The hash should include the following keys:
+
+* :allow_null - Whether NULL/nil is an allowed value for this column. Used by the Sequel::Model typecasting code.
+* :db_type - The type of column the database provided, as a string.  Used by the schema_dumper plugin for a more specific type translation.
+* :default - The default value of the column, as either a string or nil.  Uses a database specific format. Used by the schema_dumper plugin for converting to a ruby value.
+* :primary_key - Whether this column is one of the primary key columns for the table.  Used by the Sequel::Model code to determine primary key columns.
+* :ruby_default - The default value of the column as a ruby object, or nil if there is no default or the default could not be successfully parsed into a ruby object.
+* :type - The type of column, as a symbol (e.g. :string).  Used by the Sequel::Model typecasting code.
+
+Example:
+
+  DB.schema(:table) # [[:column1, {:allow_null=>true, :db_type=>'varchar(255)', :default=>'blah', :primary_key=>false, :type=>:string}], ...]
+
+== Column Information for a Model
+
+Model#db_schema returns pretty much the same information, except it returns it as a hash with column keys instead of an array of two element arrays.
+
+  Model.db_schema # {:column1=>{:allow_null=>true, :db_type=>'varchar(255)', :default=>'blah', :primary_key=>false, :type=>:string}, ...}
+
+== Columns used by a dataset/model
+
+Dataset#columns returns the columns of the current dataset as an array of symbols:
+
+  DB[:table].columns # [:column1, :column2, :column3, ...]
+
+Dataset#columns! does the same thing, except it ignores any cached value.  In general, the cached value should never be incorrect, unless the database schema is changed after the dataset is created.
+
+  DB[:table].columns! # [:column1, :column2, :column3, ...]
+
+Model.columns does the same thing as Dataset#columns, using the model's dataset:
+
+  Model.columns # [:column1, :column2, :column3, ...]
+
+== Associations Defined
+
+Sequel::Model offers complete introspection capability for all associations.
+
+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):
+
+  Model.association_reflection(:association1) # {:name=>:association1, :type=>:many_to_one, :model=>Model, :associated_class=>OtherModel, ...}
+
+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, :associated_class=>OtherModel, ...}, ...]
+
+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, :associated_class=>OtherModel, ...}, ...}