Abstract
CL-SQLITE package is an interface to the SQLite embedded relational database engine.
The code is in public domain so you can basically do with it whatever you want.
This documentation describes only the CL-SQLITE package, not the SQLite database itself. SQLite documentation is available at http://sqlite.org/docs.html
CL-SQLITE together with this documentation can be downloaded from http://common-lisp.net/project/cl-sqlite/releases/cl-sqlite-0.1.5.tar.gz.
CL-SQLITE source code is available in Git repository at http://repo.or.cz/w/cl-sqlite.git.
The package can be downloaded from http://common-lisp.net/project/cl-sqlite/releases/cl-sqlite-0.1.5.tar.gz. CL-SQLITE package has the following dependencies:
SQLITE has a system definition for ASDF. Compile and load it in the usual way.
(use-package :sqlite) (use-package :iter) (defvar *db* (connect ":memory:")) ;;Connect to the sqlite database. :memory: is the temporary in-memory database (execute-non-query *db* "create table users (id integer primary key, user_name text not null, age integer null)") ;;Create the table (execute-non-query *db* "insert into users (user_name, age) values (?, ?)" "joe" 18) (execute-non-query *db* "insert into users (user_name, age) values (?, ?)" "dvk" 22) (execute-non-query *db* "insert into users (user_name, age) values (?, ?)" "qwe" 30) (execute-non-query *db* "insert into users (user_name, age) values (?, ?)" nil nil) ;; ERROR: constraint failed (execute-single *db* "select id from users where user_name = ?" "dvk") ;; => 2 (execute-one-row-m-v *db* "select id, user_name, age from users where user_name = ?" "joe") ;; => (values 1 "joe" 18) (execute-to-list *db* "select id, user_name, age from users") ;; => ((1 "joe" 18) (2 "dvk" 22) (3 "qwe" 30)) ;; Use iterate (iter (for (id user-name age) in-sqlite-query "select id, user_name, age from users where age < ?" on-database *db* with-parameters (25)) (collect (list id user-name age))) ;; => ((1 "joe" 18) (2 "dvk" 22)) ;; Use prepared statements directly (loop with statement = (prepare-statement *db* "select id, user_name, age from users where age < ?") initially (bind-parameter statement 1 25) while (step-statement statement) collect (list (statement-column-value statement 0) (statement-column-value statement 1) (statement-column-value statement 2)) finally (finalize-statement statement)) ;; => ((1 "joe" 18) (2 "dvk" 22)) (disconnect *db*) ;;Disconnect
Two functions and a macro are used to manage connections to the database:
To make queries to the database the following functions are provided:
Macro with-transaction is used to execute code within transaction.
Support for ITERATE is provided. Use the following clause:
This clause will bind vars (a list of variables) to the values of the columns of query.(for (vars) in-sqlite-query sql on-database db &optional with-parameters (&rest parameters))
Additionally, it is possible to use the prepared statements API of sqlite. Create the prepared statement with prepare-statement, bind its parameters with bind-parameter, step through it with step-statement, retrieve the results with statement-column-value, and finally reset it to be used again with reset-statement or dispose of it with finalize-statement.
Positional parameters in queries are supported (sqlite supports named parameters but this package does not support them). Parameters are denoted by question mark in SQL code.
Following types are supported:
[Function]
bind-parameter statement parameter value
Sets the parameter-th parameter in statement to the value.
Parameters are numbered from one.
Supported types:
- Null. Passed as NULL
- Integer. Passed as an 64-bit integer
- String. Passed as a string
- Float. Passed as a double
- (vector (unsigned-byte 8)) and vector that contains integers in range [0,256). Passed as a BLOB
[Function]
connect database-path => sqlite-handle
Connect to the sqlite database at the given database-path (database-path is a string or a pathname). If database-path equal to":memory:"is given, a new in-memory database is created. Returns the sqlite-handle connected to the database. Use disconnect to disconnect.
[Function]
disconnect handle
Disconnects the given handle from the database. All further operations on the handle and on prepared statements (including freeing handle or statements) are invalid and will lead to memory corruption.
[Function]
execute-non-query db sql &rest parameters
Executes the query sql to the database db with given parameters. Returns nothing.
Example:
(execute-non-query db "insert into users (user_name, real_name) values (?, ?)" "joe" "Joe the User")See bind-parameter for the list of supported parameter types.
[Function]
execute-one-row-m-v db sql &rest parameters => (values result*)
Executes the query sql to the database db with given parameters. Returns the first row as multiple values.
Example:
(execute-one-row-m-v db "select id, user_name, real_name from users where id = ?" 1) => (values 1 "joe" "Joe the User")See bind-parameter for the list of supported parameter types.
[Function]
execute-single db sql &rest parameters => result
Executes the query sql to the database db with given parameters. Returns the first column of the first row as single value.
Example:
(execute-single db "select user_name from users where id = ?" 1) => "joe"See bind-parameter for the list of supported parameter types.
[Function]
execute-to-list db sql &rest parameters => results
Executes the query sql to the database db with given parameters. Returns the results as list of lists.
Example:
(execute-to-list db "select id, user_name, real_name from users where user_name = ?" "joe") => ((1 "joe" "Joe the User") (2 "joe" "Another Joe"))See bind-parameter for the list of supported parameter types.
[Function]
finalize-statement statement
Finalizes the statement and signals that associated resources may be released.
Note: does not immediately release resources because statements are cached.
[Function]
last-insert-rowid db => result
Returns the auto-generated ID of the last inserted row on the database connection db.
[Function]
prepare-statement db sql => sqlite-statement
Prepare the statement to the DB that will execute the commands that are in sql.
Returns the sqlite-statement.
sql must contain exactly one statement.
sql may have some positional (not named) parameters specified with question marks.
Example:
(prepare-statement db "select name from users where id = ?")
[Function]
reset-statement statement
Resets the statement and prepare it to be called again.
[Standard class]
sqlite-handle
Class that encapsulates the connection to the database.
[Standard class]
sqlite-statement
Class that represents the prepared statement.
[Function]
statement-column-value statement column-number => result
Returns the column-number-th column's value of the current row of the statement. Columns are numbered from zero.
Returns:
- NIL for NULL
- integer for integers
- double-float for floats
- string for text
- (simple-array (unsigned-byte 8)) for BLOBs
[Function]
step-statement statement => boolean
Steps to the next row of the resultset of statement.
Returns T is successfully advanced to the next row and NIL if there are no more rows.
[Macro]
with-transaction db &body body
Wraps the body inside the transaction. If body evaluates without error, transaction is commited. If evaluation of body is interrupted, transaction is rolled back.
[Macro]
with-open-database (db path) &body body
Executes the body with db being bound to the database handle for database located at path. Database is open before the body is run and it is ensured that database is closed after the evaluation of body finished or interrupted.
This documentation was prepared with DOCUMENTATION-TEMPLATE.
$Header: /usr/local/cvsrep/documentation-template/output.lisp,v 1.14 2008/05/29 08:23:37 edi Exp $