@@ -1,5 +1,7 @@ === HEAD +* Add opening_databases.rdoc file for describing how to connect to a database (mwlang, jeremyevans) + * Significantly increase JDBC select performance (jeremyevans) * Slightly increase SQLite select performance using the native adapter (jeremyevans) CHANGELOG @@ -1,59 +1,98 @@ -= Opening Database += Connecting to a database -All Sequel activity begins with opening a database connection, thus you always need a database connection -before you can perform any other actions. Sequel provides a powerful and flexible mechanism for -opening database connections. There are three main approaches to opening and using a database connection: +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. Use the connect method -2. Use the specialized adapter method -3. Passing a block to the either of the above +1. Using the Sequel.connect method +2. Using the specialized adapter method (Sequel.sqlite, Sequel.postgres, etc.) -Each adapter has been extended to handle its specialized needs when establishing a connection, so there -may be cases where one approach applies to one adapter, but not to the other. +The connection options needed depend on the adapter being used, though most adapters +share the same basic connection options. -== Using the Connect Method -The connect method takes a well-formed uri, which is parsed into the appropriate adapter and database -connection parameters needed to open the database connection. Upon successfully opening the connection -to the database, a Database object is returned which then provides access to SQL and DDL statements -against the opened database connection. +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. -Creates a new database object based on the supplied connection string -and optional arguments. The specified scheme determines the database -class used, and the rest of the string specifies the connection options. +== 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 open the connection and pass it as an argument +to the block. When the block is exited, Sequel will disconnect the database connection. For example: - DB = Sequel.connect('postgres://user:password@localhost/blog') - DB = Sequel.connect('ado://blog') + Sequel.connect('sqlite://blog.db'){|db| puts db[:users].count} + +== General connection options -== Using specialized adapter method -The specialized adapter method of connecting to a database allows you to turn: +These options are shared by all adapters unless otherwise noted. - DB = Sequel.connect('postgres://user:password@localhost/my_db') +* :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 the single-threaded (non-thread safe) connection pool +* :user - The user account name to use logging in -into: - - DB = Sequel.postgres('my_db', :user => 'user', :password => 'password', :host => 'localhost') +The following options can be specified and are passed to the the database's internal connection pool. -The following databases demonstrate how to open each of the databases and the syntax idiosyncrasies of -opening each type. +* :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) -=== ADO +== Adapter specific connection options -The ADO adapter provides connectivity to ADO databases in Windows. ADO -databases can be opened using a URL with the ado schema: +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. - DB = Sequel.connect('ado://mydb') +=== ado -or using the Sequel.ado method: +Requires: win32ole - DB = Sequel.ado('mydb') +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 -* :host -* :database - The name of the database to use -* :user - The user account name for logging in. -* :password - credential token for logging in. +* :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. @@ -62,111 +101,179 @@ The following options are supported: === 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 - Timeout period given in milliseconds +* :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 -Not documented, yet. + +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 -Not documented, yet. + +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 -Not documented, yet. + +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 -Not documented, yet. + +Requires: fb (using code at http://github.com/wishdev/fb) + +Does not support the :port option. === informix -Not documented, yet. + +Does not support the :host or :port options. === jdbc -Not documented, yet. + +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, and MSSQL. All except Oracle and MSSQL 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: === mysql -=== odbc -The ODBC adapter allows you to connect to any database driver with the appropriate ODBC drivers installed. -ODBC is typically accessed via the Ruby DBI libraries configured with ODBC support. To connect to an -ODBC database, the DSN (Descriptive Service Name) from the ODBC configuration is utilized. +The MySQL adapter does not support the pure-ruby MySQL adapter that ships with +ActiveRecord, it requires the native adapter. - DB = Sequel.odbc('mydb', :user => "user", :password => "password") +The following additional options are supported: -For Transact SQL (Sybase and Microsoft SQL Server), non-ANSI SQL identifiers are encased in brackets. Thus, -you must indicate the :db_type as "mssql" for these databases. For example: +* :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. +* :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. - DB = Sequel.odbc('mydb', :user => "user", :password => "password", :db_type => "mssql") +=== odbc -Note: For table names with non-ANSI identifiers, you'll need to use the following notation when obtaining a dataset -with the shorthand approach: - dataset = DB[:"Some Table"] +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. -Which will result in the following SQL: - "SELECT * FROM [Some Table]" + Sequel.odbc('mydb', :user => "user", :password => "password") -The following options are supported: +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. -* :database - The name of the database to use. -* :user - The user account name for logging in. -* :password - credential token for logging in. === openbase -Not documented, yet. + +The :port option is ignored. === oracle - DB = Sequel.oracle('my_db', :user => 'user', :password => 'password', :host => 'localhost') +Requires: oci8 + +The following additional options are supported: -* :host - the server name or IP Address to connect to -* :port - the port the server listens on -* :database - The name of the database to use -* :user - The user account name for logging in. -* :password - credential token for logging in. * :privilege - The Oracle privilege level. === postgres - DB = Sequel.postgres('my_db', :user => 'user', :password => 'password', :host => 'localhost') +Requires: pg (or postgres if pg is not available) -* :host - the server name or IP Address to connect to -* :port - the port the server listens on -* :database - The name of the database to use -* :user - The user account name for logging in. -* :password - credential token for logging in. +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. -=== sqlite - -Without a filename argument, the sqlite adapter will setup a new sqlite database in memory. - DB = Sequel.sqlite - -This is equivalent to: - DB = Sequel.connect('sqlite:/') +The following additional options are supported: -and - DB = Sequel.sqlite(':memory:') +* :charset - Same as :encoding, :encoding takes precedence +* :encoding - Set the client_encoding to the given string -To open a sqlite connection on a specific file: - DB = Sequel.sqlite('my_blog.db') +=== sqlite -To open a sqlite database in the current application's directory: - DB = Sequel.connect('sqlite://blog.db') # ./blog.db +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. -To specify an absolute path, use three slashes: - DB = Sequel.connect('sqlite:///var/sqlite/blog.db') +Examples: -The maximum connections can be specified with the :max_connections option - DB = Sequel.connect('sqlite:///blog.db', :max_connections=>10) + # In Memory databases: + Sequel.sqlite + Sequel.connect('sqlite:/') + Sequel.sqlite(':memory:') -* :database - the database file name -* :max_connections - maximum connections to establish in the connection pool + # Relative Path + Sequel.sqlite('blog.db') + Sequel.sqlite('./blog.db') + Sequel.connect('sqlite://blog.db') -== Passing a ruby block to the connect method -The third way to utilize a Database connection is to open the connection only for the duration -needed to execute some chunk of code. + # Absolute Path + Sequel.sqlite('/var/sqlite/blog.db') + Sequel.connect('sqlite:///var/sqlite/blog.db') -Both the connect method and the various adapter scheme methods can be passed a block when -calling. This causes a connection to be opened, the block to be executed, and then the -database connection closed immediately upon return from the block. +The following additional options are supported: -For example: - Sequel.connect('sqlite://blog.db'){|db| puts db[:users].count} +* :timeout - the busy timeout to use in milliseconds (default: 5000). doc/opening_databases.rdoc @@ -5,6 +5,7 @@ <ul> <li><a href="rdoc/files/README_rdoc.html">README</a></li> <li><a href="rdoc/files/doc/cheat_sheet_rdoc.html">Cheat Sheet</a></li> + <li><a href="rdoc/files/doc/opening_databases_rdoc.html">Connecting to a Database</a></li> <li><a href="rdoc/files/doc/dataset_filtering_rdoc.html">Dataset Filtering</a></li> <li><a href="rdoc/files/doc/advanced_associations_rdoc.html">Advanced Associations</a></li> <li><a href="rdoc/files/doc/prepared_statements_rdoc.html">Prepared Statements/Bound Variables</a></li> www/pages/documentation bc85e6a8664bd3d14f149bf6acea2697ce217afd Jeremy Evans code@jeremyevans.net http://github.com/jeremyevans/sequel/commit/7acaa350b8ed2216a0849d9be55f888b1331217f 7acaa350b8ed2216a0849d9be55f888b1331217f 2009-06-15T10:23:48-07:00 2009-06-15T10:23:48-07:00 Augment the opening_databases.rdoc file with a lot more info, add website link 4a800c389bbed00dac9d574204cd93f3e63481fd Jeremy Evans code@jeremyevans.net