Function

Summary

Opens a connection to a database.

Package

sql

Signature

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

Arguments

connection-spec

The connection specifications.

if-exists

A keyword.

database-type

A database type.

interface

A displayed CAPI element, or nil .

Values

database

A database.

Description

The connect function opens a connection to a database of type database-type .

The allowed values for database-type are :odbc , :postgresql and :oracle8 , though not all of these are supported on some platforms. See the section "Supported databases" in the LispWorks User Guide for details of per-platform database support.

The default for database-type is the value of *default-database-type*.

connect sets the variable *default-database* to an instance of the database opened, and returns that instance.

The format of connection-spec depends on the type of the database to connect to. For databases of type :odbc , the connection specification is a string of the format

" datasource-name / username / password "

where datasource-name is the name of an ODBC datasource, and username and password are a valid username and password. If the datasource does not require a username and password they can be omitted. For databases of type :oracle8 , the connection specification is passed as-is to the Oracle logon call. For example, if you have an Oracle user matching the current Unix username and that does need a password to connect, you can call

(connect "/")

To connect to Oracle via SQL*Net, connection-spec is of the form " username/password@host " where host is an Oracle hostname.

The argument if-exists modifies the behavior of connect as follows:

:new

Makes a new connection even if connections to the same database already exist.

:warn-new

Makes a new connection but warns about existing connections.

:error

Makes a new connection but signals an error for existing connections.

:warn-old

Selects old connection if one exists (and warns) or makes a new one.

:old

Selects old connection if one exists or makes a new one.

The default value of if-exists is the value of *connect-if-exists*.

interface is used if connect needs to display a dialog to ask the user for username and password. If interface is a CAPI element, this is used. If interface is any other value (the default value is nil ), and connect is called in a process which is associated with a CAPI interface, then this CAPI interface is used. interface has been added because dialogs asking for passwords can fail otherwise. This depends on the driver that the datasource uses: the problem has only been observed using MS SQL on Windows.

Example

The following example connects LispWorks to the info database.

(connect "info")

The next example connects to the ODBC database personnel using the username "admin" and the password "secret".

(connect "personnel/admin/secret" :database-type :odbc)

See also

*default-database*
*default-database-type*
connected-databases
*connect-if-exists*
database-name
disconnect
find-database
reconnect
status