X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref-connect.xml;h=1e299b949321ef412353e93ab91ed540090218c7;hb=0b757e652eda05d8d824438d925665f17e764d93;hp=e63aae2a84d44e2763372fe43762cb2ab1671dd8;hpb=5edc92aee527621ed13245b5b7892e40c2cd443f;p=clsql.git diff --git a/doc/ref-connect.xml b/doc/ref-connect.xml index e63aae2..1e299b9 100644 --- a/doc/ref-connect.xml +++ b/doc/ref-connect.xml @@ -125,6 +125,61 @@ 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 + + + + + + @@ -371,8 +426,7 @@ 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. @@ -545,8 +605,16 @@ Affected by - *default-database-type* - *connect-if-exists* + + + *default-database-type* + + + + + *connect-if-exists* + + @@ -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* + + @@ -1121,7 +1211,7 @@ 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 @@ -1826,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] @@ -2069,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. @@ -2083,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.