├── sqlite-tests.asd ├── sqlite.asd ├── style.css ├── cache.lisp ├── sqlite-ffi.lisp ├── sqlite-tests.lisp ├── sqlite.lisp └── index.html /sqlite-tests.asd: -------------------------------------------------------------------------------- 1 | (defsystem :sqlite-tests 2 | :name "sqlite-tests" 3 | :author "Kalyanov Dmitry " 4 | :maintainer "Jacek Złydach " 5 | :description "Tests for CL-SQLITE, an interface to the SQLite embedded relational database engine." 6 | :homepage "https://common-lisp.net/project/cl-sqlite/" 7 | :source-control (:git "git@github.com:TeMPOraL/cl-sqlite.git") 8 | :bug-tracker "https://github.com/TeMPOraL/cl-sqlite/issues" 9 | :version "0.2.1" 10 | :license "Public Domain" 11 | 12 | :components ((:file "sqlite-tests")) 13 | 14 | :depends-on (:fiveam :sqlite :bordeaux-threads)) 15 | -------------------------------------------------------------------------------- /sqlite.asd: -------------------------------------------------------------------------------- 1 | (defsystem :sqlite 2 | :name "sqlite" 3 | :author "Kalyanov Dmitry " 4 | :maintainer "Jacek Złydach " 5 | :description "CL-SQLITE package is an interface to the SQLite embedded relational database engine." 6 | :homepage "https://common-lisp.net/project/cl-sqlite/" 7 | :source-control (:git "git@github.com:TeMPOraL/cl-sqlite.git") 8 | :bug-tracker "https://github.com/TeMPOraL/cl-sqlite/issues" 9 | :version "0.2.1" 10 | :license "Public Domain" 11 | 12 | :components ((:file "sqlite-ffi") 13 | (:file "cache") 14 | (:file "sqlite" :depends-on ("sqlite-ffi" "cache"))) 15 | 16 | :depends-on (:iterate :cffi) 17 | 18 | :in-order-to ((test-op (load-op sqlite-tests)))) 19 | 20 | (defmethod perform ((o asdf:test-op) (c (eql (find-system :sqlite)))) 21 | (funcall (intern "RUN-ALL-SQLITE-TESTS" :sqlite-tests))) 22 | -------------------------------------------------------------------------------- /style.css: -------------------------------------------------------------------------------- 1 | 2 | .header { 3 | font-size: medium; 4 | background-color:#336699; 5 | color:#ffffff; 6 | border-style:solid; 7 | border-width: 5px; 8 | border-color:#002244; 9 | padding: 1mm 1mm 1mm 5mm; 10 | } 11 | 12 | .footer { 13 | font-size: small; 14 | font-style: italic; 15 | text-align: right; 16 | background-color:#336699; 17 | color:#ffffff; 18 | border-style:solid; 19 | border-width: 2px; 20 | border-color:#002244; 21 | padding: 1mm 1mm 1mm 1mm; 22 | } 23 | 24 | .footer a:link { 25 | font-weight:bold; 26 | color:#ffffff; 27 | text-decoration:underline; 28 | } 29 | 30 | .footer a:visited { 31 | font-weight:bold; 32 | color:#ffffff; 33 | text-decoration:underline; 34 | } 35 | 36 | .footer a:hover { 37 | font-weight:bold; 38 | color:#002244; 39 | text-decoration:underline; } 40 | 41 | .check {font-size: x-small; 42 | text-align:right;} 43 | 44 | .check a:link { font-weight:bold; 45 | color:#a0a0ff; 46 | text-decoration:underline; } 47 | 48 | .check a:visited { font-weight:bold; 49 | color:#a0a0ff; 50 | text-decoration:underline; } 51 | 52 | .check a:hover { font-weight:bold; 53 | color:#000000; 54 | text-decoration:underline; } 55 | -------------------------------------------------------------------------------- /cache.lisp: -------------------------------------------------------------------------------- 1 | (defpackage :sqlite.cache 2 | (:use :cl :iter) 3 | (:export :mru-cache 4 | :get-from-cache 5 | :put-to-cache 6 | :purge-cache)) 7 | 8 | (in-package :sqlite.cache) 9 | 10 | ;(declaim (optimize (speed 3) (safety 0) (debug 0))) 11 | 12 | (defclass mru-cache () 13 | ((objects-table :accessor objects-table :initform (make-hash-table :test 'equal)) 14 | (last-access-time-table :accessor last-access-time-table :initform (make-hash-table :test 'equal)) 15 | (total-cached :type fixnum :accessor total-cached :initform 0) 16 | (cache-size :type fixnum :accessor cache-size :initarg :cache-size :initform 100) 17 | (destructor :accessor destructor :initarg :destructor :initform #'identity))) 18 | 19 | (defun get-from-cache (cache id) 20 | (let ((available-objects-stack (gethash id (objects-table cache)))) 21 | (when (and available-objects-stack (> (length (the vector available-objects-stack)) 0)) 22 | (decf (the fixnum (total-cached cache))) 23 | (setf (gethash id (last-access-time-table cache)) (get-internal-run-time)) 24 | (vector-pop (the vector available-objects-stack))))) 25 | 26 | (defun remove-empty-objects-stacks (cache) 27 | (let ((table (objects-table cache))) 28 | (maphash (lambda (key value) 29 | (declare (type vector value)) 30 | (when (zerop (length value)) 31 | (remhash key table) 32 | (remhash key (last-access-time-table cache)))) 33 | table))) 34 | 35 | (defun pop-from-cache (cache) 36 | (let ((id (iter (for (id time) in-hashtable (last-access-time-table cache)) 37 | (when (not (zerop (length (the vector (gethash id (objects-table cache)))))) 38 | (finding id minimizing (the fixnum time)))))) 39 | (let ((object (vector-pop (gethash id (objects-table cache))))) 40 | (funcall (destructor cache) object))) 41 | (remove-empty-objects-stacks cache) 42 | (decf (the fixnum (total-cached cache)))) 43 | 44 | (defun put-to-cache (cache id object) 45 | (when (>= (the fixnum (total-cached cache)) (the fixnum (cache-size cache))) 46 | (pop-from-cache cache)) 47 | (let ((available-objects-stack (or (gethash id (objects-table cache)) 48 | (setf (gethash id (objects-table cache)) (make-array 0 :adjustable t :fill-pointer t))))) 49 | (vector-push-extend object available-objects-stack) 50 | (setf (gethash id (last-access-time-table cache)) (get-internal-run-time)) 51 | (incf (the fixnum (total-cached cache))) 52 | object)) 53 | 54 | (defun purge-cache (cache) 55 | (iter (for (id items) in-hashtable (objects-table cache)) 56 | (declare (ignorable id)) 57 | (when items 58 | (iter (for item in-vector (the vector items)) 59 | (funcall (destructor cache) item))))) -------------------------------------------------------------------------------- /sqlite-ffi.lisp: -------------------------------------------------------------------------------- 1 | (defpackage :sqlite-ffi 2 | (:use :cl :cffi) 3 | (:export :error-code 4 | :p-sqlite3 5 | :sqlite3-open 6 | :sqlite3-close 7 | :sqlite3-errmsg 8 | :sqlite3-busy-timeout 9 | :p-sqlite3-stmt 10 | :sqlite3-prepare 11 | :sqlite3-finalize 12 | :sqlite3-step 13 | :sqlite3-reset 14 | :sqlite3-clear-bindings 15 | :sqlite3-column-count 16 | :sqlite3-column-type 17 | :sqlite3-column-text 18 | :sqlite3-column-int64 19 | :sqlite3-column-double 20 | :sqlite3-column-bytes 21 | :sqlite3-column-blob 22 | :sqlite3-column-name 23 | :sqlite3-bind-parameter-count 24 | :sqlite3-bind-parameter-name 25 | :sqlite3-bind-parameter-index 26 | :sqlite3-bind-double 27 | :sqlite3-bind-int64 28 | :sqlite3-bind-null 29 | :sqlite3-bind-text 30 | :sqlite3-bind-blob 31 | :destructor-transient 32 | :destructor-static 33 | :sqlite3-last-insert-rowid)) 34 | 35 | (in-package :sqlite-ffi) 36 | 37 | (define-foreign-library sqlite3-lib 38 | (:darwin (:default "libsqlite3")) 39 | (:unix (:or "libsqlite3.so.0" "libsqlite3.so")) 40 | (t (:or (:default "libsqlite3") (:default "sqlite3")))) 41 | 42 | (use-foreign-library sqlite3-lib) 43 | 44 | (defcenum error-code 45 | (:OK 0) 46 | (:ERROR 1) 47 | (:INTERNAL 2) 48 | (:PERM 3) 49 | (:ABORT 4) 50 | (:BUSY 5) 51 | (:LOCKED 6) 52 | (:NOMEM 7) 53 | (:READONLY 8) 54 | (:INTERRUPT 9) 55 | (:IOERR 10) 56 | (:CORRUPT 11) 57 | (:NOTFOUND 12) 58 | (:FULL 13) 59 | (:CANTOPEN 14) 60 | (:PROTOCOL 15) 61 | (:EMPTY 16) 62 | (:SCHEMA 17) 63 | (:TOOBIG 18) 64 | (:CONSTRAINT 19) 65 | (:MISMATCH 20) 66 | (:MISUSE 21) 67 | (:NOLFS 22) 68 | (:AUTH 23) 69 | (:FORMAT 24) 70 | (:RANGE 25) 71 | (:NOTADB 26) 72 | (:ROW 100) 73 | (:DONE 101)) 74 | 75 | (defcstruct sqlite3) 76 | 77 | (defctype p-sqlite3 (:pointer sqlite3)) 78 | 79 | (defcfun sqlite3-open error-code 80 | (filename :string) 81 | (db (:pointer p-sqlite3))) 82 | 83 | (defcfun sqlite3-close error-code 84 | (db p-sqlite3)) 85 | 86 | (defcfun sqlite3-errmsg :string 87 | (db p-sqlite3)) 88 | 89 | (defcfun sqlite3-busy-timeout :int 90 | (db p-sqlite3) 91 | (ms :int)) 92 | 93 | (defcstruct sqlite3-stmt) 94 | 95 | (defctype p-sqlite3-stmt (:pointer sqlite3-stmt)) 96 | 97 | (defcfun (sqlite3-prepare "sqlite3_prepare_v2") error-code 98 | (db p-sqlite3) 99 | (sql :string) 100 | (sql-length-bytes :int) 101 | (stmt (:pointer p-sqlite3-stmt)) 102 | (tail (:pointer (:pointer :char)))) 103 | 104 | (defcfun sqlite3-finalize error-code 105 | (statement p-sqlite3-stmt)) 106 | 107 | (defcfun sqlite3-step error-code 108 | (statement p-sqlite3-stmt)) 109 | 110 | (defcfun sqlite3-reset error-code 111 | (statement p-sqlite3-stmt)) 112 | 113 | (defcfun sqlite3-clear-bindings error-code 114 | (statement p-sqlite3-stmt)) 115 | 116 | (defcfun sqlite3-column-count :int 117 | (statement p-sqlite3-stmt)) 118 | 119 | (defcenum type-code 120 | (:integer 1) 121 | (:float 2) 122 | (:text 3) 123 | (:blob 4) 124 | (:null 5)) 125 | 126 | (defcfun sqlite3-column-type type-code 127 | (statement p-sqlite3-stmt) 128 | (column-number :int)) 129 | 130 | (defcfun sqlite3-column-text :string 131 | (statement p-sqlite3-stmt) 132 | (column-number :int)) 133 | 134 | (defcfun sqlite3-column-int64 :int64 135 | (statement p-sqlite3-stmt) 136 | (column-number :int)) 137 | 138 | (defcfun sqlite3-column-double :double 139 | (statement p-sqlite3-stmt) 140 | (column-number :int)) 141 | 142 | (defcfun sqlite3-column-bytes :int 143 | (statement p-sqlite3-stmt) 144 | (column-number :int)) 145 | 146 | (defcfun sqlite3-column-blob :pointer 147 | (statement p-sqlite3-stmt) 148 | (column-number :int)) 149 | 150 | (defcfun sqlite3-column-name :string 151 | (statement p-sqlite3-stmt) 152 | (column-number :int)) 153 | 154 | (defcfun sqlite3-bind-parameter-count :int 155 | (statement p-sqlite3-stmt)) 156 | 157 | (defcfun sqlite3-bind-parameter-name :string 158 | (statement p-sqlite3-stmt) 159 | (column-number :int)) 160 | 161 | (defcfun sqlite3-bind-parameter-index :int 162 | (statement p-sqlite3-stmt) 163 | (name :string)) 164 | 165 | (defcfun sqlite3-bind-double error-code 166 | (statement p-sqlite3-stmt) 167 | (parameter-index :int) 168 | (value :double)) 169 | 170 | (defcfun sqlite3-bind-int64 error-code 171 | (statement p-sqlite3-stmt) 172 | (parameter-index :int) 173 | (value :int64)) 174 | 175 | (defcfun sqlite3-bind-null error-code 176 | (statement p-sqlite3-stmt) 177 | (parameter-index :int)) 178 | 179 | (defcfun sqlite3-bind-text error-code 180 | (statement p-sqlite3-stmt) 181 | (parameter-index :int) 182 | (value :string) 183 | (octets-count :int) 184 | (destructor :pointer)) 185 | 186 | (defcfun sqlite3-bind-blob error-code 187 | (statement p-sqlite3-stmt) 188 | (parameter-index :int) 189 | (value :pointer) 190 | (bytes-count :int) 191 | (destructor :pointer)) 192 | 193 | (defconstant destructor-transient-address (mod -1 (expt 2 (* 8 (cffi:foreign-type-size :pointer))))) 194 | 195 | (defun destructor-transient () (cffi:make-pointer destructor-transient-address)) 196 | 197 | (defun destructor-static () (cffi:make-pointer 0)) 198 | 199 | (defcfun sqlite3-last-insert-rowid :int64 200 | (db p-sqlite3)) 201 | -------------------------------------------------------------------------------- /sqlite-tests.lisp: -------------------------------------------------------------------------------- 1 | (defpackage :sqlite-tests 2 | (:use :cl :sqlite :5am :iter :bordeaux-threads) 3 | (:export :run-all-sqlite-tests)) 4 | 5 | (in-package :sqlite-tests) 6 | 7 | (def-suite sqlite-suite) 8 | 9 | (defun run-all-sqlite-tests () 10 | (run! 'sqlite-suite)) 11 | 12 | (in-suite sqlite-suite) 13 | 14 | (test test-connect 15 | (with-open-database (db ":memory:"))) 16 | 17 | (test test-disconnect-with-statements 18 | (finishes 19 | (with-open-database (db ":memory:") 20 | (prepare-statement db "create table users (id integer primary key, user_name text not null, age integer null)")))) 21 | 22 | (defmacro with-inserted-data ((db) &body body) 23 | `(with-open-database (,db ":memory:") 24 | (execute-non-query ,db "create table users (id integer primary key, user_name text not null, age integer null)") 25 | (execute-non-query ,db "insert into users (user_name, age) values (?, ?)" "joe" 18) 26 | (execute-non-query ,db "insert into users (user_name, age) values (?, ?)" "dvk" 22) 27 | (execute-non-query ,db "insert into users (user_name, age) values (?, ?)" "qwe" 30) 28 | ,@body)) 29 | 30 | (test create-table-insert-and-error 31 | (with-inserted-data (db) 32 | (signals sqlite-constraint-error 33 | (execute-non-query db "insert into users (user_name, age) values (?, ?)" nil nil)))) 34 | 35 | (test create-table-insert-and-error/named 36 | (with-inserted-data (db) 37 | (signals sqlite-constraint-error 38 | (execute-non-query/named db "insert into users (user_name, age) values (:name, :age)" ":name" nil ":age" nil)))) 39 | 40 | (test test-select-single 41 | (with-inserted-data (db) 42 | (is (= (execute-single db "select id from users where user_name = ?" "dvk") 43 | 2)))) 44 | 45 | (test test-select-single/named 46 | (with-inserted-data (db) 47 | (is (= (execute-single/named db "select id from users where user_name = :name" ":name" "dvk") 48 | 2)))) 49 | 50 | (test test-select-m-v 51 | (with-inserted-data (db) 52 | (is (equalp (multiple-value-list (execute-one-row-m-v db "select id, user_name, age from users where user_name = ?" "joe")) 53 | (list 1 "joe" 18))))) 54 | 55 | (test test-select-m-v/named 56 | (with-inserted-data (db) 57 | (is (equalp (multiple-value-list (execute-one-row-m-v/named db "select id, user_name, age from users where user_name = :name" ":name" "joe")) 58 | (list 1 "joe" 18))))) 59 | 60 | (test test-select-list 61 | (with-inserted-data (db) 62 | (is (equalp (execute-to-list db "select id, user_name, age from users") 63 | '((1 "joe" 18) (2 "dvk" 22) (3 "qwe" 30)))))) 64 | 65 | (test test-iterate 66 | (with-inserted-data (db) 67 | (is (equalp (iter (for (id user-name age) in-sqlite-query "select id, user_name, age from users where age < ?" on-database db with-parameters (25)) 68 | (collect (list id user-name age))) 69 | '((1 "joe" 18) (2 "dvk" 22)))))) 70 | 71 | (test test-iterate/named 72 | (with-inserted-data (db) 73 | (is (equalp (iter (for (id user-name age) in-sqlite-query/named "select id, user_name, age from users where age < :age" on-database db with-parameters (":age" 25)) 74 | (collect (list id user-name age))) 75 | '((1 "joe" 18) (2 "dvk" 22)))))) 76 | 77 | (test test-loop-with-prepared-statement 78 | (with-inserted-data (db) 79 | (is (equalp (loop 80 | with statement = (prepare-statement db "select id, user_name, age from users where age < ?") 81 | initially (bind-parameter statement 1 25) 82 | while (step-statement statement) 83 | collect (list (statement-column-value statement 0) (statement-column-value statement 1) (statement-column-value statement 2)) 84 | finally (finalize-statement statement)) 85 | '((1 "joe" 18) (2 "dvk" 22)))))) 86 | 87 | (test test-loop-with-prepared-statement/named 88 | (with-inserted-data (db) 89 | (let ((statement 90 | (prepare-statement db "select id, user_name, age from users where age < $x"))) 91 | (unwind-protect 92 | (progn 93 | (is (equalp (statement-column-names statement) 94 | '("id" "user_name" "age"))) 95 | (is (equalp (statement-bind-parameter-names statement) 96 | '("$x"))) 97 | (bind-parameter statement "$x" 25) 98 | (flet ((fetch-all () 99 | (loop while (step-statement statement) 100 | collect (list (statement-column-value statement 0) 101 | (statement-column-value statement 1) 102 | (statement-column-value statement 2)) 103 | finally (reset-statement statement)))) 104 | (is (equalp (fetch-all) '((1 "joe" 18) (2 "dvk" 22)))) 105 | (is (equalp (fetch-all) '((1 "joe" 18) (2 "dvk" 22)))) 106 | (clear-statement-bindings statement) 107 | (is (equalp (fetch-all) '())))) 108 | (finalize-statement statement))))) 109 | 110 | #+thread-support 111 | (defparameter *db-file* "/tmp/test.sqlite") 112 | 113 | #+thread-support 114 | (defun ensure-table () 115 | (with-open-database (db *db-file*) 116 | (execute-non-query db "CREATE TABLE IF NOT EXISTS FOO (v NUMERIC)"))) 117 | 118 | #+thread-support 119 | (test test-concurrent-inserts 120 | (when (probe-file *db-file*) 121 | (delete-file *db-file*)) 122 | (ensure-table) 123 | (unwind-protect 124 | (do-zillions 10 10000) 125 | (when (probe-file *db-file*) 126 | (delete-file *db-file*)))) 127 | 128 | #+thread-support 129 | (defun do-insert (n timeout) 130 | "Insert a nonsense value into foo" 131 | (ignore-errors 132 | (with-open-database (db *db-file* :busy-timeout timeout) 133 | (iter (repeat 10000) 134 | (execute-non-query db "INSERT INTO FOO (v) VALUES (?)" n))) 135 | t)) 136 | 137 | #+thread-support 138 | (defun do-zillions (max-n timeout) 139 | (iterate (for n from 1 to max-n) 140 | (collect 141 | (bt:make-thread (let ((n n)) 142 | (lambda () 143 | (do-insert n timeout)))) 144 | into threads) 145 | (finally 146 | (iter (for thread in threads) 147 | (for all-ok = t) 148 | (for thread-result = (bt:join-thread thread)) 149 | (unless thread-result 150 | (setf all-ok nil)) 151 | (finally (is-true all-ok "One of inserter threads encountered a SQLITE_BUSY error")))))) 152 | -------------------------------------------------------------------------------- /sqlite.lisp: -------------------------------------------------------------------------------- 1 | (defpackage :sqlite 2 | (:use :cl :iter) 3 | (:export :sqlite-error 4 | :sqlite-constraint-error 5 | :sqlite-error-db-handle 6 | :sqlite-error-code 7 | :sqlite-error-message 8 | :sqlite-error-sql 9 | :sqlite-handle 10 | :connect 11 | :set-busy-timeout 12 | :disconnect 13 | :sqlite-statement 14 | :prepare-statement 15 | :finalize-statement 16 | :step-statement 17 | :reset-statement 18 | :clear-statement-bindings 19 | :statement-column-value 20 | :statement-column-names 21 | :statement-bind-parameter-names 22 | :bind-parameter 23 | :execute-non-query 24 | :execute-to-list 25 | :execute-single 26 | :execute-single/named 27 | :execute-one-row-m-v/named 28 | :execute-to-list/named 29 | :execute-non-query/named 30 | :execute-one-row-m-v 31 | :last-insert-rowid 32 | :with-transaction 33 | :with-open-database)) 34 | 35 | (in-package :sqlite) 36 | 37 | (define-condition sqlite-error (simple-error) 38 | ((handle :initform nil :initarg :db-handle 39 | :reader sqlite-error-db-handle) 40 | (error-code :initform nil :initarg :error-code 41 | :reader sqlite-error-code) 42 | (error-msg :initform nil :initarg :error-msg 43 | :reader sqlite-error-message) 44 | (statement :initform nil :initarg :statement 45 | :reader sqlite-error-statement) 46 | (sql :initform nil :initarg :sql 47 | :reader sqlite-error-sql))) 48 | 49 | (define-condition sqlite-constraint-error (sqlite-error) 50 | ()) 51 | 52 | (defun sqlite-error (error-code message &key 53 | statement 54 | (db-handle (if statement (db statement))) 55 | (sql-text (if statement (sql statement)))) 56 | (error (if (eq error-code :constraint) 57 | 'sqlite-constraint-error 58 | 'sqlite-error) 59 | :format-control (if (listp message) (first message) message) 60 | :format-arguments (if (listp message) (rest message)) 61 | :db-handle db-handle 62 | :error-code error-code 63 | :error-msg (if (and db-handle error-code) 64 | (sqlite-ffi:sqlite3-errmsg (handle db-handle))) 65 | :statement statement 66 | :sql sql-text)) 67 | 68 | (defmethod print-object :after ((obj sqlite-error) stream) 69 | (unless *print-escape* 70 | (when (or (and (sqlite-error-code obj) 71 | (not (eq (sqlite-error-code obj) :ok))) 72 | (sqlite-error-message obj)) 73 | (format stream "~&Code ~A: ~A." 74 | (or (sqlite-error-code obj) :OK) 75 | (or (sqlite-error-message obj) "no message"))) 76 | (when (sqlite-error-db-handle obj) 77 | (format stream "~&Database: ~A" 78 | (database-path (sqlite-error-db-handle obj)))) 79 | (when (sqlite-error-sql obj) 80 | (format stream "~&SQL: ~A" (sqlite-error-sql obj))))) 81 | 82 | ;(declaim (optimize (speed 3) (safety 0) (debug 0))) 83 | 84 | (defclass sqlite-handle () 85 | ((handle :accessor handle) 86 | (database-path :accessor database-path) 87 | (cache :accessor cache) 88 | (statements :initform nil :accessor sqlite-handle-statements)) 89 | (:documentation "Class that encapsulates the connection to the database. Use connect and disconnect.")) 90 | 91 | (defmethod initialize-instance :after ((object sqlite-handle) &key (database-path ":memory:") &allow-other-keys) 92 | (cffi:with-foreign-object (ppdb 'sqlite-ffi:p-sqlite3) 93 | (let ((error-code (sqlite-ffi:sqlite3-open database-path ppdb))) 94 | (if (eq error-code :ok) 95 | (setf (handle object) (cffi:mem-ref ppdb 'sqlite-ffi:p-sqlite3) 96 | (database-path object) database-path) 97 | (sqlite-error error-code (list "Could not open sqlite3 database ~A" database-path))))) 98 | (setf (cache object) (make-instance 'sqlite.cache:mru-cache :cache-size 16 :destructor #'really-finalize-statement))) 99 | 100 | (defun connect (database-path &key busy-timeout) 101 | "Connect to the sqlite database at the given DATABASE-PATH. Returns the SQLITE-HANDLE connected to the database. Use DISCONNECT to disconnect. 102 | Operations will wait for locked databases for up to BUSY-TIMEOUT milliseconds; if BUSY-TIMEOUT is NIL, then operations on locked databases will fail immediately." 103 | (let ((db (make-instance 'sqlite-handle 104 | :database-path (etypecase database-path 105 | (string database-path) 106 | (pathname (namestring database-path)))))) 107 | (when busy-timeout 108 | (set-busy-timeout db busy-timeout)) 109 | db)) 110 | 111 | (defun set-busy-timeout (db milliseconds) 112 | "Sets the maximum amount of time to wait for a locked database." 113 | (sqlite-ffi:sqlite3-busy-timeout (handle db) milliseconds)) 114 | 115 | (defun disconnect (handle) 116 | "Disconnects the given HANDLE from the database. All further operations on the handle are invalid." 117 | (sqlite.cache:purge-cache (cache handle)) 118 | (iter (with statements = (copy-list (sqlite-handle-statements handle))) 119 | (declare (dynamic-extent statements)) 120 | (for statement in statements) 121 | (really-finalize-statement statement)) 122 | (let ((error-code (sqlite-ffi:sqlite3-close (handle handle)))) 123 | (unless (eq error-code :ok) 124 | (sqlite-error error-code "Could not close sqlite3 database." :db-handle handle)) 125 | (slot-makunbound handle 'handle))) 126 | 127 | (defclass sqlite-statement () 128 | ((db :reader db :initarg :db) 129 | (handle :accessor handle) 130 | (sql :reader sql :initarg :sql) 131 | (columns-count :accessor resultset-columns-count) 132 | (columns-names :accessor resultset-columns-names :reader statement-column-names) 133 | (parameters-count :accessor parameters-count) 134 | (parameters-names :accessor parameters-names :reader statement-bind-parameter-names)) 135 | (:documentation "Class that represents the prepared statement.")) 136 | 137 | (defmethod initialize-instance :after ((object sqlite-statement) &key &allow-other-keys) 138 | (cffi:with-foreign-object (p-statement 'sqlite-ffi:p-sqlite3-stmt) 139 | (cffi:with-foreign-object (p-tail '(:pointer :char)) 140 | (cffi:with-foreign-string (sql (sql object)) 141 | (let ((error-code (sqlite-ffi:sqlite3-prepare (handle (db object)) sql -1 p-statement p-tail))) 142 | (unless (eq error-code :ok) 143 | (sqlite-error error-code "Could not prepare an sqlite statement." 144 | :db-handle (db object) :sql-text (sql object))) 145 | (unless (zerop (cffi:mem-ref (cffi:mem-ref p-tail '(:pointer :char)) :uchar)) 146 | (sqlite-error nil "SQL string contains more than one SQL statement." :sql-text (sql object))) 147 | (setf (handle object) (cffi:mem-ref p-statement 'sqlite-ffi:p-sqlite3-stmt) 148 | (resultset-columns-count object) (sqlite-ffi:sqlite3-column-count (handle object)) 149 | (resultset-columns-names object) (loop 150 | for i below (resultset-columns-count object) 151 | collect (sqlite-ffi:sqlite3-column-name (handle object) i)) 152 | (parameters-count object) (sqlite-ffi:sqlite3-bind-parameter-count (handle object)) 153 | (parameters-names object) (loop 154 | for i from 1 to (parameters-count object) 155 | collect (sqlite-ffi:sqlite3-bind-parameter-name (handle object) i)))))))) 156 | 157 | (defun prepare-statement (db sql) 158 | "Prepare the statement to the DB that will execute the commands that are in SQL. 159 | 160 | Returns the SQLITE-STATEMENT. 161 | 162 | SQL must contain exactly one statement. 163 | SQL may have some positional (not named) parameters specified with question marks. 164 | 165 | Example: 166 | 167 | select name from users where id = ?" 168 | (or (let ((statement (sqlite.cache:get-from-cache (cache db) sql))) 169 | (when statement 170 | (clear-statement-bindings statement)) 171 | statement) 172 | (let ((statement (make-instance 'sqlite-statement :db db :sql sql))) 173 | (push statement (sqlite-handle-statements db)) 174 | statement))) 175 | 176 | (defun really-finalize-statement (statement) 177 | (setf (sqlite-handle-statements (db statement)) 178 | (delete statement (sqlite-handle-statements (db statement)))) 179 | (sqlite-ffi:sqlite3-finalize (handle statement)) 180 | (slot-makunbound statement 'handle)) 181 | 182 | (defun finalize-statement (statement) 183 | "Finalizes the statement and signals that associated resources may be released. 184 | Note: does not immediately release resources because statements are cached." 185 | (reset-statement statement) 186 | (sqlite.cache:put-to-cache (cache (db statement)) (sql statement) statement)) 187 | 188 | (defun step-statement (statement) 189 | "Steps to the next row of the resultset of STATEMENT. 190 | Returns T is successfully advanced to the next row and NIL if there are no more rows." 191 | (let ((error-code (sqlite-ffi:sqlite3-step (handle statement)))) 192 | (case error-code 193 | (:done nil) 194 | (:row t) 195 | (t 196 | (sqlite-error error-code "Error while stepping an sqlite statement." :statement statement))))) 197 | 198 | (defun reset-statement (statement) 199 | "Resets the STATEMENT and prepare it to be called again." 200 | (let ((error-code (sqlite-ffi:sqlite3-reset (handle statement)))) 201 | (unless (eq error-code :ok) 202 | (sqlite-error error-code "Error while resetting an sqlite statement." :statement statement)))) 203 | 204 | (defun clear-statement-bindings (statement) 205 | "Sets all binding values to NULL." 206 | (let ((error-code (sqlite-ffi:sqlite3-clear-bindings (handle statement)))) 207 | (unless (eq error-code :ok) 208 | (sqlite-error error-code "Error while clearing bindings of an sqlite statement." 209 | :statement statement)))) 210 | 211 | (defun statement-column-value (statement column-number) 212 | "Returns the COLUMN-NUMBER-th column's value of the current row of the STATEMENT. Columns are numbered from zero. 213 | Returns: 214 | * NIL for NULL 215 | * INTEGER for integers 216 | * DOUBLE-FLOAT for floats 217 | * STRING for text 218 | * (SIMPLE-ARRAY (UNSIGNED-BYTE 8)) for BLOBs" 219 | (let ((type (sqlite-ffi:sqlite3-column-type (handle statement) column-number))) 220 | (ecase type 221 | (:null nil) 222 | (:text (sqlite-ffi:sqlite3-column-text (handle statement) column-number)) 223 | (:integer (sqlite-ffi:sqlite3-column-int64 (handle statement) column-number)) 224 | (:float (sqlite-ffi:sqlite3-column-double (handle statement) column-number)) 225 | (:blob (let* ((blob-length (sqlite-ffi:sqlite3-column-bytes (handle statement) column-number)) 226 | (result (make-array (the fixnum blob-length) :element-type '(unsigned-byte 8))) 227 | (blob (sqlite-ffi:sqlite3-column-blob (handle statement) column-number))) 228 | (loop 229 | for i below blob-length 230 | do (setf (aref result i) (cffi:mem-aref blob :unsigned-char i))) 231 | result))))) 232 | 233 | (defmacro with-prepared-statement (statement-var (db sql parameters-var) &body body) 234 | (let ((i-var (gensym "I")) 235 | (value-var (gensym "VALUE"))) 236 | `(let ((,statement-var (prepare-statement ,db ,sql))) 237 | (unwind-protect 238 | (progn 239 | (iter (for ,i-var from 1) 240 | (declare (type fixnum ,i-var)) 241 | (for ,value-var in ,parameters-var) 242 | (bind-parameter ,statement-var ,i-var ,value-var)) 243 | ,@body) 244 | (finalize-statement ,statement-var))))) 245 | 246 | (defmacro with-prepared-statement/named (statement-var (db sql parameters-var) &body body) 247 | (let ((name-var (gensym "NAME")) 248 | (value-var (gensym "VALUE"))) 249 | `(let ((,statement-var (prepare-statement ,db ,sql))) 250 | (unwind-protect 251 | (progn 252 | (iter (for (,name-var ,value-var) on ,parameters-var by #'cddr) 253 | (bind-parameter ,statement-var (string ,name-var) ,value-var)) 254 | ,@body) 255 | (finalize-statement ,statement-var))))) 256 | 257 | (defun execute-non-query (db sql &rest parameters) 258 | "Executes the query SQL to the database DB with given PARAMETERS. Returns nothing. 259 | 260 | Example: 261 | 262 | \(execute-non-query db \"insert into users (user_name, real_name) values (?, ?)\" \"joe\" \"Joe the User\") 263 | 264 | See BIND-PARAMETER for the list of supported parameter types." 265 | (declare (dynamic-extent parameters)) 266 | (with-prepared-statement statement (db sql parameters) 267 | (step-statement statement))) 268 | 269 | (defun execute-non-query/named (db sql &rest parameters) 270 | "Executes the query SQL to the database DB with given PARAMETERS. Returns nothing. 271 | 272 | PARAMETERS is a list of alternating parameter names and values. 273 | 274 | Example: 275 | 276 | \(execute-non-query db \"insert into users (user_name, real_name) values (:name, :real_name)\" \":name\" \"joe\" \":real_name\" \"Joe the User\") 277 | 278 | See BIND-PARAMETER for the list of supported parameter types." 279 | (declare (dynamic-extent parameters)) 280 | (with-prepared-statement/named statement (db sql parameters) 281 | (step-statement statement))) 282 | 283 | (defun execute-to-list (db sql &rest parameters) 284 | "Executes the query SQL to the database DB with given PARAMETERS. Returns the results as list of lists. 285 | 286 | Example: 287 | 288 | \(execute-to-list db \"select id, user_name, real_name from users where user_name = ?\" \"joe\") 289 | => 290 | \((1 \"joe\" \"Joe the User\") 291 | (2 \"joe\" \"Another Joe\")) 292 | 293 | See BIND-PARAMETER for the list of supported parameter types." 294 | (declare (dynamic-extent parameters)) 295 | (with-prepared-statement stmt (db sql parameters) 296 | (let (result) 297 | (loop (if (step-statement stmt) 298 | (push (iter (for i from 0 below (the fixnum (sqlite-ffi:sqlite3-column-count (handle stmt)))) 299 | (declare (type fixnum i)) 300 | (collect (statement-column-value stmt i))) 301 | result) 302 | (return))) 303 | (nreverse result)))) 304 | 305 | (defun execute-to-list/named (db sql &rest parameters) 306 | "Executes the query SQL to the database DB with given PARAMETERS. Returns the results as list of lists. 307 | 308 | PARAMETERS is a list of alternating parameters names and values. 309 | 310 | Example: 311 | 312 | \(execute-to-list db \"select id, user_name, real_name from users where user_name = :user_name\" \":user_name\" \"joe\") 313 | => 314 | \((1 \"joe\" \"Joe the User\") 315 | (2 \"joe\" \"Another Joe\")) 316 | 317 | See BIND-PARAMETER for the list of supported parameter types." 318 | (declare (dynamic-extent parameters)) 319 | (with-prepared-statement/named stmt (db sql parameters) 320 | (let (result) 321 | (loop (if (step-statement stmt) 322 | (push (iter (for i from 0 below (the fixnum (sqlite-ffi:sqlite3-column-count (handle stmt)))) 323 | (declare (type fixnum i)) 324 | (collect (statement-column-value stmt i))) 325 | result) 326 | (return))) 327 | (nreverse result)))) 328 | 329 | (defun execute-one-row-m-v (db sql &rest parameters) 330 | "Executes the query SQL to the database DB with given PARAMETERS. Returns the first row as multiple values. 331 | 332 | Example: 333 | \(execute-one-row-m-v db \"select id, user_name, real_name from users where id = ?\" 1) 334 | => 335 | \(values 1 \"joe\" \"Joe the User\") 336 | 337 | See BIND-PARAMETER for the list of supported parameter types." 338 | (with-prepared-statement stmt (db sql parameters) 339 | (if (step-statement stmt) 340 | (return-from execute-one-row-m-v 341 | (values-list (iter (for i from 0 below (the fixnum (sqlite-ffi:sqlite3-column-count (handle stmt)))) 342 | (declare (type fixnum i)) 343 | (collect (statement-column-value stmt i))))) 344 | (return-from execute-one-row-m-v 345 | (values-list (loop repeat (the fixnum (sqlite-ffi:sqlite3-column-count (handle stmt))) collect nil)))))) 346 | 347 | (defun execute-one-row-m-v/named (db sql &rest parameters) 348 | "Executes the query SQL to the database DB with given PARAMETERS. Returns the first row as multiple values. 349 | 350 | PARAMETERS is a list of alternating parameters names and values. 351 | 352 | Example: 353 | \(execute-one-row-m-v db \"select id, user_name, real_name from users where id = :id\" \":id\" 1) 354 | => 355 | \(values 1 \"joe\" \"Joe the User\") 356 | 357 | See BIND-PARAMETER for the list of supported parameter types." 358 | (with-prepared-statement/named stmt (db sql parameters) 359 | (if (step-statement stmt) 360 | (return-from execute-one-row-m-v/named 361 | (values-list (iter (for i from 0 below (the fixnum (sqlite-ffi:sqlite3-column-count (handle stmt)))) 362 | (declare (type fixnum i)) 363 | (collect (statement-column-value stmt i))))) 364 | (return-from execute-one-row-m-v/named 365 | (values-list (loop repeat (the fixnum (sqlite-ffi:sqlite3-column-count (handle stmt))) collect nil)))))) 366 | 367 | (defun statement-parameter-index (statement parameter-name) 368 | (sqlite-ffi:sqlite3-bind-parameter-index (handle statement) parameter-name)) 369 | 370 | (defun bind-parameter (statement parameter value) 371 | "Sets the PARAMETER-th parameter in STATEMENT to the VALUE. 372 | PARAMETER may be parameter index (starting from 1) or parameters name. 373 | Supported types: 374 | * NULL. Passed as NULL 375 | * INTEGER. Passed as an 64-bit integer 376 | * STRING. Passed as a string 377 | * FLOAT. Passed as a double 378 | * (VECTOR (UNSIGNED-BYTE 8)) and VECTOR that contains integers in range [0,256). Passed as a BLOB" 379 | (let ((index (etypecase parameter 380 | (integer parameter) 381 | (string (statement-parameter-index statement parameter))))) 382 | (declare (type fixnum index)) 383 | (let ((error-code (typecase value 384 | (null (sqlite-ffi:sqlite3-bind-null (handle statement) index)) 385 | (integer (sqlite-ffi:sqlite3-bind-int64 (handle statement) index value)) 386 | (double-float (sqlite-ffi:sqlite3-bind-double (handle statement) index value)) 387 | (real (sqlite-ffi:sqlite3-bind-double (handle statement) index (coerce value 'double-float))) 388 | (string (sqlite-ffi:sqlite3-bind-text (handle statement) index value -1 (sqlite-ffi:destructor-transient))) 389 | ((vector (unsigned-byte 8)) (cffi:with-pointer-to-vector-data (ptr value) 390 | (sqlite-ffi:sqlite3-bind-blob (handle statement) index ptr (length value) (sqlite-ffi:destructor-transient)))) 391 | (vector (cffi:with-foreign-object (array :unsigned-char (length value)) 392 | (loop 393 | for i from 0 below (length value) 394 | do (setf (cffi:mem-aref array :unsigned-char i) (aref value i))) 395 | (sqlite-ffi:sqlite3-bind-blob (handle statement) index array (length value) (sqlite-ffi:destructor-transient)))) 396 | (t 397 | (sqlite-error nil 398 | (list "Do not know how to pass value ~A of type ~A to sqlite." 399 | value (type-of value)) 400 | :statement statement))))) 401 | (unless (eq error-code :ok) 402 | (sqlite-error error-code 403 | (list "Error when binding parameter ~A to value ~A." parameter value) 404 | :statement statement))))) 405 | 406 | (defun execute-single (db sql &rest parameters) 407 | "Executes the query SQL to the database DB with given PARAMETERS. Returns the first column of the first row as single value. 408 | 409 | Example: 410 | \(execute-single db \"select user_name from users where id = ?\" 1) 411 | => 412 | \"joe\" 413 | 414 | See BIND-PARAMETER for the list of supported parameter types." 415 | (declare (dynamic-extent parameters)) 416 | (with-prepared-statement stmt (db sql parameters) 417 | (if (step-statement stmt) 418 | (statement-column-value stmt 0) 419 | nil))) 420 | 421 | (defun execute-single/named (db sql &rest parameters) 422 | "Executes the query SQL to the database DB with given PARAMETERS. Returns the first column of the first row as single value. 423 | 424 | PARAMETERS is a list of alternating parameters names and values. 425 | 426 | Example: 427 | \(execute-single db \"select user_name from users where id = :id\" \":id\" 1) 428 | => 429 | \"joe\" 430 | 431 | See BIND-PARAMETER for the list of supported parameter types." 432 | (declare (dynamic-extent parameters)) 433 | (with-prepared-statement/named stmt (db sql parameters) 434 | (if (step-statement stmt) 435 | (statement-column-value stmt 0) 436 | nil))) 437 | 438 | (defun last-insert-rowid (db) 439 | "Returns the auto-generated ID of the last inserted row on the database connection DB." 440 | (sqlite-ffi:sqlite3-last-insert-rowid (handle db))) 441 | 442 | (defmacro with-transaction (db &body body) 443 | "Wraps the BODY inside the transaction." 444 | (let ((ok (gensym "TRANSACTION-COMMIT-")) 445 | (db-var (gensym "DB-"))) 446 | `(let (,ok 447 | (,db-var ,db)) 448 | (execute-non-query ,db-var "begin transaction") 449 | (unwind-protect 450 | (multiple-value-prog1 451 | (progn ,@body) 452 | (setf ,ok t)) 453 | (if ,ok 454 | (execute-non-query ,db-var "commit transaction") 455 | (execute-non-query ,db-var "rollback transaction")))))) 456 | 457 | (defmacro with-open-database ((db path &key busy-timeout) &body body) 458 | `(let ((,db (connect ,path :busy-timeout ,busy-timeout))) 459 | (unwind-protect 460 | (progn ,@body) 461 | (disconnect ,db)))) 462 | 463 | (defmacro-driver (FOR vars IN-SQLITE-QUERY query-expression ON-DATABASE db &optional WITH-PARAMETERS parameters) 464 | (let ((statement (gensym "STATEMENT-")) 465 | (kwd (if generate 'generate 'for))) 466 | `(progn (with ,statement = (prepare-statement ,db ,query-expression)) 467 | (finally-protected (when ,statement (finalize-statement ,statement))) 468 | ,@(when parameters 469 | (list `(initially ,@(iter (for i from 1) 470 | (for value in parameters) 471 | (collect `(sqlite:bind-parameter ,statement ,i ,value)))))) 472 | (,kwd ,(if (symbolp vars) 473 | `(values ,vars) 474 | `(values ,@vars)) 475 | next (progn (if (step-statement ,statement) 476 | (values ,@(iter (for i from 0 below (if (symbolp vars) 1 (length vars))) 477 | (collect `(statement-column-value ,statement ,i)))) 478 | (terminate))))))) 479 | 480 | (defmacro-driver (FOR vars IN-SQLITE-QUERY/NAMED query-expression ON-DATABASE db &optional WITH-PARAMETERS parameters) 481 | (let ((statement (gensym "STATEMENT-")) 482 | (kwd (if generate 'generate 'for))) 483 | `(progn (with ,statement = (prepare-statement ,db ,query-expression)) 484 | (finally-protected (when ,statement (finalize-statement ,statement))) 485 | ,@(when parameters 486 | (list `(initially ,@(iter (for (name value) on parameters by #'cddr) 487 | (collect `(sqlite:bind-parameter ,statement ,name ,value)))))) 488 | (,kwd ,(if (symbolp vars) 489 | `(values ,vars) 490 | `(values ,@vars)) 491 | next (progn (if (step-statement ,statement) 492 | (values ,@(iter (for i from 0 below (if (symbolp vars) 1 (length vars))) 493 | (collect `(statement-column-value ,statement ,i)))) 494 | (terminate))))))) 495 | 496 | 497 | (defmacro-driver (FOR vars ON-SQLITE-STATEMENT statement) 498 | (let ((statement-var (gensym "STATEMENT-")) 499 | (kwd (if generate 'generate 'for))) 500 | `(progn (with ,statement-var = ,statement) 501 | (,kwd ,(if (symbolp vars) 502 | `(values ,vars) 503 | `(values ,@vars)) 504 | next (progn (if (step-statement ,statement-var) 505 | (values ,@(iter (for i from 0 below (if (symbolp vars) 1 (length vars))) 506 | (collect `(statement-column-value ,statement-var ,i)))) 507 | (terminate))))))) -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | SQLITE - Sqlite package 7 | 8 | 25 | 26 | 27 | 28 | 29 |
30 |

CL-SQLITE

31 |
32 | 33 |
34 |
 

Abstract

35 | 36 |

CL-SQLITE package is an interface to the SQLite embedded relational database engine.

37 | 38 |

The code is in public domain so you can basically do with it whatever you want.

39 | 40 |

This documentation describes only the CL-SQLITE package, not the SQLite database itself. SQLite documentation is available at http://sqlite.org/docs.html

41 | 42 | 43 |

CL-SQLITE together with this documentation can be downloaded from http://common-lisp.net/project/cl-sqlite/releases/cl-sqlite-0.2.tar.gz.

45 | 46 |

CL-SQLITE source code is available in Git repository at git://repo.or.cz/cl-sqlite.git (gitweb) and at git://github.com/TeMPOraL/cl-sqlite.git (gitweb).

47 | 48 |

49 |

50 | 51 |
 

Contents

52 |
    53 |
  1. Installation 54 |
  2. Example 55 |
  3. Usage 56 |
  4. The SQLITE dictionary 57 |
      58 |
    1. bind-parameter 59 |
    2. clear-statement-bindings 60 |
    3. connect 61 |
    4. disconnect 62 |
    5. execute-non-query 63 |
    6. execute-non-query/named 64 |
    7. execute-one-row-m-v 65 |
    8. execute-one-row-m-v/named 66 |
    9. execute-single 67 |
    10. execute-single/named 68 |
    11. execute-to-list 69 |
    12. execute-to-list/named 70 |
    13. finalize-statement 71 |
    14. last-insert-rowid 72 |
    15. prepare-statement 73 |
    16. reset-statement 74 |
    17. sqlite-error 75 |
    18. sqlite-constraint-error 76 |
    19. sqlite-error-code 77 |
    20. sqlite-error-db-handle 78 |
    21. sqlite-error-message 79 |
    22. sqlite-error-sql 80 |
    23. sqlite-handle 81 |
    24. sqlite-statement 82 |
    25. statement-bind-parameter-names 83 |
    26. statement-column-names 84 |
    27. statement-column-value 85 |
    28. step-statement 86 |
    29. with-transaction 87 |
    30. with-open-database 88 |
    89 |
  5. Support 90 |
  6. Changelog 91 |
  7. Acknowledgements 92 |
93 | 94 |
 

Installation

95 | 96 |

The package can be downloaded from http://common-lisp.net/project/cl-sqlite/releases/cl-sqlite-0.2.tar.gz. 98 | CL-SQLITE package has the following dependencies:

99 | 103 | 104 |

SQLITE has a system definition for ASDF. Compile and load it in the usual way.

105 | 106 |

This package does not include SQLite library. It should be installed 107 | and loadable with regular FFI mechanisms. On Linux and Mac OS X SQLite 108 | is probably already installed (if it's not installed, use native package 109 | manager to install it). On Windows PATH environment variable should 110 | contain path to sqlite3.dll.

111 | 112 |
 

Example

113 | 114 | 
115 | (use-package :sqlite)
116 | (use-package :iter)
117 | 
118 | (defvar *db* (connect ":memory:")) ;;Connect to the sqlite database. :memory: is the temporary in-memory database
119 | 
120 | (execute-non-query *db* "create table users (id integer primary key, user_name text not null, age integer null)") ;;Create the table
121 | 
122 | (execute-non-query *db* "insert into users (user_name, age) values (?, ?)" "joe" 18)
123 | (execute-non-query/named *db* "insert into users (user_name, age) values (:user_name, :user_age)" 
124 |                          ":user_name" "dvk" ":user_age" 22)
125 | (execute-non-query *db* "insert into users (user_name, age) values (?, ?)" "qwe" 30)
126 | (execute-non-query *db* "insert into users (user_name, age) values (?, ?)" nil nil) ;; ERROR: constraint failed
127 | 
128 | (execute-single *db* "select id from users where user_name = ?" "dvk")
129 | ;; => 2
130 | (execute-one-row-m-v *db* "select id, user_name, age from users where user_name = ?" "joe")
131 | ;; => (values 1 "joe" 18)
132 | 
133 | (execute-to-list *db* "select id, user_name, age from users")
134 | ;; => ((1 "joe" 18) (2 "dvk" 22) (3 "qwe" 30))
135 | 
136 | ;; Use iterate
137 | (iter (for (id user-name age) in-sqlite-query "select id, user_name, age from users where age < ?" on-database *db* with-parameters (25))
138 |       (collect (list id user-name age)))
139 | ;; => ((1 "joe" 18) (2 "dvk" 22))
140 | 
141 | ;; Use iterate with named parameters
142 | (iter (for (id user-name age) in-sqlite-query/named "select id, user_name, age from users where age < :age"
143 |       on-database *db* with-parameters (":age" 25))
144 |       (collect (list id user-name age)))
145 | ;; => ((1 "joe" 18) (2 "dvk" 22))
146 | 
147 | ;; Use prepared statements directly
148 | (loop
149 |    with statement = (prepare-statement *db* "select id, user_name, age from users where age < ?")
150 |    initially (bind-parameter statement 1 25)
151 |    while (step-statement statement)
152 |    collect (list (statement-column-value statement 0) (statement-column-value statement 1) (statement-column-value statement 2))
153 |    finally (finalize-statement statement))
154 | ;; => ((1 "joe" 18) (2 "dvk" 22))
155 | 
156 | ;; Use prepared statements with named parameters
157 | (loop
158 |    with statement = (prepare-statement *db* "select id, user_name, age from users where age < :age")
159 |    initially (bind-parameter statement ":age" 25)
160 |    while (step-statement statement)
161 |    collect (list (statement-column-value statement 0) (statement-column-value statement 1) (statement-column-value statement 2))
162 |    finally (finalize-statement statement))
163 | ;; => ((1 "joe" 18) (2 "dvk" 22))
164 | 
165 | (disconnect *db*) ;;Disconnect
166 | 167 |
 

Usage

168 | 169 |

Two functions and a macro are used to manage connections to the database:

170 |
    171 |
  • Function connect connects to the database
    • 172 |
  • Function disconnect disconnects from the database
    • 173 |
  • Macro with-open-database opens the database and ensures that it is properly closed after the code is run
    • 174 |
175 | 176 |

To make queries to the database the following functions are provided:

177 | 183 | 184 |

Macro with-transaction is used to execute code within transaction.

185 | 186 |

Support for ITERATE is provided. Use the following clause: 187 | 

(for (vars) in-sqlite-query sql on-database db &optional with-parameters (&rest parameters))
188 | This clause will bind vars (a list of variables) to the values of the columns of query.

189 | 190 |

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.

191 | 192 |

Positional and named parameters in queries are supported. Positional parameters are denoted by question mark in SQL code, and named parameters are denoted by prefixing color (:), at sign (@) or dollar sign ($) before parameter name.

193 | 194 |

Following types are supported:

195 |
    196 |
  • Integer. Integers are stored as 64-bit integers.
    • 197 |
  • Float. Stored as double. Single-float, double-float and rational may be passed as a parameter, and double-float will be returned.
    • 198 |
  • String. Stored as an UTF-8 string.
    • 199 |
  • Vector of bytes. Stored as a blob.
    • 200 |
  • Null. Passed as NIL to and from database.
    • 201 |
202 | 203 |
 

The SQLITE dictionary

204 | 205 | 206 | 207 | 208 | 209 |


[Function]
bind-parameter statement parameter value 210 |


211 | 212 | Sets the parameter in statement to the value.
213 | parameter is an index (parameters are numbered from one) or the name of a parameter.
214 | Supported types:
215 |
    216 |
  • Null. Passed as NULL 217 |
  • Integer. Passed as an 64-bit integer 218 |
  • String. Passed as a string 219 |
  • Float. Passed as a double 220 |
  • (vector (unsigned-byte 8)) and vector that contains integers in range [0,256). Passed as a BLOB 221 |
222 | 223 |
224 | 225 | 226 | 227 | 228 | 229 |


[Function]
clear-statement-bindings statement 230 |


231 | 232 | Binds all parameters of the statement to NULL. 233 | 234 |
235 | 236 | 237 | 238 | 239 | 240 |


[Function]
connect database-path &key busy-timeout => sqlite-handle 241 |


242 | 243 | 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.
244 | 245 | Operations will wait for locked databases for up to busy-timeout milliseconds; if busy-timeout is NIL, then operations on locked databases will fail immediately. 246 | 247 |
248 | 249 | 250 | 251 | 252 | 253 | 254 |


[Function]
disconnect handle 255 |


256 | 257 | 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. 258 | 259 |
260 | 261 | 262 | 263 | 264 | 265 | 266 |


[Function]
execute-non-query db sql &rest parameters 267 |


268 | 269 | Executes the query sql to the database db with given parameters. Returns nothing.
270 | 271 | Example:
272 | 273 | 
(execute-non-query db "insert into users (user_name, real_name) values (?, ?)" "joe" "Joe the User")
274 | 275 | See bind-parameter for the list of supported parameter types. 276 | 277 |
278 | 279 | 280 | 281 | 282 | 283 | 284 |


[Function]
execute-non-query/named db sql &rest parameters 285 |


286 | 287 | Executes the query sql to the database db with given parameters. Returns nothing. Parameters are alternating names and values.
288 | 289 | Example:
290 | 291 | 
(execute-non-query/named db "insert into users (user_name, real_name) values (:user_name, :real_name)"
292 |                          ":user_name" "joe" ":real_name" "Joe the User")
293 | 294 | See bind-parameter for the list of supported parameter types. 295 | 296 |
297 | 298 | 299 | 300 | 301 | 302 | 303 |


[Function]
execute-one-row-m-v db sql &rest parameters => (values result*) 304 |


305 | 306 | Executes the query sql to the database db with given parameters. Returns the first row as multiple values.
307 | 308 | Example:
309 | 
(execute-one-row-m-v db "select id, user_name, real_name from users where id = ?" 1)
310 | =>
311 | (values 1 "joe" "Joe the User")
312 | 313 | See bind-parameter for the list of supported parameter types. 314 | 315 |
316 | 317 | 318 | 319 | 320 | 321 | 322 |


[Function]
execute-one-row-m-v/named db sql &rest parameters => (values result*) 323 |


324 | 325 | Executes the query sql to the database db with given parameters. Returns the first row as multiple values. Parameters are alternating names and values.
326 | 327 | Example:
328 | 
(execute-one-row-m-v/named db "select id, user_name, real_name from users where id = :id" ":id" 1)
329 | =>
330 | (values 1 "joe" "Joe the User")
331 | 332 | See bind-parameter for the list of supported parameter types. 333 | 334 |
335 | 336 | 337 | 338 | 339 | 340 | 341 |


[Function]
execute-single db sql &rest parameters => result 342 |


343 | 344 | Executes the query sql to the database db with given parameters. Returns the first column of the first row as single value.
345 | 346 | Example:
347 | 
(execute-single db "select user_name from users where id = ?" 1)
348 | =>
349 | "joe"
350 | 351 | See bind-parameter for the list of supported parameter types. 352 | 353 |
354 | 355 | 356 | 357 | 358 | 359 | 360 |


[Function]
execute-single/named db sql &rest parameters => result 361 |


362 | 363 | Executes the query sql to the database db with given parameters. Returns the first column of the first row as single value. Parameters are alternating names and values.
364 | 365 | Example:
366 | 
(execute-single/named db "select user_name from users where id = :id" ":id" 1)
367 | =>
368 | "joe"
369 | 370 | See bind-parameter for the list of supported parameter types. 371 | 372 |
373 | 374 | 375 | 376 | 377 | 378 | 379 |


[Function]
execute-to-list db sql &rest parameters => results 380 |


381 | 382 | Executes the query sql to the database db with given parameters. Returns the results as list of lists.
383 | 384 | Example:
385 | 386 | 
(execute-to-list db "select id, user_name, real_name from users where user_name = ?" "joe")
387 | =>
388 | ((1 "joe" "Joe the User")
389 |  (2 "joe" "Another Joe"))
390 | 391 | See bind-parameter for the list of supported parameter types. 392 | 393 |
394 | 395 | 396 | 397 | 398 | 399 | 400 |


[Function]
execute-to-list/named db sql &rest parameters => results 401 |


402 | 403 | Executes the query sql to the database db with given parameters. Returns the results as list of lists. Parameters are alternating names and values.
404 | 405 | Example:
406 | 407 | 
(execute-to-list db "select id, user_name, real_name from users where user_name = :name" ":name" "joe")
408 | =>
409 | ((1 "joe" "Joe the User")
410 |  (2 "joe" "Another Joe"))
411 | 412 | See bind-parameter for the list of supported parameter types. 413 | 414 |
415 | 416 | 417 | 418 | 419 | 420 | 421 |


[Function]
finalize-statement statement 422 |


423 | 424 | Finalizes the statement and signals that associated resources may be released.
425 | Note: does not immediately release resources because statements are cached. 426 | 427 |
428 | 429 | 430 | 431 | 432 | 433 | 434 |


[Function]
last-insert-rowid db => result 435 |


436 | 437 | Returns the auto-generated ID of the last inserted row on the database connection db. 438 | 439 |
440 | 441 | 442 | 443 | 444 | 445 | 446 |


[Function]
prepare-statement db sql => sqlite-statement 447 |


448 | 449 | Prepare the statement to the DB that will execute the commands that are in sql.
450 | 451 | Returns the sqlite-statement.
452 | 453 | sql must contain exactly one statement.
454 | sql may have some positional (not named) parameters specified with question marks.
455 | 456 | Example:
457 | 458 | 
(prepare-statement db "select name from users where id = ?")
459 | 460 |
461 | 462 | 463 | 464 | 465 | 466 | 467 |


[Function]
reset-statement statement 468 |


469 | 470 | Resets the statement and prepares it to be called again. Note that bind parameter values are not cleared; use clear-statement-bindings for that. 471 | 472 |
473 | 474 | 475 | 476 | 477 | 478 |


[Condition]
sqlite-error 479 |


480 | 481 | Error condition used by the library. 482 |
483 | 484 | 485 | 486 | 487 | 488 |


[Condition]
sqlite-constraint-error 489 |


490 | 491 | A subclass of sqlite-error used to distinguish constraint violation errors. 492 |
493 | 494 | 495 | 496 | 497 | 498 |


[Accessor]
sqlite-error-code sqlite-error => keyword or null 499 |


500 | 501 | Returns the SQLite error code represeting the error. 502 |
503 | 504 | 505 | 506 | 507 | 508 |


[Accessor]
sqlite-error-db-handle sqlite-error => sqlite-handle or null 509 |


510 | 511 | Returns the SQLite database connection that caused the error. 512 |
513 | 514 | 515 | 516 | 517 | 518 |


[Accessor]
sqlite-error-message sqlite-error => string or null 519 |


520 | 521 | Returns the SQLite error message corresponding to the error code. 522 |
523 | 524 | 525 | 526 | 527 | 528 |


[Accessor]
sqlite-error-sql sqlite-error => string or null 529 |


530 | 531 | Returns the SQL statement source string that caused the error. 532 |
533 | 534 | 535 | 536 | 537 | 538 |


[Standard class]
sqlite-handle 539 |


540 | 541 | Class that encapsulates the connection to the database. 542 | 543 |
544 | 545 | 546 | 547 | 548 | 549 | 550 |


[Standard class]
sqlite-statement 551 |


552 | 553 | Class that represents the prepared statement. 554 | 555 |
556 | 557 | 558 | 559 | 560 | 561 |


[Accessor]
statement-bind-parameter-names statement => list of strings 562 |


563 | 564 | Returns the names of the bind parameters of the prepared statement. If a parameter does not have a name, the corresponding list item is NIL. 565 |
566 | 567 | 568 | 569 | 570 | 571 |


[Accessor]
statement-column-names statement => list of strings 572 |


573 | 574 | Returns the names of columns in the result set of the prepared statement. 575 |
576 | 577 | 578 | 579 | 580 | 581 |


[Function]
statement-column-value statement column-number => result 582 |


583 | 584 | Returns the column-number-th column's value of the current row of the statement. Columns are numbered from zero.
585 | Returns:
586 |
    587 |
  • NIL for NULL 588 |
  • integer for integers 589 |
  • double-float for floats 590 |
  • string for text 591 |
  • (simple-array (unsigned-byte 8)) for BLOBs 592 |
593 |
594 | 595 | 596 | 597 | 598 | 599 | 600 |


[Function]
step-statement statement => boolean 601 |


602 | 603 | Steps to the next row of the resultset of statement.
604 | Returns T is successfully advanced to the next row and NIL if there are no more rows. 605 | 606 |
607 | 608 | 609 | 610 | 611 | 612 | 613 |


[Macro]
with-transaction db &body body 614 |


615 | 616 | Wraps the body inside the transaction. If body evaluates without error, transaction is commited. If evaluation of body is interrupted, transaction is rolled back. 617 | 618 |
619 | 620 | 621 | 622 | 623 | 624 | 625 |


[Macro]
with-open-database (db path &key busy-timeout) &body body 626 |


627 | 628 | 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.
629 | See CONNECT for meaning of busy-timeout parameter. 630 | 631 |
632 | 633 | 634 | 635 |
 

Support

636 | 637 | This package is written by Kalyanov Dmitry.
638 | 639 | This project has a cl-sqlite-devel mailing list.
640 | 641 |
 

Changelog

642 | 643 |
    644 |
  • 23 Jan 2009 0.1 Initial version 645 |
  • 03 Mar 2009 0.1.1 Fixed bug with access to recently freed memory during statement preparation 646 |
  • 22 Mar 2009 0.1.2 disconnect function now ensures that all non-finalized statements are finalized before closing the database (otherwise errors are signaled when database is being closed). 647 |
  • 28 Apr 2009 0.1.3 Added support for passing all values of type REAL (including RATIONAL) as query parameter. cl-sqlite is made available as git repository. 648 |
  • 10 May 2009 0.1.4 Added test suite (based on FiveAM testing framework); changed foreign library definition to work on Mac OS X (thanks to Patrick Stein) and removed the dependency on sqlite3_next_stmt function that appeared only in sqlite 3.6.0 (making cl-sqlite work with older sqlite versions) 649 |
  • 13 June 2009 0.1.5 Allow passing pathnames to CONNECT function. 650 |
  • 24 Oct 2009 0.1.6 Add busy-timeout argument to CONNECT. Fix library defininitions for running on Microsoft Windows. 651 |
  • 14 Nov 2010 0.2 Added support for named parameters. Made statement reset and connection close more safe by clearing statements' bindings and unbinding slot of connection object. Added error condition for SQLite errors. Changes are courtesy of Alexander Gavrilov. 652 |
  • 02 Aug 2019 0.2.1 Added metadata to system definitions. Fixed symbol conflict with FiveAM in tests. Project maintenance is now handled by Jacek Złydach. 653 |
654 | 655 |
 

Acknowledgements

656 | 657 |

658 | This documentation was prepared with DOCUMENTATION-TEMPLATE. 659 |

660 |

661 | $Header: /usr/local/cvsrep/documentation-template/output.lisp,v 1.14 2008/05/29 08:23:37 edi Exp $ 662 | 663 | 664 | 665 | --------------------------------------------------------------------------------