2 Connections

This section describes functions for creating connections as well as administrative functions for managing connections.

2.1 Base Connections

There are four kinds of base connection, and they are divided into two groups: wire-based connections and FFI-based connections. PostgreSQL and MySQL connections are wire-based, and SQLite and ODBC connections are FFI-based. See also FFI-Based Connections and Concurrency.

Base connections are made using the following functions.

By default, the connection is made via TCP to "localhost" at port 5432. To make a different TCP connection, provide one or both of the server and port arguments.

To connect via a local socket, specify the socket path as the socket argument. You must not supply the socket argument if you have also supplied either of the TCP arguments. See also Local Sockets for PostgreSQL and MySQL Servers for notes on socket paths. Supplying a socket argument of 'guess is the same as supplying (postgresql-guess-socket-path). Sockets are only available under Linux (x86) and Mac OS X.

If the server requests password authentication, the password argument must be present; otherwise an exception is raised. If the server does not request password authentication, the password argument is ignored and may be omitted. A connection normally only sends password hashes (using the md5 authentication method). If the server requests a password sent as cleartext (un-hashed), the connection is aborted unless allow-cleartext-password? is true.

If the ssl argument is either 'yes or 'optional, the connection attempts to negotiate an SSL connection. If the server refuses SSL, the connection raises an exception if ssl was set to 'yes or continues with an unencrypted connection if ssl was set to 'optional. Some servers use SSL certificates to authenticate clients; see ssl-load-certificate-chain! and ssl-load-private-key!. SSL may only be used with TCP connections, not with local sockets. See also Making Database Connections Securely.

The notice-handler is called on notice messages received asynchronously from the server. A common example is notice of an index created automatically for a table’s primary key. The notice-handler function takes two string arguments: the condition’s SQLSTATE and a message. The notification-handler is called in response to an event notification (see the LISTEN and NOTIFY statements); its arguments are the name of the channel, and the payload, as strings. If the handler only accepts a single argument, then it will be called without the payload. The ability to include a payload in a notification was added in PostgreSQL 9.0. An output port may be supplied instead of a procedure, in which case a message is printed to the given port. Finally, the symbol 'output causes the message to be printed to the current output port, and 'error causes the message to be printed to the current error port.

If the connection cannot be made, an exception is raised.

If none of the attempted paths exist, an exception is raised.

The meaning of the other keyword arguments is similar to those of the postgresql-connect function, except that the first argument to a notice-handler function is a MySQL-specific integer code rather than a SQLSTATE string, and a socket argument of 'guess is the same as supplying (mysql-guess-socket-path).

If the connection cannot be made, an exception is raised.

If none of the attempted paths exist, an exception is raised.

If mode is 'read-only, the database is opened in read-only mode. If mode is 'read/write (the default), the database is opened for reading and writing (if filesystem permissions permit). The 'create mode is like 'read/write, except that if the given file does not exist, it is created as a new database.

SQLite uses coarse-grained locking, and many internal operations fail with the SQLITE_BUSY condition when a lock cannot be acquired. When an internal operation fails because the database is busy, the connection sleeps for busy-retry-delay seconds and retries the operation, up to busy-retry-limit additional times. If busy-retry-limit is 0, the operation is only attempted once. If after busy-retry-limit retries the operation still does not succeed, an exception is raised.

If use-place is true, the actual connection is created in a distinct place for database connections and a proxy is returned; see FFI-Based Connections and Concurrency.

If the connection cannot be made, an exception is raised.

If strict-parameter-types? is true, then the connection attempts to determine and enforce specific types for query parameters. See ODBC Types for more details.

By default, connections use ODBC’s SQL_C_WCHAR-based character encoding (as UTF-16) to send and receive Unicode character data. Unfortunately, some drivers’ support for this method is buggy. To use SQL_C_CHAR instead, set character-mode to 'utf-8 or 'latin-1, depending on which encoding the driver uses.

See ODBC Status for notes on specific ODBC drivers and recommendations for connection options.

If use-place is true, the actual connection is created in a distinct place for database connections and a proxy is returned; see FFI-Based Connections and Concurrency.

If the connection cannot be made, an exception is raised.

If the connection cannot be made, an exception is raised.

2.2 Connection Pooling

Creating a database connection can be a costly operation; it may involve steps such as process creation and SSL negotiation. A connection pool helps reduce connection costs by reusing connections.

See also virtual-connection for a mechanism that eliminates the need to explicitly call connection-pool-lease and disconnect.

Calling disconnect on the connection obtained causes the connection to be released back to the connection pool. The connection is also released if release becomes available, if it is a synchronizable event, or if release is shutdown, if it is a custodian. The default for release is the current thread, so the resulting connection is released when the thread that requested it terminates.

When a connection is released, it is kept as an idle connection if pool’s idle connection limit would not be exceeded; otherwise, it is disconnected. In either case, if the connection is in a transaction, the transaction is rolled back.

2.3 Virtual Connections

A virtual connection creates actual connections on demand and automatically releases them when they are no longer needed.

A virtual connection encapsulates a mapping of threads to actual connections. When a query function is called with a virtual connection, the current thread’s associated actual connection is used to execute the query. If there is no actual connection associated with the current thread, one is obtained by calling connect. An actual connection is disconnected when its associated thread dies.

Virtual connections are especially useful in contexts such as web servlets (see Databases and Web Servlets), where each request is handled in a fresh thread. A single global virtual connection can be defined, freeing each servlet request from explicitly opening and closing its own connections. In particular, a virtual connection backed by a connection pool combines convenience with efficiency:

(define the-connection

(virtual-connection (connection-pool (lambda () ....))))

The resulting virtual connection leases a connection from the pool on demand for each servlet request thread and releases it when the thread terminates (that is, when the request has been handled).

When given a connection produced by virtual-connection, connected? indicates whether there is an actual connection associated with the current thread. Likewise, disconnect causes the current actual connection associated with the thread (if there is one) to be disconnected, but the connection will be recreated if a query function is executed.

Connections produced by virtual-connection may not be used with the prepare function. However, they may still be used to execute parameterized queries expressed as strings or encapsulated via virtual-statement.

2.4 Kill-safe Connections

Note: A kill-safe connection whose underlying connection uses ports to communicate with a database server is not protected from a custodian shutting down its ports.

2.5 Data Source Names

A DSN (data source name) is a symbol associated with a connection specification in a DSN file. They are inspired by, but distinct from, ODBC’s DSNs.

Data sources can also be created using the postgresql-data-source, etc auxiliary functions.

If dsn-file does not exist, or if it contains no entry for dsn, an exception is raised. If dsn is a data-source, then dsn-file is ignored.

If dsn-file does not exist, an exception is raised. If dsn-file does not have an entry for dsn, default is called if it is a function or returned otherwise.

2.6 Managing Connections

2.7 System-specific Modules

The db module exports all of the functions listed in this manual except those described in Utilities. The database system-specific connection modules are loaded lazily to avoid unnecessary dependencies on foreign libraries.

The following modules provide subsets of the bindings described in this manual.

Provides all generic connection operations (those described in Managing Connections and Queries) and SQL data support (SQL Types and Conversions).

Provides only postgresql-connect and postgresql-guess-socket-path.

Provides only mysql-connect and mysql-guess-socket-path.

Provides sqlite3-connect plus sqlite3-available?. When the SQLite native library cannot be found, sqlite3-connect raises an exception.

Provides only odbc-connect, odbc-driver-connect, odbc-data-sources, and odbc-drivers. In contrast to db, this module immediately attempts to load the ODBC native library when required, and it raises an exception if it cannot be found.