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.