Path: | doc/opening_databases.rdoc |
Last Update: | Thu Mar 18 05:47:28 -0600 2010 |
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:
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.
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.
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')
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:
Sequel.connect('sqlite://blog.db'){|db| puts db[:users].count}
These options are shared by all adapters unless otherwise noted.
The following options can be specified and are passed to the the database‘s internal connection pool.
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.
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:
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.
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.
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.
Allows access to a multitude of databases via ruby-dbi. Additional options:
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.
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
Requires: fb (using code at github.com/wishdev/fb)
Does not support the :port option.
Does not support the :host or :port options.
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:
The following additional options are supported:
The MySQL adapter does not support the pure-ruby MySQL adapter that ships with ActiveRecord, it requires the native adapter.
The following additional options are supported:
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:
The :port option is ignored.
Requires: oci8
The following additional options are supported:
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:
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: