X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref-connect.xml;h=c3879b22ea71be587c2c315eed3d1fe1cc4d0dc2;hb=4871b9ef13ed1cf4f7ef927bd026ca19e845f53c;hp=4bc296b3fa843278fd26b9d80963f55a4dec18f5;hpb=528064c179b6b74f0a9d6a43c42e71de3f0e9a3a;p=clsql.git
diff --git a/doc/ref-connect.xml b/doc/ref-connect.xml
index 4bc296b..c3879b2 100644
--- a/doc/ref-connect.xml
+++ b/doc/ref-connect.xml
@@ -22,7 +22,7 @@
DATABASE
- ClassDATABASE
+ DATABASEThe super-type of all &clsql; databasesClass
@@ -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 TypeA 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,78 @@
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. 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.VariableValue 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 +214,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 +295,18 @@
*DEFAULT-DATABASE-TYPE*
- Variable*DEFAULT-DATABASE-TYPE*
+ *DEFAULT-DATABASE-TYPE*The default database type to useVariableValue TypeAny keyword representing a valid database back-end of
- &clsql;, or nil.
+ &clsql;, or &nil;.
Initial Value
- nil
+ &nil;Description
@@ -261,7 +315,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 +354,7 @@
*INITIALIZED-DATABASE-TYPES*
- Variable*INITIALIZED-DATABASE-TYPES*
+ *INITIALIZED-DATABASE-TYPES*List of all initialized database typesVariable
@@ -311,7 +365,7 @@
Initial Value
- nil
+ &nil;Description
@@ -365,14 +419,13 @@
CONNECT
- FunctionCONNECT
+ CONNECTcreate a connection to a database.FunctionSyntax
- Syntax
- connectconnection-spec &key if-existsdatabase-typepoolmake-default => database
+ connectconnection-spec &key if-existsdatabase-typepoolmake-default => databaseArguments and Values
@@ -380,8 +433,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 +465,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 +475,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 +604,16 @@
Affected by
- *default-database-type*
- *connect-if-exists*
+
+
+ *default-database-type*
+
+
+
+
+ *connect-if-exists*
+
+
@@ -580,7 +645,9 @@
Notes
- None.
+ The pool and
+ make-default keyword arguments to
+ connect are &clsql; extensions.
@@ -589,7 +656,7 @@
CONNECTED-DATABASES
- FunctionCONNECTED-DATABASES
+ CONNECTED-DATABASESReturn the list of active database objects.Function
@@ -681,7 +748,7 @@
DATABASE-NAME
- Generic FunctionDATABASE-NAME
+ DATABASE-NAMEGet the name of a database objectGeneric Function
@@ -798,7 +865,7 @@
DATABASE-NAME-FROM-SPEC
- Generic FunctionDATABASE-NAME-FROM-SPEC
+ DATABASE-NAME-FROM-SPECReturn the database name string corresponding to
the given connection specification.Generic Function
@@ -911,7 +978,7 @@
DATABASE-TYPE
- Generic FunctionDATABASE-TYPE
+ DATABASE-TYPEGet the type of a database object.Generic Function
@@ -1000,7 +1067,7 @@
DISCONNECT
- FunctionDISCONNECT
+ DISCONNECTclose a database connectionFunction
@@ -1015,7 +1082,7 @@
errorA 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 +1111,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 +1134,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 +1204,13 @@
DISCONNECT-POOLED
- FunctionDISCONNECT-POOLED
+ DISCONNECT-POOLEDcloses all pooled database connectionsFunctionSyntax
- disconnect-pooled => t
+ disconnect-pooled &optional clear => tDescription
@@ -1130,6 +1219,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 +1231,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 +1272,7 @@
FIND-DATABASE
- FunctionFIND-DATABASE
+ FIND-DATABASE>Locate a database object through it's
name.Function
@@ -1209,8 +1302,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 +1310,8 @@
resultEither a database object, or, if
- errorp is nil,
- possibly nil.
+ errorp is &nil;,
+ possibly &nil;.
@@ -1240,11 +1332,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 +1413,9 @@
Notes
- None.
+ The db-type keyword argument to
+ find-database is a &clsql;
+ extension.
@@ -1330,7 +1424,7 @@
INITIALIZE-DATABASE-TYPE
- FunctionINITIALIZE-DATABASE-TYPE
+ INITIALIZE-DATABASE-TYPEInitializes a database typeFunction
@@ -1354,7 +1448,7 @@
result
- Either nil if the initialization
+ Either &nil; if the initialization
attempt fails, or t otherwise.
@@ -1373,7 +1467,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 +1538,7 @@
RECONNECT
- FunctionRECONNECT
+ RECONNECTRe-establishes the connection between a database object and its RDBMS.Function
@@ -1503,13 +1597,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 +1663,7 @@
STATUS
- FunctionSTATUS
+ STATUSPrint information about connected databases.Function
@@ -1595,7 +1689,7 @@
DescriptionPrints 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 +1706,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 +1770,7 @@ CLSQL STATUS: 2004-06-13 15:08:08
CREATE-DATABASE
- FunctionCREATE-DATABASE
+ CREATE-DATABASEcreate a databaseFunction
@@ -1774,7 +1868,7 @@ error: 'Access denied for user: 'root@localhost' (Using password: YES)'
DESTROY-DATABASE
- FunctionDESTROY-DATABASE
+ DESTROY-DATABASEdestroys a databaseFunction
@@ -1825,7 +1919,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 +1965,7 @@ Error: While trying to access database localhost/test2/root
PROBE-DATABASE
- FunctionPROBE-DATABASE
+ PROBE-DATABASEtests for existence of a databaseFunction
@@ -1954,7 +2048,7 @@ Error: While trying to access database localhost/test2/root
LIST-DATABASES
- FunctionLIST-DATABASES
+ LIST-DATABASESList databases matching the supplied connection spec
and database type.Function
@@ -2052,7 +2146,7 @@ Error: While trying to access database localhost/test2/root
WITH-DATABASE
- MacroWITH-DATABASE
+ WITH-DATABASEExecute a body of code with a variable bound to a
specified database object.Macro
@@ -2068,7 +2162,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 +2176,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 +2267,7 @@ Error: While trying to access database localhost/test2/root
WITH-DEFAULT-DATABASE
- MacroWITH-DEFAULT-DATABASE
+ WITH-DEFAULT-DATABASEExecute a body of code with *default-database* bound to a specified database.Macro
@@ -2206,8 +2305,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*.