No matching definitions.

← Home

Exported

Internal

sqlite/db

src/sqlite/db.tur
defn

db-open

(db-open [path :cstr] :ptr<void>)

open a SQLite3 database file, creating it if it does not exist.

Parameters
pathfilesystem path to the database file
Returns

(ok db-handle) on success; (err 0) on failure. Use sqlite-errmsg from sqlite/error on the handle for details. Inspect with ok? / ok-val / err-val from stdlib/result.

Example
(let [r (db-open "app.db")]
    (if (ok? r) (let [db (ok-val r)] ...) (println "open failed")))

Since: P2

defn

db-close

(db-close [db :int] :ptr<void>)

close a database handle opened with db-open.

Parameters
dbdatabase handle (ok-val from db-open)
Returns

(ok 0) always.

Example
(db-close db)

Since: P2

defn

db-exec

(db-exec [db :int sql :cstr] :ptr<void>)

execute a SQL statement that returns no rows.

Parameters
dbdatabase handle
sqlDDL or DML SQL string
Returns

(ok 0) on success; (err 0) on failure. Use sqlite-errmsg from sqlite/error on db for the error string.

Example
(db-exec db "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")

Since: P2

defn

db-prepare

(db-prepare [db :int sql :cstr] :ptr<void>)

compile a SQL string into a reusable prepared statement.

Parameters
dbdatabase handle
sqlSQL string with optional ?-placeholders for parameters
Returns

(ok stmt-handle) on success; (err 0) on failure. Finalize with stmt-finalize from sqlite/stmt when done.

Example
(let [r (db-prepare db "INSERT INTO users (name) VALUES (?)")]
    (if (ok? r)
      (let [stmt (ok-val r)]
        (stmt-bind-text stmt 1 "Alice")
        (stmt-step stmt)
        (stmt-finalize stmt))
      (println "prepare failed")))

Since: P2

defn

db-query

(db-query [db :int sql :cstr] :ptr<void>)

execute a SELECT and collect all rows as a list of alists.

Parameters
dbdatabase handle
sqlSELECT SQL string (no ?-placeholders; use db-prepare for parameters)
Returns

(ok row-list) on success; (err 0) on prepare failure. row-list is a cons list (nil if no rows). Each row is an alternating name/value alist; use row-get from sqlite/row. Rows are in reverse SQLite output order (last fetched row at list head).

Example
(let [r (db-query db "SELECT id, name FROM users")]
    (if (ok? r)
      (let [rows (ok-val r)]
        (for [row rows] (println (row-get row "name"))))
      (println "query failed")))

Since: P2

Internal definitions
__ok-- create an ok result wrapping integer value v.
__err-- create an err result wrapping integer error value e.
__ok?-- return true if a result is ok.
__ok-val-- extract the ok value from a result.
__nil-- return the empty list sentinel (0).
__cons-- prepend a value to a cons list; returns new cell as :int.
__db-open-raw-- open a database; returns sqlite3* as :int (0 on failure).
__db-close-raw-- close a SQLite3 database handle.
__db-exec-raw-- execute SQL; returns SQLITE error code (0 = SQLITE_OK).
__db-prepare-raw-- prepare SQL; returns sqlite3_stmt* as :int (0 on failure).
__ncols-- return column count for a prepared statement.
__colname-dup-- return a heap-copied column name at index i as :int.
__coltext-dup-- return a heap-copied column text value at index i as :int.
__step-raw-- step a statement; 1=row available, 0=done, -1=error.
__finalize-raw-- finalize a prepared statement.
__build-row-- build an alist from the current statement row position.
__collect-rows-- collect all result rows from stmt into a cons list.