CONNECT
Prev | Connection and Initialisation | Next

## Name

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.

Prev | Up | Next
*INITIALIZED-DATABASE-TYPES* | Home | CONNECTED-DATABASES