X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=doc%2Fappendix.xml;h=f06f035edfd4915831a7004018c66e278f0f6f46;hp=ad2f4ef8961a2e7f48dca30f8f0663a58fe5c8a3;hb=92cad9a9410b8e481987b90cc4f5edd8cc85e7ce;hpb=f7a356bb4c11d062eeeb5d4aaf4e187a3cb15a27 diff --git a/doc/appendix.xml b/doc/appendix.xml index ad2f4ef..f06f035 100644 --- a/doc/appendix.xml +++ b/doc/appendix.xml @@ -7,14 +7,53 @@ Database Back-ends - - - PostgreSQL - - Libraries - The PostgreSQL back-end requires the PostgreSQL C - client library (libpq.so). The - location of this library is specified via + + + How CLSQL finds and loads foreign libraries + + For some database types CLSQL has to load external foreign + libaries. These are usually searched for in the standard + locations the operating system uses but you can tell &clsql; to + look into other directories as well by using the function + CLSQL:PUSH-LIBRARY-PATH or by directly + manipulating the special variable + CLSQL:*FOREIGN-LIBRARY-SEARCH-PATHS*. If, + say, the shared library libpq.so needed for PostgreSQL support + is located in the directory /opt/foo/ on + your machine you'd use + + (clsql:push-library-path "/opt/foo/") + + before loading the CLSQL-POSTGRESQL module. (Note the trailing + slash above!) + + If you want to combine this with fully automatic loading of + libraries via ASDF a technique like the following works: + + + (defmethod asdf:perform :after ((o asdf:load-op) + (c (eql (asdf:find-system 'clsql)))) + (funcall (find-symbol (symbol-name '#:push-library-path) + (find-package 'clsql)) + #p"/opt/foo/")) + + + + + Additionally, site-specific initialization can be done using an +initialization file. If the file /etc/clsql-init.lisp +exists, this file will be read after the &clsql; ASDF system is loaded. +This file can contain forms to set site-specific paths as well as change +&clsql; default values. + + + + PostgreSQL + + Libraries + The PostgreSQL back-end requires the PostgreSQL C + client library (libpq.so). The + location of this library is specified via *postgresql-so-load-path*, which defaults to /usr/lib/libpq.so. Additional flags to ld needed for linking are @@ -240,7 +279,7 @@ Connection Specification Syntax of connection-spec - (host db user password) + (host db user password &optional port) Description of connection-spec @@ -277,6 +316,13 @@ field. + + port + + String representing the port to use for + communication with the MySQL server. + + @@ -392,7 +438,7 @@ Connection Specification Syntax of connection-spec - (dsn user password) + (dsn user password &key connection-string) Description of connection-spec @@ -417,6 +463,15 @@ use for authentication. + + connection-string + + Raw connection string passed to the underlying + ODBC driver. Allows bypassing creating a DSN on the + server. + + + @@ -432,6 +487,26 @@ + Connect Examples + + +;; assumes a "mssql" DSN is configured on the lisp host, specifying database server +;; and database name. +> (clsql:connect '("mssql" "database-user" "database-password") + :database-type :odbc) +=> #<CLSQL-ODBC:ODBC-DATABASE mssql/database-user OPEN {100756D123}> + +;; no DSN on the lisp host, specify connection information via :connection-string +> (clsql:connect '("friendly-server-name" "friendly-username" "" + :connection-string "DRIVER={FreeTDS};SERVER=mssql-server;DATABASE=database-name;UID=database-user;PWD=database-password;PORT=1433;TDS_Version=8.0;APP=clsql") + :database-type :odbc) +=> #<CLSQL-ODBC:ODBC-DATABASE friendly-server-name/friendly-username OPEN {100756D123}> + + The friendly-server-name + and friendly-username are only used when + printing the connection object to a stream. + + @@ -525,8 +600,8 @@ filename - String representing the filename of the &sqlite; - database file. + String or pathname representing the filename of + the &sqlite; database file. @@ -583,6 +658,118 @@ + + &sqlite3; + + Libraries The &sqlite3; back-end requires + the &sqlite3; shared library file. Its default file name is + /usr/lib/libsqlite3.so. + + + Initialization + + Use + +(asdf:operate 'asdf:load-op 'clsql-sqlite3) + + to load the &sqlite3; back-end. The database type for the &sqlite3; + back-end is :sqlite3. + + + + Connection Specification + + Syntax of connection-spec + (filename &optional init-function) + + + Description of connection-spec + + + filename + + String representing the filename of the &sqlite3; + database file. + + + + init-function + + + A function designator. + init-function takes a + single argument of type + sqlite3:sqlite3-db, a foreign pointer to + the C descriptor of the newly opened database. + init-function is called by + the back-end immediately after &sqlite3; + sqlite3_open library function, + and can be used to perform optional database + initializations by calling foreign functions in the + &sqlite3; library. + + + An example of an initialization function which + defines a new collating sequence for text columns is + provided in + ./examples/sqlite3/init-func/. + + + + + + + Notes + Connection + + + + Passing filename a value of + :memory: will create a database in + physical memory instead of using a file on disk. + + + + + Some operations will be many times faster if database + integrity checking is disabled by setting the SYNCHRONOUS + flag to OFF (see the SQLITE manual for details). + + + + + FDDL + + + + The :owner keyword argument to the FDDL functions + for listing and testing for database objects is ignored. + + + + + The :column-list keyword argument to + create-view + is not supported by &sqlite3;. + + + + + Symbolic SQL Syntax + + + + &sqlite3; does not support the all, + some, any and + exists subquery operations. + + + + + + + Oracle @@ -591,9 +778,23 @@ library. (libclntsh.so). The location of this library is specified relative to the ORACLE_HOME value in the operating system - environment. &clsql; has tested sucessfully using the client - library from Oracle 9i and Oracle 10g server installations as - well as Oracle's 10g Instant Client library. + environment. + + + + Library Versions + + &clsql; has tested sucessfully using the client library from + Oracle 9i and Oracle 10g server installations as well as + Oracle's 10g Instant Client library. For Oracle 8 and earlier + versions, there is vestigial support by pushing the symbol + :oci7 onto cl:*features* + prior to loading the clsql-oracle &asdf; + system. + + (push :oci7 cl:*features*) + (asdf:operate 'asdf:load-op 'clsql-oracle) +