# Connection and Initialisation

This section describes the &clsql; interface for initialising database interfaces of different types, creating and destroying databases and connecting and disconnecting from databases.

DATABASE

DATABASE

The super-type of all &clsql; databases

Class

### Class Precedence List

- `database`
- `standard-object`
- `t`

### Description

This class is the superclass of all &clsql; databases. The different database back-ends derive subclasses of this class to implement their databases. No instances of this class are ever created by &clsql;.

*CONNECT-IF-EXISTS*

*CONNECT-IF-EXISTS*

Default value for the `if-exists` parameter of `connect`.

Variable

### Value Type

A valid argument to the `if-exists` parameter of `connect`, that is, one of

- :new
- :warn-new
- :error
- :warn-old
- :old

.

### Initial Value

:error

### Description

The value of this variable is used in calls to `connect` as the default value of the `if-exists` parameter. See `connect` for the semantics of the valid values for this variable.

### Examples

None.

### Affected By

None.

### See Also

- `connect`

### Notes

None.

*DB-POOL-MAX-FREE-CONNECTIONS*

*DB-POOL-MAX-FREE-CONNECTIONS*

How many free connections should the connection pool try to keep.

Parameter

### Value Type

Integer

### Initial Value

4

### Description

Threshold of free-connections in the pool before we disconnect a database rather than returning it to the pool. NIL for no limit. This is really a heuristic that should, on avg keep the free connections about this size.

This is not a hard limit, the number of connections in the pool may exceed this value.

### Examples

    	(setf clsql-sys:*db-pool-max-free-connections* 2)

### Affected By

None

### See Also

- `connect`
- `disconnect`

### Notes

*DEFAULT-DATABASE*

*DEFAULT-DATABASE*

The default database object to use.

Variable

### Value Type

Any object of type `database`, or &nil; to indicate no default database.

### Initial Value

&nil;

### Description

Any function or macro in &clsql; that operates on a database uses the value of this variable as the default value for it's `database` parameter.

The value of this parameter is changed by calls to `connect`, which sets *default-database* to the database object it returns. It is also changed by calls to `disconnect`, when the database object being disconnected is the same as the value of *default-database*. In this case `disconnect` sets *default-database* to the first database that remains in the list of active databases as returned by `connected-databases`, or &nil; if no further active databases exist.

The user may change *default-database* at any time to a valid value of his choice.

If the value of *default-database* is &nil;, then all calls to &clsql; functions on databases must provide a suitable `database` parameter, or an error will be signalled.

### Examples

            (connected-databases)
            => NIL
            (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
            => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
            (connect '(nil "template1" "dent" nil) :database-type :postgresql)
            => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
            (connect '("dent" "newesim" "dent" "dent") :database-type :mysql :if-exists :new)
            => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
            *default-database*
            => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
            (disconnect)
            => T
            *default-database*
            => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
            (disconnect)
            => T
            *default-database*
            => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
            (disconnect)
            => T
            *default-database*
            => NIL
            (connected-databases)
            => NIL

### Affected By

- `connect`
- `disconnect`

### See Also

- `connected-databases`

### Notes

This variable is intended to facilitate working with &clsql; in an interactive fashion at the top-level loop, and because of this, `connect` and `disconnect` provide some fairly complex behaviour to keep *default-database* set to useful values. Programmatic use of &clsql; should never depend on the value of *default-database* and should provide correct database objects via the `database` parameter to functions called.

*DEFAULT-DATABASE-TYPE*

*DEFAULT-DATABASE-TYPE*

The default database type to use

Variable

### Value Type

Any keyword representing a valid database back-end of &clsql;, or &nil;.

### Initial Value

&nil;

### Description

The value of this variable is used in calls to `initialize-database-type` and `connect` as the default value of the `database-type` parameter.

If the value of this variable is &nil;, then all calls to `initialize-database-type` or `connect` will have to specify the `database-type` to use, or a general-purpose error will be signalled.

### Examples

            (setf *default-database-type* :mysql)
            => :mysql
            (initialize-database-type)
            => t

### Affected By

None.

### See Also

- `intitialize-database-type`

### Notes

None.

*INITIALIZED-DATABASE-TYPES*

*INITIALIZED-DATABASE-TYPES*

List of all initialized database types

Variable

### Value Type

A list of all initialized database types, each of which represented by it's corresponding keyword.

### Initial Value

&nil;

### Description

This variable is updated whenever `initialize-database-type` is called for a database type which hasn't already been initialized before, as determined by this variable. In that case the keyword representing the database type is pushed onto the list stored in *INITIALIZED-DATABASE-TYPES*.

Attempts to modify the value of this variable will result in undefined behaviour.

### Examples

            (setf *default-database-type* :mysql)
            => :mysql
            (initialize-database-type)
            => t
            *initialized-database-types*
            => (:MYSQL)

### Affected By

- `initialize-database-type`

### See Also

- `intitialize-database-type`

### Notes

Direct access to this variable is primarily provided because of compatibility with Harlequin's Common SQL.

CONNECT

CONNECT

create a connection to a database.

Function

### Syntax

    connect connection-spec &key if-exists database-type pool make-default => database

### Arguments and Values

`connection-spec`

- A SQL backend specific connection specification supplied as a list or as a string.

  For the MySQL backend, this list includes an optional associative list of connection options. The options list is parsed and supplied to the MySQL API using `mysql_options` in between the calls to `mysql_init` and `mysql_real_connect`.

`if-exists`

- This indicates the action to take if a connection to the same database exists already. See below for the legal values and actions. It defaults to the value of *connect-if-exists*.

`database-type`

- A database type specifier, i.e. a keyword. This defaults to the value of *default-database-type*

`pool`

- A boolean flag. If &t;, acquire connection from a pool of open connections. If the pool is empty, a new connection is created. The default is &nil;.

`make-default`

- A boolean flag. If &t;, *default-database* is set to the new connection, otherwise *default-database* is not changed. The default is &t;.

database

- The database object representing the connection.

### Description

This function takes a connection specification and a database type and creates a connection to the database specified by those. The type and structure of the connection specification depend on the database type.

The parameter `if-exists` specifies what to do if a connection to the database specified exists already, which is checked by calling `find-database` on the database name returned by `database-name-from-spec` when called with the `connection-spec` and `database-type` parameters. The possible values of `if-exists` are:

:new

- Go ahead and create a new connection.

:warn-new

- This is just like :new, but also signals a warning of type clsql-exists-warning, indicating the old and newly created databases.

:error

- This will cause `connect` to signal a correctable error of type clsql-exists-error. The user may choose to proceed, either by indicating that a new connection shall be created, via the restart create-new, or by indicating that the existing connection shall be used, via the restart use-old.

:old

- This will cause `connect` to use an old connection if one exists.

:warn-old

- This is just like :old, but also signals a warning of type clsql-exists-warning, indicating the old database used, via the slots old-db and new-db

The database name of the returned database object will be the same under `string=` as that which would be returned by a call to `database-name-from-spec` with the given `connection-spec` and `database-type` parameters.

### Examples

    (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
    => "dent/newesim/dent"
    (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
    => #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
    (database-name *)
    => "dent/newesim/dent"

    (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
    >> In call to CONNECT:
    >>   There is an existing connection #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
    >>
    >> Restarts:
    >>   0: [CREATE-NEW] Create a new connection.
    >>   1: [USE-OLD   ] Use the existing connection.
    >>   2: [ABORT     ] Return to Top-Level.
    >>
    >> Debug  (type H for help)
    >>
    >> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
    >> Source:
    >> ; File: /prj/CLSQL/sql/sql.cl
    >> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
    >>               (CREATE-NEW NIL :REPORT "Create a new connection."
    >>                (SETQ RESULT #))
    >>               (USE-OLD NIL :REPORT "Use the existing connection."
    >>                (SETQ RESULT OLD-DB)))
    >> 0] 0
    => #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>

### Side Effects

A database connection is established, and the resultant database object is registered, so as to appear in the list returned by `connected-databases`. *default-database* may be rebound to the created object.

### Affected by

- *default-database-type*
- *connect-if-exists*

### Exceptional Situations

If the connection specification is not syntactically or semantically correct for the given database type, an error of type sql-user-error is signalled. If during the connection attempt an error is detected (e.g. because of permission problems, network trouble or any other cause), an error of type sql-database-error is signalled.

If a connection to the database specified by `connection-spec` exists already, conditions are signalled according to the `if-exists` parameter, as described above.

### See Also

- `connected-databases`
- `disconnect`
- `reconnect`
- `*connect-if-exists*`
- `find-database`
- `status`

### Notes

The `pool` and `make-default` keyword arguments to `connect` are &clsql; extensions.

CONNECTED-DATABASES

CONNECTED-DATABASES

Return the list of active database objects.

Function

### Syntax

          connected-databases => databases

### Arguments and Values

databases

- The list of active database objects.

### Description

This function returns the list of active database objects, i.e. all those database objects created by calls to `connect`, which have not been closed by calling `disconnect` on them.

The consequences of modifying the list returned by `connected-databases` are undefined.

### Examples

    (connected-databases)
    => NIL
    (connect '(nil "template1" "dent" nil) :database-type :postgresql)
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>
    (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
    => #<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
    (connected-databases)
    => (#<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
        #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
    (disconnect)
    => T
    (connected-databases)
    => (#<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
    (disconnect)
    => T
    (connected-databases)
    => NIL

### Side Effects

None.

### Affected By

- `connect`
- `disconnect`

### Exceptional Situations

None.

### See Also

- `disconnect`
- `connect`
- `status`
- `find-database`

### Notes

None.

DATABASE-NAME

DATABASE-NAME

Get the name of a database object

Generic Function

### Syntax

    database-name database => name

### Arguments and Values

`database`

- A database object, either of type `database` or of type `closed-database`.

name

- A string describing the identity of the database to which this database object is connected to.

### Description

This function returns the database name of the given database. The database name is a string which somehow describes the identity of the database to which this database object is or has been connected. The database name of a database object is determined at `connect` time, when a call to `database-name-from-spec` derives the database name from the connection specification passed to `connect` in the `connection-spec` parameter.

The database name is used via `find-database` in `connect` to determine whether database connections to the specified database exist already.

Usually the database name string will include indications of the host, database name, user, or port that where used during the connection attempt. The only important thing is that this string shall try to identify the database at the other end of the connection. Connection specifications parts like passwords and credentials shall not be used as part of the database name.

### Examples

    (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
    => "dent/newesim/dent"
    (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
    => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
    (database-name *default-database*)
    => "dent/newesim/dent"

    (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
    => "/template1/dent"
    (connect '(nil "template1" "dent" nil) :database-type :postgresql)
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
    (database-name *default-database*)
    => "/template1/dent"

    (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
    => "www.pmsf.de/template1/dent"

### Side Effects

None.

### Affected By

- `database-name-from-spec`

### Exceptional Situations

Will signal an error if the object passed as the `database` parameter is neither of type `database` nor of type `closed-database`.

### See Also

- `connect`
- `find-database`
- `connected-databases`
- `disconnect`
- `status`

### Notes

None.

DATABASE-NAME-FROM-SPEC

DATABASE-NAME-FROM-SPEC

Return the database name string corresponding to the given connection specification.

Generic Function

### Syntax

    	  database-name-from-spec connection-spec database-type => name

### Arguments and Values

`connection-spec`

- A connection specification, whose structure and interpretation are dependent on the `database-type`.

`database-type`

- A database type specifier, i.e. a keyword.

name

- A string denoting a database name.

### Description

This generic function takes a connection specification and a database type and returns the database name of the database object that would be created had `connect` been called with the given connection specification and database types.

This function is useful in determining a database name from the connection specification, since the way the connection specification is converted into a database name is dependent on the database type.

### Examples

    (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
    => "dent/newesim/dent"
    (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
    => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
    (database-name *default-database*)
    => "dent/newesim/dent"

    (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
    => "/template1/dent"
    (connect '(nil "template1" "dent" nil) :database-type :postgresql)
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
    (database-name *default-database*)
    => "/template1/dent"

    (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
    => "www.pmsf.de/template1/dent"

    (find-database "dent/newesim/dent")
    => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
    (find-database "/template1/dent")
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
    (find-database "www.pmsf.de/template1/dent" nil)
    => NIL
    (find-database **)
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

If the value of `connection-spec` is not a valid connection specification for the given database type, an error of type clsql-invalid-spec-error might be signalled.

### See Also

- `connect`

### Notes

`database-name-from-spec` is a &clsql; extension.

DATABASE-TYPE

DATABASE-TYPE

Get the type of a database object.

Generic Function

### Syntax

          database-type DATABASE => type

### Arguments and Values

`database`

- A database object, either of type `database` or of type `closed-database`.

type

- A keyword symbol denoting a known database back-end.

### Description

Returns the type of `database`.

### Examples

    (connect '(nil "template1" "dent" nil) :database-type :postgresql)
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
    (database-type *default-database*)
    => :postgresql

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

Will signal an error if the object passed as the `database` parameter is neither of type `database` nor of type `closed-database`.

### See Also

- `connect`
- `find-database`
- `connected-databases`
- `disconnect`
- `status`

### Notes

`database-type` is a &clsql; extension.

DISCONNECT

DISCONNECT

close a database connection

Function

### Syntax

    disconnect &key database error => result

### Arguments and Values

`error`

- A boolean flag indicating whether to signal an error if `database` is non-&nil; but cannot be found.

`database`

- The database to disconnect, which defaults to the database indicated by *default-database*.

`result`

- A Boolean indicating whether a connection was successfully disconnected.

### Description

This function takes a `database` object as returned by `connect`, and closes the connection. If no matching database is found and `error` and `database` are both non-&nil; an error is signaled, otherwise &nil; is returned. If the database is from a pool it will be released to this pool.

The status of the object passed is changed to closed after the disconnection succeeds, thereby preventing further use of the object as an argument to &clsql; functions, with the exception of `database-name` and `database-type`. If the user does pass a closed database to any other &clsql; function, an error of type sql-fatal-error is signalled.

### Examples

    (disconnect :database (find-database "dent/newesim/dent"))
    => T

### Side Effects

The database object is removed from the list of connected databases as returned by `connected-databases`.

If the database object passed is the same under `eq` as the value of *default-database*, then *default-database* is set to the first remaining database from `connected-databases` or to &nil; if no further active database exists.

#### Non-pooled

The database connection is closed and the state of the database object is changed to `closed`.

#### Pooled

Unless there are already *db-pool-max-free-connections* free connections in the pool it is returned to the pool, with the backend having an opportunity to run generic cleanup on the connection first. If the max free connections has already been reached then it is disconnected as if it were not in the pool.

### Affected by

- *default-database*
- *db-pool-max-free-connections*

### Exceptional Situations

If during the disconnection attempt an error is detected (e.g. because of network trouble or any other cause), an error of type sql-error might be signalled.

### See Also

- `connect`
- `disconnect-pooled`

### Notes

None.

DISCONNECT-POOLED

DISCONNECT-POOLED

closes all pooled database connections

Function

### Syntax

    disconnect-pooled &optional clear => t

### Description

This function disconnects all database connections that have been placed into the pool by calling `connect` with :pool &t;.

If optional argument clear is non-&nil; then the connection-pool objects are also removed.

### Examples

    (disconnect-pool)
    => T

### Side Effects

Database connections will be closed and *all* entries in the pool are removed. This is done with great prejudice and no thought to thread safety or whether that connection is currently in use.

### Affected by

- `disconnect`

### Exceptional Situations

If during the disconnection attempt an error is detected (e.g. because of network trouble or any other cause), an error of type clsql-error might be signalled.

### See Also

- `connect`
- `disconnect`

### Notes

`disconnect-pooled` is a &clsql; extension.

FIND-DATABASE

FIND-DATABASE

>Locate a database object through it's name.

Function

### Syntax

    find-database database &optional errorp => result

### Arguments and Values

`database`

- A database object or a string, denoting a database name.

`errorp`

- A generalized boolean. Defaults to t.

`db-type`

- A keyword symbol denoting a known database back-end.

result

- Either a database object, or, if `errorp` is &nil;, possibly &nil;.

### Description

`find-database` locates an active database object given the specification in `database`. If `database` is an object of type `database`, `find-database` returns this. Otherwise it will search the active databases as indicated by the list returned by `connected-databases` for a database of type `db-type` whose name (as returned by `database-name` is equal as per `string=` to the string passed as `database`. If it succeeds, it returns the first database found.

If `db-type` is &nil; all databases matching the string `database` are considered. If no matching databases are found and `errorp` is &nil; then &nil; is returned. If `errorp` is &nil; and one or more matching databases are found, then the most recently connected database is returned as a first value and the number of matching databases is returned as a second value. If no, or more than one, matching databases are found and `errorp` is true, an error is signalled.

### Examples

    (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
    => "dent/newesim/dent"
    (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
    => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
    (database-name *default-database*)
    => "dent/newesim/dent"

    (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
    => "/template1/dent"
    (connect '(nil "template1" "dent" nil) :database-type :postgresql)
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
    (database-name *default-database*)
    => "/template1/dent"

    (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
    => "www.pmsf.de/template1/dent"

    (find-database "dent/newesim/dent")
    => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
    (find-database "/template1/dent")
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
    (find-database "www.pmsf.de/template1/dent" nil)
    => NIL
    (find-database **)
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>

### Side Effects

None.

### Affected By

- `connected-databases`

### Exceptional Situations

Will signal an error of type clsql-error if no matching database can be found, and `errorp` is true. Will signal an error if the value of `database` is neither an object of type `database` nor a string.

### See Also

- `database-name`
- `database-name-from-spec`
- `disconnect`
- `connect`
- `status`
- `connected-databases`

### Notes

The `db-type` keyword argument to `find-database` is a &clsql; extension.

INITIALIZE-DATABASE-TYPE

INITIALIZE-DATABASE-TYPE

Initializes a database type

Function

### Syntax

          initialize-database-type &key database-type => result

### Arguments and Values

`database-type`

- The database type to initialize, i.e. a keyword symbol denoting a known database back-end. Defaults to the value of *default-database-type*.

result

- Either &nil; if the initialization attempt fails, or t otherwise.

### Description

If the back-end specified by `database-type` has not already been initialized, as seen from *initialized-database-types*, an attempt is made to initialize the database. If this attempt succeeds, or the back-end has already been initialized, the function returns t, and places the keyword denoting the database type onto the list stored in *initialized-database-types*, if not already present.

If initialization fails, the function returns &nil;, and/or signals an error of type clsql-error. The kind of action taken depends on the back-end and the cause of the problem.

### Examples

    *initialized-database-types*
    => NIL
    (setf *default-database-type* :mysql)
    => :MYSQL
    (initialize-database-type)
    >> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
    >> Compiling Top-Level Form:
    >>
    => T
    *initialized-database-types*
    => (:MYSQL)
    (initialize-database-type)
    => T
    *initialized-database-types*
    => (:MYSQL)

### Side Effects

The database back-end corresponding to the database type specified is initialized, unless it has already been initialized. This can involve any number of other side effects, as determined by the back-end implementation (like e.g. loading of foreign code, calling of foreign code, networking operations, etc.). If initialization is attempted and succeeds, the `database-type` is pushed onto the list stored in *initialized-database-types*.

### Affected by

- *default-database-type*
- *initialized-database-types*

### Exceptional Situations

If an error is encountered during the initialization attempt, the back-end may signal errors of kind clsql-error.

### See Also

- `*initialized-database-types*`
- `*default-database-type*`

### Notes

None.

RECONNECT

RECONNECT

Re-establishes the connection between a database object and its RDBMS.

Function

### Syntax

          reconnect &key database error force => result

### Arguments and Values

`database`

- The database to reconnect, which defaults to the database indicated by *default-database*.

`error`

- A boolean flag indicating whether to signal an error if `database` is non-nil but cannot be found. The default value is &nil;.

`force`

- A Boolean indicating whether to signal an error if the database connection has been lost. The default value is &t;.

`result`

- A Boolean indicating whether the database was successfully reconnected.

### Description

Reconnects `database` which defaults to *default-database* to the underlying database management system. On success, &t; is returned and the variable *default-database* is set to the newly reconnected database. If `database` is a database instance, this object is closed. If `database` is a string, then a connected database whose name matches `database` is sought in the list of connected databases. If no matching database is found and `error` and `database` are both non-&nil; an error is signaled, otherwise &nil; is returned.

When the current database connection has been lost, if `force` is non-&nil; as it is by default, the connection is closed and errors are suppressed. If `force` is &nil; and the database connection cannot be closed, an error is signalled.

### Examples

    *default-database*
    => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48CFBEA5}>
    (reconnect)
    => #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48D64105}>

### Side Effects

A database connection is re-established and *default-database* may be rebound to the supplied database object.

### Affected by

- *default-database*

### Exceptional Situations

An error may be signalled if the specified database cannot be located or if the database cannot be closed.

### See Also

- `connect`
- `disconnect`
- `disconnect-pooled`

### Notes

None.

STATUS

STATUS

Print information about connected databases.

Function

### Syntax

          status &optional full =>

### Arguments and Values

`full`

- A boolean indicating whether to print additional table information. The default value is &nil;.

### Description

Prints information about the currently connected databases to *STANDARD-OUTPUT*. The argument `full` is &nil; by default and a value of t means that more detailed information about each database is printed.

### Examples

    (status)

    CLSQL STATUS: 2004-06-13 15:07:39
    --------------------------------------------------------
       DATABASE                 TYPE               RECORDING
    --------------------------------------------------------
       localhost/test/petrov    mysql              nil
       localhost/test/petrov    postgresql         nil
       localhost/test/petrov    postgresql-socket  nil
       test/petrov              odbc               nil
    *  :memory:                 sqlite             nil
    --------------------------------------------------------

    (status t)

    CLSQL STATUS: 2004-06-13 15:08:08
    -------------------------------------------------------------------------------
       DATABASE                 TYPE               RECORDING  POOLED  TABLES  VIEWS
    -------------------------------------------------------------------------------
       localhost/test/petrov    mysql              nil        nil     7       0
       localhost/test/petrov    postgresql         nil        nil     7       0
       localhost/test/petrov    postgresql-socket  nil        nil     7       0
       test/petrov              odbc               nil        nil     7       0
    *  :memory:                 sqlite             nil        nil     0       0
    -------------------------------------------------------------------------------

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

### See Also

- `connected-databases`
- `connect`
- `disconnect`
- `*connect-if-exists*`
- `find-database`

### Notes

None.

CREATE-DATABASE

CREATE-DATABASE

create a database

Function

### Syntax

    create-database connection-spec &key database-type => success

### Arguments and Values

`connection-spec`

- A connection specification

`database-type`

- A database type specifier, i.e. a keyword. This defaults to the value of *default-database-type*

`success`

- A boolean flag. If &t;, a new database was successfully created.

### Description

This function creates a database in the database system specified by `database-type`.

### Examples

    (create-database '("localhost" "new" "dent" "dent") :database-type :mysql)
    => T

    (create-database '("localhost" "new" "dent" "badpasswd") :database-type :mysql)
    =>
    Error: While trying to access database localhost/new/dent
      using database-type MYSQL:
      Error database-create failed: mysqladmin: connect to server at 'localhost' failed
    error: 'Access denied for user: 'root@localhost' (Using password: YES)'
      has occurred.
      [condition type: CLSQL-ACCESS-ERROR]

### Side Effects

A database will be created on the filesystem of the host.

### Exceptional Situations

An exception will be thrown if the database system does not allow new databases to be created or if database creation fails.

### See Also

- `destroy-database`
- `probe-database`
- `list-databases`

### Notes

This function may invoke the operating systems functions. Thus, some database systems may require the administration functions to be available in the current PATH. At this time, the :mysql backend requires `mysqladmin` and the :postgresql backend requires `createdb`.

`create-database` is a &clsql; extension.

DESTROY-DATABASE

DESTROY-DATABASE

destroys a database

Function

### Syntax

    destroy-database connection-spec &key database-type => success

### Arguments and Values

`connection-spec`

- A connection specification

`database-type`

- A database type specifier, i.e. a keyword. This defaults to the value of *default-database-type*

`success`

- A boolean flag. If &t;, the database was successfully destroyed.

### Description

This function destroys a database in the database system specified by `database-type`.

### Examples

    (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
    => T

    (destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
    =>
    Error: While trying to access database localhost/test2/root
      using database-type POSTGRESQL:
      Error database-destroy failed: dropdb: database removal failed: ERROR:  database "test2" does not exist
      has occurred.
      [condition type: CLSQL-ACCESS-ERROR]

### Side Effects

A database will be removed from the filesystem of the host.

### Exceptional Situations

An exception will be thrown if the database system does not allow databases to be removed, the database does not exist, or if database removal fails.

### See Also

- `create-database`
- `probe-database`
- `list-databases`

### Notes

This function may invoke the operating systems functions. Thus, some database systems may require the administration functions to be available in the current PATH. At this time, the :mysql backend requires `mysqladmin` and the :postgresql backend requires `dropdb`.

`destroy-database` is a &clsql; extension.

PROBE-DATABASE

PROBE-DATABASE

tests for existence of a database

Function

### Syntax

    probe-database connection-spec &key database-type => success

### Arguments and Values

`connection-spec`

- A connection specification

`database-type`

- A database type specifier, i.e. a keyword. This defaults to the value of *default-database-type*

`success`

- A boolean flag. If &t;, the database exists in the database system.

### Description

This function tests for the existence of a database in the database system specified by `database-type`.

### Examples

    (probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
    => T

### Side Effects

None

### Exceptional Situations

An exception maybe thrown if the database system does not receive administrator-level authentication since function may need to read the administrative database of the database system.

### See Also

- `create-database`
- `destroy-database`
- `list-databases`

### Notes

`probe-database` is a &clsql; extension.

LIST-DATABASES

LIST-DATABASES

List databases matching the supplied connection spec and database type.

Function

### Syntax

          list-databases connection-spec &key database-type => result

### Arguments and Values

`connection-spec`

- A connection specification

`database-type`

- A database type specifier, i.e. a keyword. This defaults to the value of *default-database-type*

`result`

- A list of matching databases.

### Description

This function returns a list of databases existing in the database system specified by `database-type`.

### Examples

    (list-databases '("localhost" "new" "dent" "dent") :database-type :postgresql)
    => ("address-book" "sql-test" "template1" "template0" "test1" "dent" "test")

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

An exception maybe thrown if the database system does not receive administrator-level authentication since function may need to read the administrative database of the database system.

### See Also

- `create-database`
- `destroy-database`
- `probe-database`

### Notes

`list-databases` is a &clsql; extension.

WITH-DATABASE

WITH-DATABASE

Execute a body of code with a variable bound to a specified database object.

Macro

### Syntax

          with-database db-var connection-spec &rest connect-args &body body => result

### Arguments and Values

`db-var`

- A variable which is bound to the specified database.

`connection-spec`

- A vendor specific connection specification supplied as a list or as a string.

`connect-args`

- Other optional arguments to `connect`. This macro use a value of &nil; for `connect`'s `make-default` key, This is in contrast to to the connect function which has a default value of &t; for `make-default`.

`body`

- A Lisp code body.

`result`

- Determined by the result of executing the last expression in `body`.

### Description

Evaluate `body` in an environment, where `db-var` is bound to the database connection given by `connection-spec` and `connect-args`. The connection is automatically closed or released to the pool on exit from the body.

### Examples

    (connected-databases)
    => NIL
    (with-database (db '(":memory:") :database-type :sqlite
                    :make-default nil)
      (database-name db))
    => ":memory:"
    (connected-databases)
    => NIL

### Side Effects

See `connect` and `disconnect`.

### Affected by

See `connect` and `disconnect`.

### Exceptional Situations

See `connect` and `disconnect`.

### See Also

- `connect`
- `disconnect`
- `disconnect-pooled`
- `with-default-database`

### Notes

`with-database` is a &clsql; extension.

WITH-DEFAULT-DATABASE

WITH-DEFAULT-DATABASE

Execute a body of code with *default-database* bound to a specified database.

Macro

### Syntax

          with-default-database database &rest body => result

### Arguments and Values

`database`

- An active database object.

`body`

- A Lisp code body.

`result`

- Determined by the result of executing the last expression in `body`.

### Description

Perform `body` with `DATABASE` bound as *default-database*.

### Examples

    *default-database*
    => #<CLSQL-ODBC:ODBC-DATABASE new/dent OPEN {49095CAD}>

    (let ((database (clsql:find-database ":memory:")))
      (with-default-database (database)
        (database-name *default-database*)))
    => ":memory:"

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

Calls to &clsql; functions in `body` may signal errors if `database` is not an active database object.

### See Also

- `with-database`
- *default-database*

### Notes

`with-default-database` is a &clsql; extension.