2 Connections

▼ |  | DB: Database Connectivity

1 | Using Database Connections
2 | Connections
3 | Queries
4 | SQL Types and Conversions
5 | Utilities
6 | Notes

► | 2 | Connections

2.1 | Base Connections
2.2 | Connection Pooling
2.3 | Virtual Connections
2.4 | Kill-safe Connections
2.5 | Data Source Names
2.6 | Managing Connections
2.7 | System-specific Modules

On this page:

2.1 Base Connections
postgresql-connect
postgresql-guess-socket-path
mysql-connect
mysql-guess-socket-path
cassandra-connect
sqlite3-connect
sqlite3-available?
odbc-connect
odbc-driver-connect
odbc-data-sources
odbc-drivers
2.2 Connection Pooling
connection-pool
connection-pool?
connection-pool-lease
2.3 Virtual Connections
virtual-connection
2.4 Kill-safe Connections
kill-safe-connection
2.5 Data Source Names
data-source
dsn-connect
current-dsn-file
get-dsn
put-dsn
postgresql-data-source
mysql-data-source
cassandra-data-source
sqlite3-data-source
odbc-data-source
odbc-driver-data-source
2.6 Managing Connections
connection?
disconnect
connected?
connection-dbsystem
dbsystem?
dbsystem-name
dbsystem-supported-types
2.7 System-specific Modules

Racket
top contents ← prev up next →

## 2 Connections🔗ℹ

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

### 2.1 Base Connections🔗ℹ

There are five kinds of base connection, and they are divided into two groups: wire-based connections and FFI-based connections. PostgreSQL, MySQL, and Cassandra 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.

> > procedure
> > (postgresql-connect |
> > |  | #:user user |
> > |  | #:database database |
> > | [ | #:server server |
> > |  | #:port port |
> > |  | #:socket socket |
> > |  | #:password password |
> > |  | #:allow-cleartext-password? allow-cleartext-password? |
> > |  | #:ssl ssl |
> > |  | #:ssl-context ssl-context |
> > |  | #:notice-handler notice-handler |
> > |  | #:notification-handler notification-handler]) |
> → connection?
> user : string?
> database : string?
> server : string? = "localhost"
> port : exact-positive-integer? = 5432
> socket : (or/c path-string? 'guess #f) = #f
> password : (or/c string? #f) = #f
> allow-cleartext-password? : (or/c boolean? 'local) = 'local
> ssl : (or/c 'yes 'optional 'no) = 'no
> ssl-context : ssl-client-context? = (ssl-make-client-context)
> | notice-handler |  | : |  |
> (or/c 'output 'error output-port?
> (-> string? string? any))
> |  | = |  | void
> | notification-handler |  | : |  |
> (or/c 'output 'error output-port?
> (-> string? any)
> (-> string? string? any))
> |  |  | = |  | void

Creates a connection to a PostgreSQL server. Only the database and user arguments are mandatory.

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).

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 or scram-sha-256 authentication methods). If the server requests a password sent as cleartext (un-hashed), the connection is aborted unless allow-cleartext-password? is #t, or unless allow-cleartext-password? is 'local and the connection is to "localhost" or a local socket.

If the server requests an OAuth 2.0 bearer token, the token is passed using the password argument. The token is only sent if the connection uses SSL or if the connection is to "localhost" or a local socket. If password is #f or if authentication fails, an exn:fail:sql exception is raised with an 'auth/oauthbearer info field with a string containing failure information (RFC 7628).

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.

Examples:

> > (postgresql-connect #:server "db.mysite.com"
> #:port 5432
> #:database "webappdb"
> #:user "webapp"
> #:password "ultra5ecret")
> (object:connection% ...)
> > (postgresql-connect #:user "me"
> #:database "me"
> #:password "icecream")
> (object:connection% ...)
> > (postgresql-connect ; Typical socket path
> #:socket "/var/run/postgresql/.s.PGSQL.5432"
> #:user "me"
> #:database "me")
> (object:connection% ...)
> > (postgresql-connect #:socket 'guess ; or (postgresql-guess-socket-path)
> #:user "me"
> #:database "me")
> (object:connection% ...)

Changed in version 1.2 of package db-lib: Added support for SCRAM-SHA-256 authentication.
Changed in version 1.7: Added support for SCRAM-SHA-256-PLUS authentication.
Changed in version 1.12: Added support for OAUTHBEARER authentication.

> procedure (postgresql-guess-socket-path) → path-string?

Attempts to guess the path for the socket based on conventional locations. This function returns the first such path that exists in the filesystem. It does not check that the path is a socket file, nor that the path is connected to a PostgreSQL server.

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

> > procedure
> > (mysql-connect |
> > |  | #:user user |
> > | [ | #:database database |
> > |  | #:server server |
> > |  | #:port port |
> > |  | #:socket socket |
> > |  | #:allow-cleartext-password? allow-cleartext-password? |
> > |  | #:ssl ssl |
> > |  | #:ssl-context ssl-context |
> > |  | #:password password |
> > |  | #:notice-handler notice-handler]) |
> → connection?
> user : string?
> database : (or/c string? #f) = #f
> server : string? = "localhost"
> port : exact-positive-integer? = 3306
> socket : (or/c path-string? 'guess #f) = #f
> allow-cleartext-password? : (or/c boolean? 'local) = 'local
> ssl : (or/c 'yes 'optional 'no) = 'no
> ssl-context : ssl-client-context? = (ssl-make-client-context)
> password : (or/c string? #f) = #f
> | notice-handler |  | : |  |
> (or/c 'output 'error output-port?
> (-> exact-nonnegative-integer? string? any))
> |  |  | = |  | void

Creates a connection to a MySQL server. If database is #f, the connection is established without setting the current database; it should be subsequently set with the USE SQL command.

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.

Examples:

> > (mysql-connect #:server "db.mysite.com"
> #:port 3306
> #:database "webappdb"
> #:user "webapp"
> #:password "ultra5ecret")
> (object:connection% ...)
> > (mysql-connect #:user "me"
> #:database "me"
> #:password "icecream")
> (object:connection% ...)
> > (mysql-connect ; Typical socket path
> #:socket "/var/run/mysqld/mysqld.sock"
> #:user "me"
> #:database "me")
> (object:connection% ...)
> > (mysql-connect #:socket (mysql-guess-socket-path)
> #:user "me"
> #:database "me")
> (object:connection% ...)

Changed in version 1.6 of package db-lib: Added support for caching_sha2_password authentication and added the #:allow-cleartext-password? argument; see MySQL Authentication.

> procedure (mysql-guess-socket-path) → path-string?

Attempts to guess the path for the socket based on conventional locations. This function returns the first such path that exists in the filesystem. It does not check that the path is a socket file, nor that the path is connected to a MySQL server.

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

> > procedure
> > (cassandra-connect | [ | #:user user |  |  |  |
> > |  | #:password password |  |  |  |
> > |  | #:server server |  |  |  |
> > |  | #:port port |  |  |  |
> > |  | #:ssl ssl |  |  |  |
> > |  | #:ssl-context ssl-context]) |  | → |  | connection?
> user : (or string? #f) = #f
> password : (or string? #f) = #f
> server : string? = "localhost"
> port : exact-positive-integer? = 9042
> ssl : (or/c 'yes 'no) = 'no
> ssl-context : (or/c ssl-client-context? 'auto 'secure) = 'auto

Creates a connection to a Cassandra server.

The meaning of the keyword arguments is similar to those of the postgresql-connect function.

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

Examples:

> > (cassandra-connect)
> (object:connection% ...)
> > (cassandra-connect #:user "me"
> #:password "icecream")
> (object:connection% ...)
> > (cassandra-connect #:server "db.mysite.com"
> #:port 9042
> #:user "webapp"
> #:password "ultra5ecret")
> (object:connection% ...)

> > procedure
> > (sqlite3-connect |  | #:database database |
> > | [ | #:mode mode |
> > |  | #:busy-retry-limit busy-retry-limit |
> > |  | #:busy-retry-delay busy-retry-delay |
> > |  | #:use-place use-place]) |
> → connection?
> database : (or/c path-string? 'memory 'temporary)
> mode : (or/c 'read-only 'read/write 'create) = 'read/write
> | busy-retry-limit |  | : |  | (or/c exact-nonnegative-integer? +inf.0)
> |  |  | = |  | 10
> busy-retry-delay : (and/c rational? (not/c negative?)) = 0.1
> use-place : (or/c boolean? 'os-thread 'place) = #f

Opens the SQLite database at the file named by database, if database is a string or path. If database is 'temporary, a private disk-based database is created. If database is 'memory, a private memory-based database is created.

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 'os-thread, then queries are executed in a separate OS thread. If use-place is 'place, the actual connection is created in a distinct place for database connections and a proxy is returned. If use-place is #t, then it acts like 'os-thread if available, otherwise like 'place. See FFI-Based Connections and Concurrency for more information.

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

Examples:

> > (sqlite3-connect #:database "/path/to/my.db")
> (object:connection% ...)
> > (sqlite3-connect #:database "relpath/to/my.db"
> #:mode 'create)
> (object:connection% ...)

> procedure (sqlite3-available?) → boolean?

Reports whether the SQLite native library is found, in which case sqlite3-connect works, otherwise it raises an exception.

> > procedure
> > (odbc-connect |
> > |  | #:dsn dsn |
> > | [ | #:user user |
> > |  | #:password password |
> > |  | #:notice-handler notice-handler |
> > |  | #:strict-parameter-types? strict-parameter-types? |
> > |  | #:character-mode character-mode |
> > |  | #:quirks quirks |
> > |  | #:use-place use-place]) |
> → connection?
> dsn : string?
> user : (or/c string? #f) = #f
> password : (or/c string? #f) = #f
> | notice-handler |  | : |  |
> (or/c output-port? 'output 'error
> (-> string? string? any))
> |  | = |  | void
> strict-parameter-types? : boolean? = #f
> character-mode : (or/c 'wchar 'utf-8 'latin-1) = 'wchar
> quirks : (listof symbol?) = null
> use-place : (or/c boolean? 'place 'os-thread) = #f

Creates a connection to the ODBC Data Source named dsn. The user and password arguments are optional, since that information may be incorporated into the data source definition, or it might not be relevant to the data source’s driver. The notice-handler argument behaves the same as in postgresql-connect.

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.

The character-mode argument controls the handling of character data; the following values are supported:

- 'wchar (the default) – use SQL_C_WCHAR and treat the data as UTF-16 (or UTF-32/UCS-4 when the driver manager is iODBC)

- 'utf-8 – use SQL_C_CHAR and treat the data as UTF-8

- 'latin-1 – use SQL_C_CHAR and treat the data as Latin-1. Characters not in Latin-1 are replaced with #\?.

The quirks argument represents a list of flags to modify the behavior of the connection. The following quirks are currently supported:

- 'no-c-bigint — Don’t use SQL_C_BIGINT to bind parameters or fetch field values.

- 'no-c-numeric — Don’t use SQL_C_NUMERIC to fetch NUMERIC/DECIMAL values.

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

The use-place argument is interpreted the same as for sqlite3-connect.

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

Changed in version 1.3 of package db-lib: Added #:quirks argument.

> > procedure
> > (odbc-driver-connect |
> > |  | connection-string |
> > | [ | #:notice-handler notice-handler |
> > |  | #:strict-parameter-types? strict-parameter-types? |
> > |  | #:character-mode character-mode |
> > |  | #:quirks quirks |
> > |  | #:use-place use-place]) |
> → connection?
> connection-string : string?
> | notice-handler |  | : |  |
> (or/c output-port? 'output 'error
> (-> string? string? any))
> |  | = |  | void
> strict-parameter-types? : boolean? = #f
> character-mode : (or/c 'wchar 'utf-8 'latin-1) = 'wchar
> quirks : (listof symbol?) = null
> use-place : (or/c boolean? 'os-thread 'place) = #f

Creates a connection using an ODBC connection string containing a sequence of keyword and value connection parameters. The syntax of connection strings is described in SQLDriverConnect (see Comments section); supported attributes depend on the driver. The other arguments are the same as in odbc-connect.

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

Changed in version 1.3 of package db-lib: Added #:quirks argument.

> procedure (odbc-data-sources) → (listof (list/c string? string?))

Returns a list of known ODBC Data Sources. Each data source is represented by a list of two strings; the first string is the name of the data source, and the second is the name of its associated driver.

> procedure (odbc-drivers) → (listof (cons/c string? any/c))

Returns a list of known ODBC Drivers. Each driver is represented by a list, the first element of which is the name of the driver. The contents of the rest of each entry is currently undefined.

### 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.

> > procedure
> > (connection-pool |  | connect |
> > | [ | #:max-connections max-connections |
> > |  | #:max-idle-connections max-idle-connections |
> > |  | #:max-idle-seconds max-idle-seconds]) |
> → connection-pool?
> connect : (-> connection?)
> max-connections : (or/c (integer-in 1 10000) +inf.0) = +inf.0
> max-idle-connections : (or/c (integer-in 1 10000) +inf.0) = 10
> max-idle-seconds : (>=/c 0) = 300

Creates a connection pool. The pool contains up to max-connections actual database connections, divided between the currently leased connections and up to max-idle-connections idle connections. If a connection is idle for more than max-idle-seconds seconds, then it is disconnected and removed from the connection pool.

The pool uses connect to create new actual connections when needed. The connect function must return a fresh connection each time it is called. When the pool calls connect, the value of (current-custodian) is the same as when the connection pool was created.

Examples:

> > (define pool
> (connection-pool
> (lambda () (displayln "connecting!") (sqlite3-connect ....))
> #:max-idle-connections 1))
> > (define c1 (connection-pool-lease pool))
> connecting!
> > (define c2 (connection-pool-lease pool))
> connecting!
> > (disconnect c1)
> > (define c3 (connection-pool-lease pool)) ; reuses actual conn. from c1

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

Changed in version 1.13 of package db-lib: Added #:max-idle-seconds argument.

> procedure (connection-pool? x) → boolean?
> x : any/c

Returns #t if x is a connection pool, #f otherwise.

> > procedure
> > (connection-pool-lease |  | pool |  |  |  |
> > | [ | release |  |  |  |
> > |  | #:timeout timeout-seconds |  |  |  |
> > |  | #:fail fail]) |  | → |  | connection?
> pool : connection-pool?
> release : (or/c evt? custodian?) = (current-thread)
> timeout-seconds : (or/c #f (>=/c 0)) = #f
> fail : any/c = (lambda () (error ....))

Obtains a connection from the connection pool, using an existing idle connection in pool if one is available. If timeout-seconds is #f, then if the pool cannot immediately supply a connection, the lease request fails. If timeout-seconds is a number, then if the pool does not satisfy the request within timeout-seconds, then the lease request fails. In either case, if the lease request fails, fail is called if it is a procedure or returned otherwise.

Calling disconnect on the leased connection causes the connection to be released back to the connection pool. The connection may also be released automatically: if release is a synchronizable event, the connection is released when the event becomes ready; if release is a custodian, the connection is released when the custodian is shut down. The default for release is the current thread, so the 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.

Changed in version 1.13 of package db-lib: Added #:timeout and #:fail.

### 2.3 Virtual Connections🔗ℹ

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

> procedure (virtual-connection connect) → connection?
> connect : (or/c (-> connection?) connection-pool?)

Creates a virtual connection that creates actual connections on demand using the connect function, or by calling (connection-pool-lease connect) if connect is a connection pool. If connect is a function, it is called with the same current-custodian value as when the virtual connection was created.

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.

Examples:

> > (define c
> (virtual-connection
> (lambda ()
> (printf "connecting!\n")
> (postgresql-connect ....))))
> > (connected? c)
> #f
> > (query-value c "select 1")
> connecting!
> 1
> > (connected? c)
> #t
> > (void (thread (lambda () (displayln (query-value c "select 2")))))
> connecting!
> 2
> > (disconnect c)
> > (connected? c)
> #f
> > (query-value c "select 3")
> connecting!
> 3

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.

Examples:

> > (prepare c "select 2 + $1")
> prepare: cannot prepare statement with virtual connection
> > (query-value c "select 2 + $1" 2)
> 4
> > (define pst (virtual-statement "select 2 + $1"))
> > (query-value c pst 3)
> 5

### 2.4 Kill-safe Connections🔗ℹ

> procedure (kill-safe-connection c) → connection?
> c : connection?

Creates a proxy for connection c. All queries performed through the proxy are kill-safe; that is, if a thread is killed during a call to a query function such as query, the connection will not become locked or damaged. (Connections are normally thread-safe but not kill-safe.)

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.

> > struct
> > (struct |  | data-source (connector args extensions)
> #:mutable)
> connector : (or/c 'postgresql 'mysql 'sqlite3 'odbc 'odbc-driver)
> args : list?
> extensions : (listof (list/c symbol? any/c))

Represents a data source. The connector field determines which connection function is used to create the connection. The args field is a partial list of arguments passed to the connection function; additional arguments may be added when dsn-connect is called. The extensions field contains additional information about a connection; for example, this library’s testing framework uses it to store SQL dialect flags.

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

> > procedure
> > (dsn-connect |  | dsn |  |  |  |
> > | [ | #:dsn-file dsn-file] |  |  |  |
> > |  | arg ... |  |  |  |
> > |  | #:<kw> kw-arg ...) |  | → |  | connection?
> dsn : (or/c symbol? data-source?)
> dsn-file : path-string? = (current-dsn-file)
> arg : any/c
> kw-arg : any/c

Makes a connection using the connection information associated with dsn in dsn-file. The given args and kw-args are added to those specified by dsn to form the complete arguments supplied to the connect function.

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.

Examples:

> > (put-dsn 'pg
> (postgresql-data-source #:user "me"
> #:database "mydb"
> #:password "icecream"))
> > (dsn-connect 'pg)
> (object:connection% ...)
> > (dsn-connect 'pg #:notice-handler (lambda (code msg) ....))
> (object:connection% ...)

> parameter (current-dsn-file) → path-string?
> (current-dsn-file x) → void?
> x : path-string?

A parameter holding the location of the default DSN file. The initial value is a file located immediately within (find-system-path 'prefs-dir).

> procedure (get-dsn dsn [default #:dsn-file dsn-file])
> → (or/c data-source? any/c)
> dsn : symbol?
> default : any/c = #f
> dsn-file : path-string? = (current-dsn-file)

Returns the data-source associated with dsn in dsn-file.

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.

> procedure (put-dsn dsn ds [#:dsn-file dsn-file]) → void?
> dsn : symbol?
> ds : (or/c data-source? #f)
> dsn-file : path-string? = (current-dsn-file)

Associates dsn with the given data source ds in dsn-file, replacing the previous association, if one exists.

> > procedure
> > (postgresql-data-source |
> > | [ | #:user user |
> > |  | #:database database |
> > |  | #:server server |
> > |  | #:port port |
> > |  | #:socket socket |
> > |  | #:password password |
> > |  | #:allow-cleartext-password? allow-cleartext-password? |
> > |  | #:ssl ssl |
> > |  | #:notice-handler notice-handler |
> > |  | #:notification-handler notification-handler]) |
> → data-source?
> user : string? = absent
> database : string? = absent
> server : string? = absent
> port : exact-positive-integer? = absent
> socket : (or/c path-string? 'guess #f) = absent
> password : (or/c string? #f) = absent
> allow-cleartext-password? : boolean? = absent
> ssl : (or/c 'yes 'optional 'no) = absent
> notice-handler : (or/c 'output 'error) = absent
> notification-handler : (or/c 'output 'error) = absent
> > procedure
> > (mysql-data-source | [ | #:user user |
> > |  | #:database database |
> > |  | #:server server |
> > |  | #:port port |
> > |  | #:socket socket |
> > |  | #:ssl ssl |
> > |  | #:password password |
> > |  | #:notice-handler notice-handler]) |
> → data-source?
> user : string? = absent
> database : (or/c string? #f) = absent
> server : string? = absent
> port : exact-positive-integer? = absent
> socket : (or/c path-string? 'guess #f) = absent
> ssl : (or/c 'yes 'optional 'no) = absent
> password : (or/c string? #f) = absent
> notice-handler : (or/c 'output 'error) = absent
> > procedure
> > (cassandra-data-source | [ | #:server server |
> > |  | #:port port |
> > |  | #:user user |
> > |  | #:password password |
> > |  | #:ssl ssl |
> > |  | #:ssl-context ssl-context]) |
> → data-source?
> server : string? = absent
> port : exact-positive-integer? = absent
> user : string? = absent
> password : (or/c string? #f) = absent
> ssl : (or/c 'yes 'no) = absent
> ssl-context : (or/c 'auto 'secure) = absent
> > procedure
> > (sqlite3-data-source | [ | #:database database |
> > |  | #:mode mode |
> > |  | #:busy-retry-limit busy-retry-limit |
> > |  | #:busy-retry-delay busy-retry-delay |
> > |  | #:use-place use-place]) |
> → data-source?
> database : (or/c path-string? 'memory 'temporary) = absent
> mode : (or/c 'read-only 'read/write 'create) = absent
> | busy-retry-limit |  | : |  | (or/c exact-nonnegative-integer? +inf.0)
> |  |  | = |  | absent
> | busy-retry-delay |  | : |  | (and/c rational? (not/c negative?))
> |  |  | = |  | absent
> use-place : boolean? = absent
> > procedure
> > (odbc-data-source |
> > | [ | #:dsn dsn |
> > |  | #:user user |
> > |  | #:password password |
> > |  | #:notice-handler notice-handler |
> > |  | #:strict-parameter-types? strict-parameter-types? |
> > |  | #:character-mode character-mode |
> > |  | #:quirks quirks |
> > |  | #:use-place use-place]) |
> → data-source?
> dsn : (or/c string? #f) = absent
> user : (or/c string? #f) = absent
> password : (or/c string? #f) = absent
> notice-handler : (or/c 'output 'error) = absent
> strict-parameter-types? : boolean? = absent
> character-mode : (or/c 'wchar 'utf-8 'latin-1) = absent
> quirks : (listof symbol?) = null
> use-place : boolean? = absent
> > procedure
> > (odbc-driver-data-source |
> > |  | connection-string |
> > | [ | #:notice-handler notice-handler |
> > |  | #:strict-parameter-types? strict-parameter-types? |
> > |  | #:character-mode character-mode |
> > |  | #:quirks quirks |
> > |  | #:use-place use-place]) |
> → data-source?
> connection-string : string?
> notice-handler : (or/c 'output 'error) = absent
> strict-parameter-types? : boolean? = absent
> character-mode : (or/c 'wchar 'utf-8 'latin-1) = absent
> quirks : (listof symbol?) = null
> use-place : boolean? = absent

Analogues of postgresql-connect, mysql-connect, sqlite3-connect, odbc-connect, and odbc-driver-connect, respectively, that return a data-source describing the (partial) connection information. All arguments are optional, even those that are mandatory in the corresponding connection function; the missing arguments must be supplied when dsn-connect is called.

Changed in version 1.7 of package db-lib: Added odbc-driver-data-source.

### 2.6 Managing Connections🔗ℹ

> procedure (connection? x) → boolean?
> x : any/c

Returns #t if x is a connection, #f otherwise.

> procedure (disconnect connection) → void?
> connection : connection?

Closes the connection.

> procedure (connected? connection) → boolean?
> connection : connection?

Returns #t if connection is connected, #f otherwise.

> procedure (connection-dbsystem connection) → dbsystem?
> connection : connection?

Gets an object encapsulating information about the database system of connection.

> procedure (dbsystem? x) → boolean?
> x : any/c

Predicate for objects representing database systems.

> procedure (dbsystem-name sys) → symbol?
> sys : dbsystem?

Returns a symbol that identifies the database system. Currently one of the following:

- 'postgresql

- 'mysql

- 'sqlite3

- 'odbc

> procedure (dbsystem-supported-types sys) → (listof symbol?)
> sys : dbsystem?

Returns a list of symbols identifying types supported by the database system. See SQL Type Conversions.

### 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.

(require db/base) | package: db-lib

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

(require db/postgresql) | package: db-lib

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

(require db/mysql) | package: db-lib

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

(require db/cassandra) | package: db-lib

Provides only cassandra-connect and cassandra-consistency.

(require db/sqlite3) | package: db-lib

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

(require db/odbc) | package: db-lib

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.

top contents ← prev up next →