X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=doc%2Fref_clsql.xml;h=0d893a6208866732ed023058d1422be9d234c23a;hp=4d1c9d510c9eee29a25b620e37e6b4165a4a6ada;hb=fa32c4233b4a02ae631602dbb0a234ab10df8aaf;hpb=4acd394aa304abb683270f8ce6979e7efc423e23 diff --git a/doc/ref_clsql.xml b/doc/ref_clsql.xml index 4d1c9d5..0d893a6 100644 --- a/doc/ref_clsql.xml +++ b/doc/ref_clsql.xml @@ -1650,6 +1650,237 @@ The default is &nil;. + + + 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. + + + 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. + + + + + + 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 destroy 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. + + + 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. + + + + + + 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 + None. + + + DATABASE-NAME-FROM-SPEC @@ -1868,7 +2099,7 @@ The default is &nil;. Syntax - query query-expression &key database types => result + query query-expression &key database result-types => result Arguments and Values @@ -1892,11 +2123,11 @@ The default is &nil;. - types + result-types A field type - specififier. The default is &nil;. + specifier. The default is &nil;. The purpose of this argument is cause &clsql; to @@ -2019,7 +2250,7 @@ The default is &nil;. Syntax - map-query output-type-spec function query-expression &key database types => result + map-query output-type-spec function query-expression &key database result-types => result Arguments and Values @@ -2060,10 +2291,10 @@ The default is &nil;. - types + result-types - A field type specififier. + A field type specifier. The default is &nil;. See query for the semantics of this argument. @@ -2190,7 +2421,7 @@ The default is &nil;. Syntax - do-query ((&rest args) query-expression &key database types) &body body => nil + do-query ((&rest args) query-expression &key database result-types) &body body => nil Arguments and Values @@ -2221,10 +2452,10 @@ The default is &nil;. - types + result-types - A field type specififier. + A field type specifier. The default is &nil;. See query for the semantics of this argument.