X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=doc%2Fref-connect.xml;h=1e299b949321ef412353e93ab91ed540090218c7;hp=4bc296b3fa843278fd26b9d80963f55a4dec18f5;hb=92cad9a9410b8e481987b90cc4f5edd8cc85e7ce;hpb=528064c179b6b74f0a9d6a43c42e71de3f0e9a3a diff --git a/doc/ref-connect.xml b/doc/ref-connect.xml index 4bc296b..1e299b9 100644 --- a/doc/ref-connect.xml +++ b/doc/ref-connect.xml @@ -22,7 +22,7 @@ DATABASE - Class DATABASE + DATABASE The super-type of all &clsql; databases Class @@ -71,7 +71,7 @@ *CONNECT-IF-EXISTS* - Variable *CONNECT-IF-EXISTS* + *CONNECT-IF-EXISTS* Default value for the if-exists parameter of connect. @@ -80,7 +80,7 @@ Value Type A valid argument to the if-exists - parameter of connect, i.e. one of + parameter of connect, that is, one of :new :warn-new @@ -125,24 +125,79 @@ None. + + + *DB-POOL-MAX-FREE-CONNECTIONS* + + + *DB-POOL-MAX-FREE-CONNECTIONS* + How many free connections should the connection pool try to keep. + Parameter + + + Value Type + Integer + + + Initial Value + 4 + + + Description + Threshold of free-connections in the pool before we + disconnect a database rather than returning it to the pool. NIL for + no limit. This is really a heuristic that should, on avg keep the + free connections about this size. + + This is not a hard limit, the number of connections in + the pool may exceed this value. + + + + Examples + + (setf clsql-sys:*db-pool-max-free-connections* 2) + + + + Affected By + None + + + See Also + + + connect + disconnect + + + + + Notes + + + + + + *DEFAULT-DATABASE* - Variable *DEFAULT-DATABASE* + *DEFAULT-DATABASE* The default database object to use. Variable Value Type - Any object of type database, or nil to + Any object of type database, or &nil; to indicate no default database. Initial Value - nil + &nil; Description @@ -160,13 +215,13 @@ *default-database* to the first database that remains in the list of active databases as returned by connected-databases, or - nil if no further active databases + &nil; if no further active databases exist. The user may change *default-database* 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 + &nil;, then all calls to &clsql; functions on databases must provide a suitable database parameter, or an error will be signalled. @@ -241,18 +296,18 @@ *DEFAULT-DATABASE-TYPE* - Variable *DEFAULT-DATABASE-TYPE* + *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 - nil + &nil; Description @@ -261,7 +316,7 @@ connect as the default value of the database-type parameter. - If the value of this variable is nil, + If the value of this variable is &nil;, then all calls to initialize-database-type or connect will have to specify the @@ -300,7 +355,7 @@ *INITIALIZED-DATABASE-TYPES* - Variable *INITIALIZED-DATABASE-TYPES* + *INITIALIZED-DATABASE-TYPES* List of all initialized database types Variable @@ -311,7 +366,7 @@ Initial Value - nil + &nil; Description @@ -365,14 +420,13 @@ CONNECT - Function CONNECT + CONNECT create a connection to a database. Function Syntax - Syntax - connect connection-spec &key if-exists database-type pool make-default => database + connect connection-spec &key if-exists database-type pool make-default => database Arguments and Values @@ -380,8 +434,14 @@ connection-spec - A vendor specific connection specification supplied - as a list or as a string. + 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. @@ -406,8 +466,7 @@ 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. + connection is created. The default is &nil;. @@ -417,8 +476,7 @@ 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. + is not changed. The default is &t;. @@ -547,8 +605,16 @@ Affected by - *default-database-type* - *connect-if-exists* + + + *default-database-type* + + + + + *connect-if-exists* + + @@ -580,7 +646,9 @@ Notes - None. + The pool and + make-default keyword arguments to + connect are &clsql; extensions. @@ -589,7 +657,7 @@ CONNECTED-DATABASES - Function CONNECTED-DATABASES + CONNECTED-DATABASES Return the list of active database objects. Function @@ -681,7 +749,7 @@ DATABASE-NAME - Generic Function DATABASE-NAME + DATABASE-NAME Get the name of a database object Generic Function @@ -798,7 +866,7 @@ DATABASE-NAME-FROM-SPEC - Generic Function DATABASE-NAME-FROM-SPEC + DATABASE-NAME-FROM-SPEC Return the database name string corresponding to the given connection specification. Generic Function @@ -911,7 +979,7 @@ DATABASE-TYPE - Generic Function DATABASE-TYPE + DATABASE-TYPE Get the type of a database object. Generic Function @@ -1000,7 +1068,7 @@ DISCONNECT - Function DISCONNECT + DISCONNECT close a database connection Function @@ -1015,7 +1083,7 @@ error A boolean flag indicating whether to signal an error - if database is non-nil but cannot + if database is non-&nil; but cannot be found. @@ -1044,8 +1112,8 @@ 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 + 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. @@ -1067,24 +1135,46 @@ 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. + The database object is removed from the list of connected databases as + returned by connected-databases. 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. + 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. + + Non-pooled + The database connection is closed and the state of the + database object is changed to closed. + + + Pooled + Unless there are already + *db-pool-max-free-connections* + free connections in the pool it is returned to the + pool, with the backend having an opportunity to run + generic cleanup on the connection first. If the max free + connections has already been reached then it is + disconnected as if it were not in the pool. + + Affected by - *default-database* + + + *default-database* + + + + + *db-pool-max-free-connections* + + @@ -1115,13 +1205,13 @@ DISCONNECT-POOLED - Function DISCONNECT-POOLED + DISCONNECT-POOLED closes all pooled database connections Function Syntax - disconnect-pooled => t + disconnect-pooled &optional clear => t Description @@ -1130,6 +1220,8 @@ linkend="connect">connect with :pool &t;. + If optional argument clear is non-&nil; + then the connection-pool objects are also removed. Examples @@ -1140,8 +1232,10 @@ Side Effects - Database connections will be closed and entries in the pool are removed. - + Database connections will be closed and *all* entries in + the pool are removed. This is done with great prejudice and no + thought to thread safety or whether that connection is + currently in use. Affected by @@ -1179,7 +1273,7 @@ FIND-DATABASE - Function FIND-DATABASE + FIND-DATABASE >Locate a database object through it's name. Function @@ -1209,8 +1303,7 @@ db-type - A keyword symbol denoting a known database back-end. This - is a &clsql; extension. + A keyword symbol denoting a known database back-end. @@ -1218,8 +1311,8 @@ result Either a database object, or, if - errorp is nil, - possibly nil. + errorp is &nil;, + possibly &nil;. @@ -1240,11 +1333,11 @@ database. If it succeeds, it returns the first database found. - If db-type is nil all databases + 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 + 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 @@ -1321,7 +1414,9 @@ Notes - None. + The db-type keyword argument to + find-database is a &clsql; + extension. @@ -1330,7 +1425,7 @@ INITIALIZE-DATABASE-TYPE - Function INITIALIZE-DATABASE-TYPE + INITIALIZE-DATABASE-TYPE Initializes a database type Function @@ -1354,7 +1449,7 @@ result - Either nil if the initialization + Either &nil; if the initialization attempt fails, or t otherwise. @@ -1373,7 +1468,7 @@ *initialized-database-types*, if not already present. If initialization fails, the function returns - nil, and/or signals an error of type + &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. @@ -1444,7 +1539,7 @@ RECONNECT - Function RECONNECT + RECONNECT Re-establishes the connection between a database object and its RDBMS. Function @@ -1503,13 +1598,13 @@ 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. + 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 + 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 + force is &nil; and the database connection cannot be closed, an error is signalled. @@ -1569,7 +1664,7 @@ STATUS - Function STATUS + STATUS Print information about connected databases. Function @@ -1595,7 +1690,7 @@ Description Prints information about the currently connected databases to *STANDARD-OUTPUT*. The argument - full is nil by default and a value of t + full is &nil; by default and a value of t means that more detailed information about each database is printed. @@ -1612,7 +1707,7 @@ CLSQL STATUS: 2004-06-13 15:07:39 localhost/test/petrov mysql nil localhost/test/petrov postgresql nil localhost/test/petrov postgresql-socket nil - mysql-test/petrov odbc nil + test/petrov odbc nil * :memory: sqlite nil -------------------------------------------------------- @@ -1676,7 +1771,7 @@ CLSQL STATUS: 2004-06-13 15:08:08 CREATE-DATABASE - Function CREATE-DATABASE + CREATE-DATABASE create a database Function @@ -1774,7 +1869,7 @@ error: 'Access denied for user: 'root@localhost' (Using password: YES)' DESTROY-DATABASE - Function DESTROY-DATABASE + DESTROY-DATABASE destroys a database Function @@ -1825,7 +1920,7 @@ error: 'Access denied for user: 'root@localhost' (Using password: YES)' => 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 + Error database-destroy failed: dropdb: database removal failed: ERROR: database "test2" does not exist has occurred. [condition type: CLSQL-ACCESS-ERROR] @@ -1871,7 +1966,7 @@ Error: While trying to access database localhost/test2/root PROBE-DATABASE - Function PROBE-DATABASE + PROBE-DATABASE tests for existence of a database Function @@ -1954,7 +2049,7 @@ Error: While trying to access database localhost/test2/root LIST-DATABASES - Function LIST-DATABASES + LIST-DATABASES List databases matching the supplied connection spec and database type. Function @@ -2052,7 +2147,7 @@ Error: While trying to access database localhost/test2/root WITH-DATABASE - Macro WITH-DATABASE + WITH-DATABASE Execute a body of code with a variable bound to a specified database object. Macro @@ -2068,7 +2163,7 @@ Error: While trying to access database localhost/test2/root db-var - A variable to which the specified database is bound. + A variable which is bound to the specified database. @@ -2082,7 +2177,12 @@ Error: While trying to access database localhost/test2/root connect-args - Other optional arguments to connect. + Other optional arguments to + connect. This macro use a value of + &nil; for connect's + make-default key, This is in + contrast to to the connect function which has a default + value of &t; for make-default. @@ -2168,7 +2268,7 @@ Error: While trying to access database localhost/test2/root WITH-DEFAULT-DATABASE - Macro WITH-DEFAULT-DATABASE + WITH-DEFAULT-DATABASE Execute a body of code with *default-database* bound to a specified database. Macro @@ -2206,8 +2306,9 @@ Error: While trying to access database localhost/test2/root Description - Perform BODY with DATABASE bound as - *default-database*. + Perform body with + DATABASE bound as + *default-database*.