X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=doc%2Fref-connect.xml;h=4bc296b3fa843278fd26b9d80963f55a4dec18f5;hp=855e20193873277a2fe69b597ebae30a58a1ac77;hb=528064c179b6b74f0a9d6a43c42e71de3f0e9a3a;hpb=749215ad8b022f7e2d533f5f82097d2d131eefd6 diff --git a/doc/ref-connect.xml b/doc/ref-connect.xml index 855e201..4bc296b 100644 --- a/doc/ref-connect.xml +++ b/doc/ref-connect.xml @@ -5,18 +5,24 @@ %myents; ]> - Connection and Initialisation - + This section describes the &clsql; interface for initialising + database interfaces of different types, creating and destroying + databases and connecting and disconnecting from databases. - + + + + + DATABASE + - DATABASE + Class DATABASE The super-type of all &clsql; databases Class @@ -31,11 +37,12 @@ - Description This class is the superclass - of all &clsql; databases. The different database back-ends - derive subclasses of this class to implement their databases. - No instances of this class are ever created by &clsql;. + Description This class is the superclass of + all &clsql; databases. The different database back-ends derive + subclasses of this class to implement their databases. No + instances of this class are ever created by &clsql;. + + + *CONNECT-IF-EXISTS* + - *CONNECT-IF-EXISTS* + Variable *CONNECT-IF-EXISTS* Default value for the - if-exists parameter of - connect. + if-exists parameter of connect. Variable @@ -115,11 +126,13 @@ - + + *DEFAULT-DATABASE* + - *DEFAULT-DATABASE* - The default database object to use + Variable *DEFAULT-DATABASE* + The default database object to use. Variable @@ -133,11 +146,9 @@ Description - Any function or macro in - &clsql; that operates on a - database uses the value of this variable as the default - value for it's database - parameter. + Any function or macro in &clsql; that operates on a + database uses the value of this variable as the default value + for it's database parameter. The value of this parameter is changed by calls to connect, which sets *default-database* to the database object @@ -155,10 +166,10 @@ at any time to a valid value of his choice. If the value of *default-database* is - nil, then all calls to - &clsql; functions on databases - must provide a suitable database - parameter, or an error will be signalled. + nil, then all calls to &clsql; functions on + databases must provide a suitable + database parameter, or an error will be + signalled. @@ -192,12 +203,10 @@ Affected By - - - connect - disconnect - - + + connect + disconnect + See Also @@ -227,18 +236,19 @@ - + + *DEFAULT-DATABASE-TYPE* + - *DEFAULT-DATABASE-TYPE* + Variable *DEFAULT-DATABASE-TYPE* The default database type to use Variable Value Type Any keyword representing a valid database back-end of - &clsql;, or - nil. + &clsql;, or nil. Initial Value @@ -248,9 +258,8 @@ Description The value of this variable is used in calls to initialize-database-type and - connect as the default - value of the database-type - parameter. + connect as the default value of the + database-type parameter. If the value of this variable is nil, then all calls to @@ -275,7 +284,10 @@ See Also - None. + + intitialize-database-type + Notes @@ -284,8 +296,11 @@ + + *INITIALIZED-DATABASE-TYPES* + - *INITIALIZED-DATABASE-TYPES* + Variable *INITIALIZED-DATABASE-TYPES* List of all initialized database types Variable @@ -302,10 +317,9 @@ Description This variable is updated whenever initialize-database-type is called for a - database type which hasn't already been initialized before, - as determined by this variable. In that case the keyword - representing the database type is pushed onto the list - stored in + database type which hasn't already been initialized before, as + determined by this variable. In that case the keyword + representing the database type is pushed onto the list stored in *INITIALIZED-DATABASE-TYPES*. Attempts to modify the value of this variable will @@ -333,7 +347,10 @@ See Also - None. + + intitialize-database-type + Notes @@ -344,1161 +361,1900 @@ + + CONNECT + - CONNECT - + Function CONNECT + create a connection to a database. Function Syntax - - (CONNECT CONNECTION-SPEC &KEY (IF-EXISTS *CONNECT-IF-EXISTS*) (MAKE-DEFAULT T) (POOL NIL) (DATABASE-TYPE *DEFAULT-DATABASE-TYPE*)) [function] => + Syntax + connect connection-spec &key if-exists database-type pool make-default => database Arguments and Values - + + connection-spec + + A vendor specific connection specification supplied + as a list or as a string. + + + + 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;. This is a + &clsql; extension. + + + + + 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;. This is a &clsql; + extension. + + + + + database + + The database object representing the connection. + + Description - Connects to a database of the supplied DATABASE-TYPE - which defaults to *DEFAULT-DATABASE-TYPE*, using the - type-specific connection specification CONNECTION-SPEC. The - value of IF-EXISTS, which defaults to *CONNECT-IF-EXISTS*, - determines what happens if a connection to the database - specified by CONNECTION-SPEC is already established. A value - of :new means create a new connection. A value of :warn-new - means warn the user and create a new connect. A value of - :warn-old means warn the user and use the old connection. A - value of :error means fail, notifying the user. A value of - :old means return the old connection. MAKE-DEFAULT is t by - default which means that *DEFAULT-DATABASE* is set to the new - connection, otherwise *DEFAULT-DATABASE* is not changed. If - POOL is t the connection will be taken from the general pool, - if POOL is a CONN-POOL object the connection will be taken - from this pool. - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - - - - - Exceptional Situations - - + 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 + + + - - - See Also - - - + 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 - - - - - + + + Notes + None. + + + + CONNECTED-DATABASES + - CONNECTED-DATABASES - + Function CONNECTED-DATABASES + Return the list of active database objects. Function Syntax - (CONNECTED-DATABASES) [function] => + connected-databases => databases Arguments and Values - + + databases + + The list of active database objects. + + Description - Returns the list of active database objects. - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - - - - - Exceptional Situations - - - - - - See Also - + This function returns the list of active database + objects, i.e. all those database objects created by calls to + connect, which have not been closed by + calling disconnect on them. + + The consequences of modifying the list returned by + connected-databases are + undefined. + + + + Examples + +(connected-databases) +=> NIL +(connect '(nil "template1" "dent" nil) :database-type :postgresql) +=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}> +(connect '("dent" "newesim" "dent" "dent") :database-type :mysql) +=> #<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}> +(connected-databases) +=> (#<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}> + #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>) +(disconnect) +=> T +(connected-databases) +=> (#<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>) +(disconnect) +=> T +(connected-databases) +=> NIL + + + + Side Effects + None. + + + Affected By + + + connect + disconnect + + + + + Exceptional Situations + None. + + + See Also - - - - + disconnect + connect + status + find-database + + + + Notes + None. + + + + + + + DATABASE-NAME + + + Generic Function DATABASE-NAME + Get the name of a database object + Generic Function + - Notes - - - - - + Syntax + database-name database => name + + + Arguments and Values + + + database + + A database object, either of type + database or of type + closed-database. + + + + name + + A string describing the identity of the database + to which this database object is connected to. + + + + + + Description + This function returns the database name of the given + database. The database name is a string which somehow + describes the identity of the database to which this + database object is or has been connected. The database name + of a database object is determined at + connect time, when a call to + database-name-from-spec derives the + database name from the connection specification passed to + connect in the + connection-spec parameter. + The database name is used via + find-database in + connect to determine whether database + connections to the specified database exist already. + Usually the database name string will include + indications of the host, database name, user, or port that + where used during the connection attempt. The only + important thing is that this string shall try to identify + the database at the other end of the connection. Connection + specifications parts like passwords and credentials shall + not be used as part of the database name. + + + 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 {48391DCD}> +(database-name *default-database*) +=> "dent/newesim/dent" - +(database-name-from-spec '(nil "template1" "dent" nil) :postgresql) +=> "/template1/dent" +(connect '(nil "template1" "dent" nil) :database-type :postgresql) +=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}> +(database-name *default-database*) +=> "/template1/dent" + +(database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql) +=> "www.pmsf.de/template1/dent" + + + + Side Effects + None. + + + Affected By + + + database-name-from-spec + + + + + Exceptional Situations + Will signal an error if the object passed as the + database parameter is neither of type + database nor of type + closed-database. + + + See Also + + + connect + find-database + connected-databases + disconnect + status + + + + + Notes + None. + + + + + + DATABASE-NAME-FROM-SPEC + + + Generic Function DATABASE-NAME-FROM-SPEC + Return the database name string corresponding to + the given connection specification. + Generic Function + + + Syntax + + database-name-from-spec connection-spec database-type => name + + + Arguments and Values + + + connection-spec + + A connection specification, whose structure and + interpretation are dependent on the + database-type. + + + + database-type + + A database type specifier, i.e. a keyword. + + + + name + + A string denoting a database name. + + + + + + Description + This generic function takes a connection specification + and a database type and returns the database name of the + database object that would be created had + connect been called with the given + connection specification and database types. + This function is useful in determining a database name + from the connection specification, since the way the + connection specification is converted into a database name + is dependent on the database type. + + + 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 {48391DCD}> +(database-name *default-database*) +=> "dent/newesim/dent" + +(database-name-from-spec '(nil "template1" "dent" nil) :postgresql) +=> "/template1/dent" +(connect '(nil "template1" "dent" nil) :database-type :postgresql) +=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}> +(database-name *default-database*) +=> "/template1/dent" + +(database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql) +=> "www.pmsf.de/template1/dent" + +(find-database "dent/newesim/dent") +=> #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}> +(find-database "/template1/dent") +=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}> +(find-database "www.pmsf.de/template1/dent" nil) +=> NIL +(find-database **) +=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}> + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + If the value of connection-spec + is not a valid connection specification for the given + database type, an error of type + clsql-invalid-spec-error might be + signalled. + + + See Also + + + connect + + + + + Notes + database-name-from-spec is a + &clsql; extension. + + + + + + DATABASE-TYPE + - CREATE-DATABASE - - Function + Generic Function DATABASE-TYPE + Get the type of a database object. + Generic Function Syntax - (CREATE-DATABASE CONNECTION-SPEC &KEY DATABASE-TYPE) [function] => + database-type DATABASE => type Arguments and Values - - + + + database + + A database object, either of type + database or of type + closed-database. + + + + type + + A keyword symbol denoting a known database back-end. + + Description - + Returns the type of database. Examples - +(connect '(nil "template1" "dent" nil) :database-type :postgresql) +=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}> +(database-type *default-database*) +=> :postgresql Side Effects - + None. Affected by - - - + None. Exceptional Situations - - - + Will signal an error if the object passed as the + database parameter is neither of type + database nor of type + closed-database. See Also - + connect + find-database + connected-databases + disconnect + status Notes - + database-type is a &clsql; extension. - + + + DISCONNECT + + + Function DISCONNECT + close a database connection + Function + + + Syntax + disconnect &key database error => result + + + Arguments and Values + + + error + + A boolean flag indicating whether to signal an error + if database is non-nil but cannot + be found. + + + + + database + + The database to disconnect, which defaults to the + database indicated by + *default-database*. + + + + result + + A Boolean indicating whether a connection was + successfully disconnected. + + + + + + + Description + This function takes a database object as + returned by connect, and closes the + connection. If no matching database is found and + error and + database are both non-nil an error is + signaled, otherwise nil is returned. If the database is from a + pool it will be released to this pool. + + + The status of the object passed is changed to closed + after the disconnection succeeds, thereby preventing further + use of the object as an argument to &clsql; functions, with + the exception of database-name and + database-type. If the user does pass a + closed database to any other &clsql; function, an error of + type sql-fatal-error is + signalled. + + + Examples + +(disconnect :database (find-database "dent/newesim/dent")) +=> T + + + + Side Effects + The database connection is closed, and the database + object is removed from the list of connected databases as + returned by connected-databases. + The state of the database object is changed to + closed. + If the database object passed is the same under + eq as the value of + *default-database*, then + *default-database* is set to the first + remaining database from + connected-databases or to nil if no + further active database exists. + + + Affected by + + + *default-database* + + + + + Exceptional Situations + If during the disconnection attempt an error is detected + (e.g. because of network trouble or any other cause), an error + of type sql-error might be + signalled. + + + See Also + + + connect + disconnect-pooled + + + + + Notes + None. + + + + + + DISCONNECT-POOLED + + + Function DISCONNECT-POOLED + closes all pooled database connections + Function + + + Syntax + disconnect-pooled => t + + + Description + This function disconnects all database connections + that have been placed into the pool by calling connect with + :pool &t;. + + + + Examples + +(disconnect-pool) +=> T + + + + Side Effects + Database connections will be closed and entries in the pool are removed. + + + + Affected by + + + disconnect + + + + + Exceptional Situations + If during the disconnection attempt an error is + detected (e.g. because of network trouble or any other + cause), an error of type clsql-error + might be signalled. + + + See Also + + + connect + disconnect + + + + + Notes + disconnect-pooled is a &clsql; + extension. + + + + + + FIND-DATABASE + + + Function FIND-DATABASE + >Locate a database object through it's + name. + Function + + + Syntax + find-database database &optional errorp => result + + + Arguments and Values + + + database + + A database object or a string, denoting a database + name. + + + + errorp + + A generalized boolean. Defaults to + t. + + + + db-type + + + A keyword symbol denoting a known database back-end. This + is a &clsql; extension. + + + + + result + + Either a database object, or, if + errorp is nil, + possibly nil. + + + + + + Description + find-database locates an active + database object given the specification in + database. If + database is an object of type + database, find-database + returns this. Otherwise it will search the active databases + as indicated by the list returned by + connected-databases for a database of + type db-type whose name (as returned by + database-name is equal as per + string= to the string passed as + database. If it succeeds, it returns + the first database found. + + If db-type is nil all databases + matching the string database are + considered. If no matching databases are found and + errorp is nil then nil is + returned. If errorp is nil and one or + more matching databases are found, then the most recently + connected database is returned as a first value and the + number of matching databases is returned as a second + value. If no, or more than one, matching databases are found + and errorp is true, an error is + signalled. + + + + 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 {48391DCD}> +(database-name *default-database*) +=> "dent/newesim/dent" + +(database-name-from-spec '(nil "template1" "dent" nil) :postgresql) +=> "/template1/dent" +(connect '(nil "template1" "dent" nil) :database-type :postgresql) +=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}> +(database-name *default-database*) +=> "/template1/dent" + +(database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql) +=> "www.pmsf.de/template1/dent" + +(find-database "dent/newesim/dent") +=> #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}> +(find-database "/template1/dent") +=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}> +(find-database "www.pmsf.de/template1/dent" nil) +=> NIL +(find-database **) +=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}> + + + + Side Effects + None. + + + Affected By + + + connected-databases + + + + + Exceptional Situations + Will signal an error of type + clsql-error if no matching database + can be found, and errorp is true. + Will signal an error if the value of + database is neither an object of type + database nor a string. + + + See Also + + + database-name + database-name-from-spec + disconnect + connect + status + connected-databases + + + + + Notes + None. + + + + + + INITIALIZE-DATABASE-TYPE + - DATABASE-NAME - + Function INITIALIZE-DATABASE-TYPE + Initializes a database type Function Syntax - (DATABASE-NAME (OBJ DATABASE)) [reader] => + initialize-database-type &key database-type => result Arguments and Values - + + database-type + + The database type to initialize, i.e. a keyword + symbol denoting a known database back-end. Defaults to + the value of + *default-database-type*. + + + + result + + Either nil if the initialization + attempt fails, or t otherwise. + + - - Description - - "Returns the name of DATABASE." - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - - - - - Exceptional Situations - - - - - - See Also - - - - - - - - Notes - - - - - + + Description + If the back-end specified by + database-type has not already been + initialized, as seen from + *initialized-database-types*, an attempt is + made to initialize the database. If this attempt succeeds, + or the back-end has already been initialized, the function + returns t, and places the keyword denoting the database type + onto the list stored in + *initialized-database-types*, if not + already present. + If initialization fails, the function returns + nil, and/or signals an error of type + clsql-error. The kind of action + taken depends on the back-end and the cause of the + problem. + + + Examples + +*initialized-database-types* +=> NIL +(setf *default-database-type* :mysql) +=> :MYSQL +(initialize-database-type) +>> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902): +>> Compiling Top-Level Form: +>> +=> T +*initialized-database-types* +=> (:MYSQL) +(initialize-database-type) +=> T +*initialized-database-types* +=> (:MYSQL) + + + + Side Effects + The database back-end corresponding to the database type + specified is initialized, unless it has already been + initialized. This can involve any number of other side + effects, as determined by the back-end implementation (like + e.g. loading of foreign code, calling of foreign code, + networking operations, etc.). If initialization is + attempted and succeeds, the + database-type is pushed onto the list + stored in + *initialized-database-types*. + + + Affected by + + + *default-database-type* + *initialized-database-types* + + + + + Exceptional Situations + If an error is encountered during the initialization + attempt, the back-end may signal errors of kind + clsql-error. + + + See Also + + *initialized-database-types* + *default-database-type* + + + + Notes + None. + + - + + + RECONNECT + - DATABASE-TYPE - + Function RECONNECT + Re-establishes the connection between a database object and its RDBMS. Function Syntax - (DATABASE-TYPE (OBJ DATABASE)) [reader] => + reconnect &key database error force => result Arguments and Values - + + database + + The database to reconnect, which defaults to the + database indicated by + *default-database*. + + + + error + + A boolean flag indicating whether to signal an error + if database is non-nil but cannot + be found. The default value is &nil;. + + + + + force + + A Boolean indicating whether to signal an error if the + database connection has been lost. The default value is &t;. + + + + + result + + A Boolean indicating whether the database was + successfully reconnected. + + + Description - - "Returns the type of DATABASE." + Reconnects database which defaults + to *default-database* to the underlying + database management system. On success, &t; is returned and the + variable *default-database* is set to the newly + reconnected database. If database is a + database instance, this object is closed. If + database is a string, then a connected + database whose name matches database is + sought in the list of connected databases. If no matching + database is found and error and + database are both non-nil an error is + signaled, otherwise nil is returned. + + When the current database connection has been lost, if + force is non-nil as it is by default, the + connection is closed and errors are suppressed. If + force is nil and the database connection + cannot be closed, an error is signalled. Examples - +*default-database* +=> #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48CFBEA5}> +(reconnect) +=> #<CLSQL-SQLITE:SQLITE-DATABASE :memory: OPEN {48D64105}> Side Effects - - - + A database connection is re-established and + *default-database* may be rebound to the supplied + database object. Affected by - + *default-database* Exceptional Situations - - + An error may be signalled if the specified database cannot be + located or if the database cannot be closed. + See Also - + connect + disconnect + disconnect-pooled Notes - + None. - + + + STATUS + - DESTROY-DATABASE - + Function STATUS + Print information about connected databases. Function Syntax - (DESTROY-DATABASE CONNECTION-SPEC &KEY DATABASE-TYPE) [function] => + status &optional full => Arguments and Values - + + full + + A boolean indicating whether to print additional + table information. The default value is &nil;. + + + Description - - + Prints information about the currently connected databases + to *STANDARD-OUTPUT*. The argument + full is nil by default and a value of t + means that more detailed information about each database is + printed. Examples - - +(status) + +CLSQL STATUS: 2004-06-13 15:07:39 +-------------------------------------------------------- + DATABASE TYPE RECORDING +-------------------------------------------------------- + localhost/test/petrov mysql nil + localhost/test/petrov postgresql nil + localhost/test/petrov postgresql-socket nil + mysql-test/petrov odbc nil +* :memory: sqlite nil +-------------------------------------------------------- + +(status t) + +CLSQL STATUS: 2004-06-13 15:08:08 +------------------------------------------------------------------------------- + DATABASE TYPE RECORDING POOLED TABLES VIEWS +------------------------------------------------------------------------------- + localhost/test/petrov mysql nil nil 7 0 + localhost/test/petrov postgresql nil nil 7 0 + localhost/test/petrov postgresql-socket nil nil 7 0 + test/petrov odbc nil nil 7 0 +* :memory: sqlite nil nil 0 0 +------------------------------------------------------------------------------- + Side Effects - + None. Affected by - - - + None. Exceptional Situations - + None. See Also - + connected-databases + connect + disconnect + *connect-if-exists* + find-database Notes - + None. - + + + + + + CREATE-DATABASE + - DISCONNECT - - Function - - - Syntax - - (DISCONNECT &KEY (DATABASE *DEFAULT-DATABASE*) (ERROR NIL)) [function] => - - - Arguments and Values - - - - - - Description - Closes the connection to DATABASE and resets - *DEFAULT-DATABASE* if that database was - disconnected. If DATABASE is a database instance, this - object is closed. If DATABASE is a string, then a - connected database whose name matches DATABASE is - sought in the list of connected databases. If no - matching database is found and ERROR and DATABASE are - both non-nil an error is signaled, otherwise nil is - returned. If the database is from a pool it will be - released to this pool. - - - - Examples - - - - - - Side Effects - - - - + Function CREATE-DATABASE + create a database + Function + + + Syntax + create-database connection-spec &key database-type => success + + + Arguments and Values + + + connection-spec + + A connection specification + + + + database-type + + A database type specifier, i.e. a keyword. + This defaults to the value of + *default-database-type* + + + + success + + A boolean flag. If &t;, a new database was + successfully created. + + + + + + + Description + This function creates a database in the database system + specified by database-type. + + + + Examples + +(create-database '("localhost" "new" "dent" "dent") :database-type :mysql) +=> T + +(create-database '("localhost" "new" "dent" "badpasswd") :database-type :mysql) +=> +Error: While trying to access database localhost/new/dent + using database-type MYSQL: + Error database-create failed: mysqladmin: connect to server at 'localhost' failed +error: 'Access denied for user: 'root@localhost' (Using password: YES)' + has occurred. + [condition type: CLSQL-ACCESS-ERROR] + + + + Side Effects + A database will be created on the filesystem of the host. + + + Exceptional Situations + An exception will be thrown if the database system does + not allow new databases to be created or if database creation + fails. + - Affected by + See Also - + destroy-database + probe-database + list-databases - - Exceptional Situations - - - - + + Notes + This function may invoke the operating systems + functions. Thus, some database systems may require the + administration functions to be available in the current + PATH. At this time, the + :mysql backend requires + mysqladmin and the + :postgresql backend requires + createdb. + + create-database is a &clsql; extension. + + + + + + + DESTROY-DATABASE + + + Function DESTROY-DATABASE + destroys a database + Function + + + Syntax + destroy-database connection-spec &key database-type => success + + + Arguments and Values + + + connection-spec + + A connection specification + + + + database-type + + A database type specifier, i.e. a keyword. + This defaults to the value of + *default-database-type* + + + + success + + A boolean flag. If &t;, the database was + successfully destroyed. + + + + + + + Description + This function destroys a database in the database system + specified by database-type. + + + + Examples + +(destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql) +=> T + +(destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql) +=> +Error: While trying to access database localhost/test2/root + using database-type POSTGRESQL: + Error database-destory failed: dropdb: database removal failed: ERROR: database "test2" does not exist + has occurred. + [condition type: CLSQL-ACCESS-ERROR] + + + + Side Effects + A database will be removed from the filesystem of the host. + + + Exceptional Situations + An exception will be thrown if the database system does not + allow databases to be removed, the database does not exist, or + if database removal fails. + See Also - + create-database + probe-database + list-databases + + Notes + This function may invoke the operating systems + functions. Thus, some database systems may require the + administration functions to be available in the current + PATH. At this time, the + :mysql backend requires + mysqladmin and the + :postgresql backend requires + dropdb. + + destroy-database is a &clsql; extension. + + + + + + + PROBE-DATABASE + + + Function PROBE-DATABASE + tests for existence of a database + Function + + + Syntax + probe-database connection-spec &key database-type => success + + + Arguments and Values + + + connection-spec + + A connection specification + + + + database-type + + A database type specifier, i.e. a keyword. + This defaults to the value of + *default-database-type* + + + + success + + A boolean flag. If &t;, the database exists + in the database system. + + + + + + + Description + This function tests for the existence of a database in + the database system specified by + database-type. + + + + Examples + +(probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql) +=> T + + + + Side Effects + None + + + Exceptional Situations + An exception maybe thrown if the database system does + not receive administrator-level authentication since function + may need to read the administrative database of the database + system. + - Notes + See Also - + + create-database + destroy-database + list-databases + - + + Notes + + probe-database is a &clsql; extension. + + + - + + + LIST-DATABASES + - DISCONNECT-POOLED - + Function LIST-DATABASES + List databases matching the supplied connection spec + and database type. Function Syntax - (DISCONNECT-POOLED &OPTIONAL CLEAR) [function] => + list-databases connection-spec &key database-type => result Arguments and Values - + + connection-spec + + A connection specification + + + + database-type + + A database type specifier, i.e. a keyword. + This defaults to the value of + *default-database-type* + + + + result + + A list of matching databases. + + + - + Description - Disconnects all connections in the pool. + + This function returns a list of databases existing in the + database system specified by + database-type. Examples - +(list-databases '("localhost" "new" "dent" "dent") :database-type :postgresql) +=> ("address-book" "sql-test" "template1" "template0" "test1" "dent" "test") Side Effects - + None. - + Affected by - - - + None. Exceptional Situations - + An exception maybe thrown if the database system does not + receive administrator-level authentication since function may + need to read the administrative database of the database + system. See Also - + create-database + destroy-database + probe-database Notes - + list-databases is a &clsql; extension. - + + + + + WITH-DATABASE + - FIND-DATABASE - - Function + Macro WITH-DATABASE + Execute a body of code with a variable bound to a + specified database object. + Macro Syntax - (FIND-DATABASE DATABASE &KEY (ERRORP T) (DB-TYPE NIL)) [function] => + with-database db-var connection-spec &rest connect-args &body body => result Arguments and Values - + + db-var + + A variable to which the specified database is bound. + + + + + connection-spec + + A vendor specific connection specification supplied + as a list or as a string. + + + + connect-args + + Other optional arguments to connect. + + + + + body + + A Lisp code body. + + + + + result + + Determined by the result of executing the last + expression in body. + + + Description - Returns the connected databases of type - DB-TYPE whose names match the string DATABASE. If - DATABASE is a database object, it is returned. If - DB-TYPE is nil all databases matching the string - DATABASE are considered. If no matching databases are - found and ERRORP is nil then nil is returned. If - ERRORP is nil and one or more matching databases are - found, then the most recently connected database is - returned as a first value and the number of matching - databases is returned as a second value. If no, or - more than one, matching databases are found and ERRORP - is true, an error is signalled. + Evaluate body in an environment, + where db-var is bound to the database + connection given by connection-spec and + connect-args. The connection is + automatically closed or released to the pool on exit from the + body. Examples - +(connected-databases) +=> NIL +(with-database (db '(":memory:") :database-type :sqlite + :make-default nil) + (database-name db)) +=> ":memory:" +(connected-databases) +=> NIL Side Effects - + See connect and disconnect. Affected by - - - + See connect and disconnect. Exceptional Situations - + See connect and disconnect. See Also - + connect + disconnect + disconnect-pooled + with-default-database Notes - + with-database is a &clsql; extension. - + + + WITH-DEFAULT-DATABASE + - INITIALIZE-DATABASE-TYPE - - Function + Macro WITH-DEFAULT-DATABASE + Execute a body of code with *default-database* bound to a specified database. + Macro Syntax - (INITIALIZE-DATABASE-TYPE &KEY (DATABASE-TYPE *DEFAULT-DATABASE-TYPE*)) [function] => + with-default-database database &rest body => result Arguments and Values - + + database + + An active database object. + + + + + body + + A Lisp code body. + + + + + result + + Determined by the result of executing the last + expression in body. + + + Description - Initializes the supplied DATABASE-TYPE, if it - is not already initialized, as indicated by - *INITIALIZED-DATABASE-TYPES* and returns - DATABASE-TYPE. *DEFAULT-DATABASE-TYPE* is set to - DATABASE-TYPE and, if DATABASE-TYPE has not been - initialised, it is added to - *INITIALIZED-DATABASE-TYPES*. + Perform BODY with DATABASE bound as + *default-database*. Examples - +*default-database* +=> #<CLSQL-ODBC:ODBC-DATABASE new/dent OPEN {49095CAD}> + +(let ((database (clsql:find-database ":memory:"))) + (with-default-database (database) + (database-name *default-database*))) +=> ":memory:" Side Effects - + None. Affected by - - - - - - - Exceptional Situations - - - - - - See Also - - - - - - - - Notes - - - - - - - - - LIST-DATABASES - - Function - - - Syntax - - (LIST-DATABASES CONNECTION-SPEC &KEY DATABASE-TYPE) [function] => - - - Arguments and Values - - - - - - Description - - - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - - - - - Exceptional Situations - - - - - - See Also - - - - - - - - Notes - - - - - - - - - PROBE-DATABASE - - Function - - - Syntax - - (PROBE-DATABASE CONNECTION-SPEC &KEY DATABASE-TYPE) [function] => - - - Arguments and Values - - - - - - Description - - - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - - - - - Exceptional Situations - - - - - - See Also - - - - - - - - Notes - - - - - - - - - RECONNECT - - Function - - - Syntax - - (RECONNECT &KEY (DATABASE *DEFAULT-DATABASE*) (ERROR NIL) (FORCE T)) [function] => - - - Arguments and Values - - - - - - Description - Reconnects DATABASE which defaults to - *DEFAULT-DATABASE* to the underlying database - management system. On success, t is returned and the - variable *DEFAULT-DATABASE* is set to the newly - reconnected database. If DATABASE is a database - instance, this object is closed. If DATABASE is a - string, then a connected database whose name matches - DATABASE is sought in the list of connected - databases. If no matching database is found and ERROR - and DATABASE are both non-nil an error is signaled, - otherwise nil is returned. When the current database - connection cannot be closed, if FORCE is non-nil, as - it is by default, the connection is closed and errors - are suppressed. If force is nil and the database - connection cannot be closed, an error is - signalled. - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - - - - - Exceptional Situations - - - - - - See Also - - - - - - - - Notes - - - - - - - - - STATUS - - Function - - - Syntax - - (STATUS &OPTIONAL FULL) [function] => - - - Arguments and Values - - - - - - Description - Prints information about the currently connected databases to - *STANDARD-OUTPUT*. The argument FULL is nil by default and a - value of t means that more detailed information about each - database is printed. - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - - - - - Exceptional Situations - - - - - - See Also - - - - - - - - Notes - - - - - - - - - TRUNCATE-DATABASE - - Function - - - Syntax - - (TRUNCATE-DATABASE &KEY (DATABASE *DEFAULT-DATABASE*)) [function] => - - - Arguments and Values - - - - - - Description - - - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - - - - - Exceptional Situations - - - - - - See Also - - - - - - - - Notes - - - - - - - - - WITH-DATABASE - - Function - - - Syntax - - (WITH-DATABASE DB-VAR CONNECTION-SPEC &REST CONNECT-ARGS &BODY BODY) [macro] => - - - Arguments and Values - - - - - - Description - Evaluate the body in an environment, where - `db-var' is bound to the database connection given by - `connection-spec' and `connect-args'. The connection - is automatically closed or released to the pool on - exit from the body. - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - - - - - Exceptional Situations - - - - - - See Also - - - - - - - - Notes - - - - - - - - - WITH-DEFAULT-DATABASE - - Function - - - Syntax - - (WITH-DEFAULT-DATABASE DATABASE &REST BODY) [macro] => - - - Arguments and Values - - - - - - Description - Perform BODY with DATABASE bound as - *default-database*. - - - - Examples - - - - - - Side Effects - - - - - - Affected by - - - - + None. Exceptional Situations - + Calls to &clsql; functions in body may signal + errors if database is not an active database + object. See Also - + with-database + *default-database* Notes - + with-default-database is a &clsql; extension.