CONNECT — create a connection to a database.Function


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

Arguments and Values


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.


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


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


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.


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


The database object representing the connection.


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:


Go ahead and create a new connection.


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


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.


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


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.


(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
=> "dent/newesim/dent"
(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
(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/
>>               (CREATE-NEW NIL :REPORT "Create a new connection."
>>                (SETQ RESULT #))
>>               (USE-OLD NIL :REPORT "Use the existing connection."
>>                (SETQ RESULT OLD-DB)))
>> 0] 0

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


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



The pool and make-default keyword arguments to connect are CLSQL extensions.