CONNECT — create a connection to a database.Function
connection-specA 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-existsThis 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-typeA database type specifier, i.e. a keyword. This defaults to the value of *default-database-type*
poolA 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-defaultA 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)
=> #<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}>
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.
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.