14.2.5 Database connection and disconnection

Once the database type has been initialized a connection can be established by calling connect . A call to connect sets *default-database* to the database instance which represents the connection. All the other database functions described take a :database argument that can be either a database or a database name, and which defaults to *default-database* .

*default-database*

Variable

Specifies the default database to be used for database operations.

connected-databases

Function

Returns a list of database connection instances.

connect

Function

Opens a connection to a database of database-type . The argument connection-spec depends on the type of the connected database. For databases of type :odbc , the connection specification is a string of the format

where datasource-name is the name of a suitable datasource, and username and password are a valid username and password. If the datasource does not require a username and password they can be omitted.

The connect function sets *default-database* to an instance of the database opened and returns that instance. The argument if-exists modifies the behavior of connect as follows:

:new

Makes a new connection even if connections to the same database already exist.

:warn-new

Makes a new connection but warns about existing connections.

:error

Makes a new connection but signals an error for existing connections.

:warn-old

Selects the old connection if one exists (and warns) or makes a new one.

:old

Selects the old connection if one exists or makes a new one.

*connect-if-exists*

Variable

Default value for the :if-exists variable of the connect function. See the connect description for the possible values. Initial value is :error .

disconnect

Function

Closes the connection to database . Resets *default-database* if that database was disconnected and only one other connection exists.

database-name

Function

Returns the database connection string.

find-database

Function

Returns a database given its name or itself. If database is not found among the connected databases and errorp is non- nil then find-database signals an error, otherwise it returns nil . By default, errorp is t .

status

Function

Returns status information for the connected databases and initialized database types. By default, full is nil . If t , more detailed information is returned.

14.2.5.1 Connection example