(index ("open-database" 0) ("close-database" 484) ("database-closed?" 1214) ("prepare" 1349) ("prepare-transient" 1859) ("prepared-cache-size" 2043) ("step" 2515) ("reset" 3089) ("finalize" 3236) ("resurrect" 3588) ("bind" 3894) ("bind-parameters" 4405) ("bind-parameter-count" 4939) ("bind-parameter-name" 5224) ("column-name" 5618) ("column-names" 5881) ("column-count" 6095) ("column-type" 6286) ("column-data" 6849) ("row-data" 7735) ("row-alist" 8018) ("change-count" 8236) ("total-change-count" 8541) ("last-insert-rowid" 8865) ("call-with-database" 9098) ("sql" 9359) ("sql/transient" 9921) ("query" 10132) ("query*" 10786) ("fetch" 11418) ("fetch-row" 11418) ("fetch-all" 12201) ("fetch-rows" 12201) ("fetch-alist" 12545) ("fetch-alists" 12849) ("fetch-value" 13109) ("fetch-column" 13615) ("for-each-row" 13898) ("for-each-row*" 13898) ("map-rows" 14939) ("map-rows*" 14939) ("fold-rows" 15675) ("fold-rows*" 15675) ("first-column" 16713) ("exec" 17093) ("exec*" 17328) ("with-transaction" 18481) ("with-deferred-transaction" 18481) ("with-immediate-transaction" 18481) ("with-exclusive-transaction" 18481) ("rollback" 19658) ("commit" 19974) ("autocommit?" 20379) ("sqlite-exception?" 20548) ("sqlite-exception-status" 20678) ("sqlite-exception-message" 20848) ("error-code" 20983) ("error-message" 22686) ("raise-database-errors" 22809) ("set-busy-handler!" 23404) ("busy-timeout" 24308) ("register-scalar-function!" 24654) ("register-aggregate-function!" 25604) ("load-extension!" 27177) ("schema" 28394) ("print-schema" 28514) ("flush-cache!" 28731) ("finalized?" 28910) ("library-version" 29166))
(def (sig (procedure "(open-database filename)" (id open-database))) (p "Opens " (tt "filename") ", a sqlite3 database.  If no database exists, one is created transparently.  " (tt "filename") " may also be one of the following symbols:") (ul (li (tt "memory") ": a new database in memory unique to this connection") (li (tt "temp") " or " (tt "temporary") ": a new temporary database on disk, visible only to this connection")) (p "Returns a " (tt "#<sqlite-database>") " object."))
(def (sig (procedure "(close-database db)" (id close-database))) (p "Closes the database connection " (tt "db") ". All prepared statements are finalized before closing the database.") (p (b "Note.") "  Prior to 0.5.0, we did finalize transient statements as well, by walking the library's list of open statements before closing. Unfortunately, this included any statements prepared and owned by SQLite itself--for example, when using FTS--resulting in a double finalize and crash.") (p (b "Note.") " Prior to 0.7.0, transient (non-cached) statements had to be finalized manually before closing the database, typically with the query and exec high-level interface. Now all statements are finalized regardless of caching status."))
(def (sig (procedure "(database-closed? db)" (id database-closed?))) (p "Predicate that checks if database " (tt "db") " is closed."))
(def (sig (procedure "(prepare db sql)" (id prepare))) (p "Looks up a prepared statement in the statement cache.  If not found, it prepares a new statement.  Returns a statement object.") (p "Preparing a SQL statement consisting entirely of whitespace or comment is an error as of 0.5.0.") (p "Returns a " (tt "#<sqlite-statement>") " object.") (p (b "Note.") " Prior to 0.7.0, an exception was thrown if a statement we pulled from cache is currently running. Statements are no longer cached while running."))
(def (sig (procedure "(prepare-transient db sql)" (id prepare-transient))) (p "Same as " (tt "prepare") ", but bypasses the cache completely.  This procedure is subject to removal."))
(def (sig (parameter "(prepared-cache-size n) [default: 100]" (id prepared-cache-size))) (p "Sets the capacity of the prepared statement cache, in statements.") (p "When the cache reaches capacity and a new statement is prepared, the least recently used statement is finalized and drops off the cache.") (p "This setting takes effect only upon initiating a new connection, and the statement cache is unique per connection.") (p "Set capacity to 0 to disable the cache."))
(def (sig (procedure "(step statement)" (id step))) (p "Steps " (tt "statement") " and returns one of the following:") (ul (li (tt "'row") ": a row was returned (" (tt "SQLITE_ROW") ")") (li (tt "'done") ": the statement is done executing (" (tt "SQLITE_DONE") ")") (li (tt "#f") ": step failed due to error")) (p (tt "#f") " is only ever returned if raising exceptions is disabled. Completion of execution is still considered a \"success\" and so the true value " (tt "'done") " is returned, rather than " (tt "#f") ".") (p "Upon database error, the statement is reset."))
(def (sig (procedure "(reset statement)" (id reset))) (p "Resets " (tt "statement") " to the beginning of its program, returning the statement."))
(def (sig (procedure "(finalize statement)" (id finalize))) (p "Finalize " (tt "statement") ".  Usually, the statement is reset and added to the statement cache.  If the statement is transient, or cannot be cached for some reason, it is finalized immediately.") (p "Finalizing a finalized statement, or a statement on a closed database, is a no-op."))
(def (sig (procedure "(resurrect statement)" (id resurrect))) (p "Resurrects a previously finalized statement " (tt "s") " by pulling it from the cache, or if it was not cached, by re-preparing the original SQL associated with the statement.") (p "Returns " (tt "s") ", which is also modified in place."))
(def (sig (procedure "(bind statement index value)" (id bind))) (p "Bind parameter at " (tt "index") " of " (tt "statement") " to " (tt "value") ", and returns " (tt "statement") ".  The variable " (tt "index") " may be an integer (the first parameter is 1, not 0) or a string for a named parameter --- for example, \"$key\", \":key\" or \"@key\".  For named parameters, the " (tt "$") ", " (tt ":") " or " (tt "@") " must be included in the string.  A reference to an invalid index will throw an exception."))
(def (sig (procedure "(bind-parameters statement . parameters)" (id bind-parameters))) (p "Convenience function which binds " (tt "parameters") " to indices 1 .. n, in order.  Keyword arguments are permitted; " (tt "foo: 3") " will bind 3 to parameter " (tt ":foo") ".") (p "The number of parameters must match the statement's " (tt "bind-parameter-count") ", or an error will be signaled.  Also, all keywords used must be valid parameter names.") (p "Mixing named and anonymous arguments in the same statement is not recommended."))
(def (sig (procedure "(bind-parameter-count statement)" (id bind-parameter-count))) (p "Returns the number of bound parameter slots in this prepared statement.  If numbered parameters are present, gaps may be left in the sequence.  Named parameters count in the slot total as well."))
(def (sig (procedure "(bind-parameter-name statement i)" (id bind-parameter-name))) (p "Returns a string representing the name of the bound parameter at index " (tt "i") ", or " (tt "#f") " if the parameter is anonymous or is out of range.") (p "The string includes the parameter name prefix; for example " (tt "\":foo\"") ", " (tt "\"$foo\"") ", " (tt "\"@foo\"") " or " (tt "\"?nnn\"") "."))
(def (sig (procedure "(column-name statement index)" (id column-name))) (p "Return the name of the specified result set column as a symbol.  The statement need not have been stepped to retrieve column names or column count.") (pre "(column-name s 1)\n; => key"))
(def (sig (procedure "(column-names statement)" (id column-names))) (p "Convenience function which returns a list of all column names for the result set, in order.") (pre "(column-names s)\n; => (rowid key val)"))
(def (sig (procedure "(column-count statement)" (id column-count))) (p "Return the number of columns in the result set returned by the prepared statement.") (pre "(column-count s)\n; => 3"))
(def (sig (procedure "(column-type statement index)" (id column-type))) (p "Returns the type of the indexed column in the current row.  SQLite is dynamically typed and the column types are unique to each row.") (table (tr (th "Symbol") (th "Database type")) "\n" (tr (td "integer") (td "SQLITE_INTEGER")) "\n" (tr (td "float") (td "SQLITE_FLOAT")) "\n" (tr (td "text") (td "SQLITE_TEXT")) "\n" (tr (td "blob") (td "SQLITE_BLOB")) "\n" (tr (td "null") (td "SQLITE_NULL"))) (pre "(map (lambda (i) (column-type s i))\n     (list 0 1 2))\n; => (integer text text)"))
(def (sig (procedure "(column-data statement index)" (id column-data))) (p "Returns the data from the indexed column in the current row.") (table (tr (th "Column type") (th "Scheme type")) "\n" (tr (td "integer") (td "Exact or inexact number")) "\n" (tr (td "float") (td "Inexact number")) "\n" (tr (td "text") (td "String")) "\n" (tr (td "blob") (td "Blob")) "\n" (tr (td "null") (td "'()"))) (pre "(map (lambda (i) (column-data s i))\n     (list 0 1 2))\n; => (1 \"foo\" \"bar\")") (p (tt "integer") " values are retrieved with " (tt "sqlite3_column_int64") ".  On a 32-bit machine, values outside the signed 31-bit fixnum range are returned as inexact numbers.  On a 64-bit machine, values outside the signed 63-bit fixnum range are returned as inexact numbers.  Note that inexact numbers are 64-bit floating point values, and can only accurately represent 53 bits of an integer."))
(def (sig (procedure "(row-data statement)" (id row-data))) (p "Retrieve a list of column data from the current row.  If the last execution of " (tt "step") " returned " (tt "done") ", a NULL value will be returned for every column.") (pre "(row-data s)\n; => (1 \"foo\" \"bar\")"))
(def (sig (procedure "(row-alist statement)" (id row-alist))) (p "Retrieve an alist mapping column names to column data for the current row.") (pre "(row-alist s)\n; => ((rowid . 1) (key . \"foo\") (val . \"bar\"))"))
(def (sig (procedure "(change-count db)" (id change-count))) (p "Returns the number of database rows that were changed or inserted or deleted by the most recently completed SQL statement, not including triggers, as in " (link "http://www.sqlite.org/capi3ref.html#sqlite3_changes" "sqlite3_changes") "."))
(def (sig (procedure "(total-change-count db)" (id total-change-count))) (p "Returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the database connection was opened, including triggers, as in " (link "http://www.sqlite.org/capi3ref.html#sqlite3_total_changes" "sqlite3_total_changes") "."))
(def (sig (procedure "(last-insert-rowid db)" (id last-insert-rowid))) (p "Get the ROWID of the last successful INSERT, as in " (link "http://www.sqlite.org/capi3ref.html#sqlite3_last_insert_rowid" "sqlite3_last_insert_rowid") "."))
(def (sig (procedure "(call-with-database filename proc)" (id call-with-database))) (p "Opens a database, calls " (tt "proc") " with the database object and then closes the database on return.  If an error occurs in proc, the database is closed immediately."))
(def (sig (procedure "(sql db sql-str)" (id sql))) (p "Creates a statement object associated with the database connection " (tt "db") " and the SQL " (tt "sql-str") ".  Preparation of the statement is deferred until needed.  This is a normal statement in every respect except that it must be " (tt "resurrect") "ed before it can be used.") (p (tt "sql") " is recommended over " (tt "prepare") " when using the " (tt "query") " / " (tt "exec") " interface so that you can declare your statements without compiling them until and unless they are actually used."))
(def (sig (procedure "(sql/transient db sql-str)" (id sql/transient))) (p "Equivalent to " (tt "(sql db sql-str)") ", but the statement will never be cached; it is prepared anew every time it is resurrected."))
(def (sig (procedure "(query proc s . args)" (id query))) (p "Resurrects statement " (tt "s") ", binds " (tt "args") " to " (tt "s") " using " (tt "bind-parameters") ", performs a " (tt "query*") " and " (tt "finalize") "s the statement.") (p (tt "query") " is the usual way to perform a query unless you need to bind arguments manually, need more control or are using the low-level interface, in which case you can use " (tt "query*") " if desired.") (p "You typically call " (tt "query") " or " (tt "query*") " with one of the provided result fetching procedures; you can also pass your own procedure to perform whichever operations you would like."))
(def (sig (procedure "(query* proc s)" (id query*))) (p "Calls " (tt "(proc s)") " and resets the statement " (tt "s") " immediately afterward, to avoid locking the database.  If an exception occurs during proc, the statement will still be reset.  The statement is not reset before execution.") (p "The entire purpose of " (tt "query*") " is to ensure a statement is reset after it is executed.  If a statement were left in a running state --- for example, if an uncaught exception occurs during proc, or you simply do not exhaust its result set --- then the database will be locked for writing until the statement is finalized."))
(def (sig (procedure "(fetch s)" (id fetch)) (procedure "(fetch-row s)" (id fetch-row))) (p "Fetch the next row of the result set.  This is the equivalent to performing a " (tt "step") " followed by a " (tt "row-data") " call, and works with both the high- and low-level interfaces.  If the statement has finished executing, fetch returns '().  These query procedures do not reset the statement before or afterward; one may do so using " (tt "reset") " or " (tt "query") ".") (p (tt "fetch") " and " (tt "fetch-row") " are aliases.") (pre "(fetch s)\n; => (1 \"foo\" \"bar\")\n(fetch s)\n; => (2 \"baz\" \"quux\")\n(fetch s)\n; => ()\n(fetch s)\n; => error\n(query fetch s)\n; => (1 \"foo\" \"bar\")\n(query fetch s)\n; => (1 \"foo\" \"bar\")\n(fetch s)\n; => (1 \"foo\" \"bar\")"))
(def (sig (procedure "(fetch-all s)" (id fetch-all)) (procedure "(fetch-rows s)" (id fetch-rows))) (p "Calls " (tt "fetch") " until it returns " (tt "'()") ", and collects the result into a list.  " (tt "fetch-all") " and " (tt "fetch-rows") " are aliases.") (pre "(query fetch-all s)\n; => ((1 \"foo\" \"bar\")\n      (2 \"baz\" \"quux\"))"))
(def (sig (procedure "(fetch-alist s)" (id fetch-alist))) (p "Fetch the next row of the result set and return an alist mapping symbolic row names to values.  Equivalent to " (tt "step") " followed by " (tt "row-alist") ".") (pre "(query fetch-alist s)\n; ((rowid . 1) (key . \"foo\") (val . \"bar\"))"))
(def (sig (procedure "(fetch-alists s)" (id fetch-alists))) (p "Fetches all rows and returns a list of alists, one per row.") (pre "(query fetch-alists s)\n; (((rowid . 1) (key . \"foo\") (val . \"bar\"))\n;  ((rowid . 2) (key . \"baz\") (val . \"quux\")))"))
(def (sig (procedure "(fetch-value s)" (id fetch-value))) (p "Fetches and returns only the first value (first column) of the next row, or " (tt "#f") " if the row contained no column data.  Equivalent to using " (tt "first-column") " on the result of a " (tt "fetch") ", but does not materialize the entire row.") (pre "(query fetch-value\n       (sql db \"select key from cache\"))\n; => \"foo\"") (pre "(query fetch-value\n       (sql db \"select key from cache where key=?\") \"nosuchkey\")\n; => #f"))
(def (sig (procedure "(fetch-column s)" (id fetch-column))) (p "Fetches all rows and returns a list containing the first column of each, or " (tt "'()") " if there was no column data.") (pre "(query fetch-column\n       (sql db \"select key from cache\"))\n; => (\"foo\" \"bar\")"))
(def (sig (procedure "(for-each-row proc)" (id for-each-row)) (procedure "(for-each-row* proc)" (id for-each-row*))) (p "Returns a procedure suitable for passing to " (tt "query") ", taking one argument, a statement object.") (p "The procedure will call fetch once for each row and call your callback as " (tt "(proc row)") ", discarding the results.") (pre "(query (for-each-row\n         (lambda (x) (print \"row: \" x)))\n       s)\n; row: (1 foo bar)\n; row: (2 baz quux)\n; => undefined") (p (tt "for-each-row*") " behaves like " (tt "for-each-row") ", but your callback is invoked with one argument for each column value.  For example, these produce equivalent results:") (pre "(query (for-each-row (match-lambda ((name sql)\n                        (print \"table: \" name \" sql: \" sql \";\"))))\n       (sql db \"select name, sql from sqlite_master;\"))\n(query (for-each-row* (lambda (name sql)\n                        (print \"table: \" name \" sql: \" sql \";\")))\n       (sql db \"select name, sql from sqlite_master;\"))"))
(def (sig (procedure "(map-rows proc)" (id map-rows)) (procedure "(map-rows* proc)" (id map-rows*))) (p "Return a procedure suitable for passing to " (tt "query") ", taking one argument, a statement object.") (p "The procedure will call fetch once for each row and call " (tt "(proc row)") ", collecting the results into a list, in order.") (pre "(query (map-rows car) s)\n; => (1 2)") (p "Another example; these two produce equivalent results:") (pre "(query (map-rows car) (sql db \"select name, sql from sqlite_master;\"))\n(map car (query fetch-all (sql db \"select name, sql from sqlite_master;\")))") (p (tt "map-rows*") " behaves like " (tt "map-rows") ", but your callback is invoked with one argument for each column value."))
(def (sig (procedure "(fold-rows kons knil)" (id fold-rows)) (procedure "(fold-rows* kons knil)" (id fold-rows*))) (p "Calls " (tt "(kons x xs)") " once for each row, where " (tt "x") " is the current row data and " (tt "xs") " is the seed (previous return value from " (tt "kons") ").  The initial seed is " (tt "knil") ".") (pre "(query (fold-rows cons '()) s)\n; => ((2 \"baz\" \"quux\") (1 \"foo\" \"bar\"))") (pre ";; sum the returned rowids\n(query (fold-rows (lambda (x xs) (+ (car x) xs))\n                  0)\n       s)\n; => 3") (pre ";; that was contrived, you should actually do the sum in the database\n(car (query fetch (sql db \"select sum(rowid) from mytable;\")))\n; => 3") (p (tt "fold-rows*") " behaves like " (tt "fold-rows") ", but the " (tt "kons") " callback is invoked with one column for each argument value, plus the seed as the last argument -- for example, as " (tt "(kons x y z seed)") ".  This turns out to be quite inefficient and makes little sense, so " (tt "fold-rows*") " is deprecated as of 0.4.2."))
(def (sig (procedure "(first-column row)" (id first-column))) (p "Returns the first column of " (tt "row") ", or " (tt "#f") " if the row is '().") (pre "(first-column (query fetch (sql db \"select sum(rowid) from mytable;\")))\n; => 3") (p "You can also use " (tt "fetch-value") " here instead:") (pre "(query fetch-value (sql db \"select sum(rowid) from mytable;\"))\n; => 3"))
(def (sig (procedure "(exec s . args)" (id exec))) (p "Resurrects statement " (tt "s") ", binds " (tt "args") " to " (tt "s") " using " (tt "bind-parameters") ", performs an " (tt "exec*") ", and " (tt "finalize") "s the statement."))
(def (sig (procedure "(exec* s)" (id exec*))) (p "Executes statement " (tt "sql") ", returning the number of changes (if the result set has no columns as in " (tt "INSERT") ", " (tt "DELETE") ", " (tt "UPDATE") ") or the first row (if column data is returned as in " (tt "SELECT") ").  In the latter case, it is like performing a (query* fetch s), but is more efficient.") (p "Resurrection is omitted, as it would wipe out any bindings.  Reset is NOT done beforehand; it is cheap, but the user must reset before a bind anyway.") (p "The statement is always reset afterward, even if an exception occurs, to avoid locking the database.  Note however that an internal error when retrieving column data (such as a string > 16MB) will leave the statement open -- this is a flaw in the current implementation.") (pre "(exec (sql db \"INSERT INTO cache(key, val) values(?, ?);\")\n      \"chicken\" 4)\n; => 1\n(exec (sql db \"SELECT * FROM cache WHERE key = ?;\")\n      \"chicken\")\n; => (\"chicken\" \"4\")\n(first-column (exec (sql db \"SELECT val FROM cache;\")))\n; => \"bar\"\n(first-column (exec (sql db \"SELECT val FROM cache;\")))\n; => \"bar\""))
(def (sig (procedure "(with-transaction db thunk #!optional (type 'deferred))" (id with-transaction)) (procedure "(with-deferred-transaction db thunk)" (id with-deferred-transaction)) (procedure "(with-immediate-transaction db thunk)" (id with-immediate-transaction)) (procedure "(with-exclusive-transaction db thunk)" (id with-exclusive-transaction))) (p "Executes " (tt "thunk") " within a " (tt "BEGIN TRANSACTION") " block, and returns the value of " (tt "thunk") ".  The optional " (tt "type") " may be one of the symbols " (tt "deferred") ", " (tt "immediate") ", or " (tt "exclusive") ".  You may also use the named convenience functions instead of the optional parameter.") (p "The transaction is committed with " (tt "(commit db)") " if " (tt "thunk") " returns a true value.  Escaping or re-entering the dynamic extent of " (tt "thunk") " will not commit or rollback the in-progress transaction.  However, if an exception occurs during " (tt "thunk") ", or " (tt "thunk") " returns " (tt "#f") ", or the commit fails, the transaction will be rolled back with " (tt "(rollback db)") ".  If this rollback fails, that is a critical error and you should likely abort."))
(def (sig (procedure "(rollback db)" (id rollback))) (p "Rollback current transaction.  Unconditionally resets running queries before doing so, as rollback would fail if read or read/write queries are running.  Successful rollback returns a true value.  Rolling back in autocommit mode also returns a true value."))
(def (sig (procedure "(commit db)" (id commit))) (p "Commit current transaction.  This does not rollback running queries, because running read queries are acceptable, and the behavior in the presence of pending write statements is unclear.  If the commit fails, you can always rollback, which will reset the pending queries.") (p "Successful commit, or commit in autocommit mode, returns a true value."))
(def (sig (procedure "(autocommit? db)" (id autocommit?))) (p "Returns " (tt "#t") " if the database is in autocommit mode, or " (tt "#f") " if within a transaction."))
(def (sig (procedure "(sqlite-exception? e)" (id sqlite-exception?))) (p "Is " (tt "e") " an exception raised by the database?"))
(def (sig (procedure "(sqlite-exception-status e)" (id sqlite-exception-status))) (p "Get the database error code as a symbol.  See " (tt "error-code") " for details."))
(def (sig (procedure "(sqlite-exception-message e)" (id sqlite-exception-message))) (p "Get the database error message as a string."))
(def (sig (procedure "(error-code db)" (id error-code))) (p "Returns the last database error code as a symbol.") (table (tr (th "Symbol            ") (th "C error code")) "\n" (tr (td "ok                ") (td "SQLITE_OK")) "\n" (tr (td "error          ") (td "SQLITE_ERROR")) "\n" (tr (td "internal    ") (td "SQLITE_INTERNAL")) "\n" (tr (td "permission\t    ") (td "SQLITE_PERM")) "\n" (tr (td "abort          ") (td "SQLITE_ABORT")) "\n" (tr (td "busy            ") (td "SQLITE_BUSY")) "\n" (tr (td "locked        ") (td "SQLITE_LOCKED")) "\n" (tr (td "no-memory  ") (td "SQLITE_NOMEM")) "\n" (tr (td "read-only  ") (td "SQLITE_READONLY")) "\n" (tr (td "interrupt  ") (td "SQLITE_INTERRUPT")) "\n" (tr (td "io-error    ") (td "SQLITE_IOERR")) "\n" (tr (td "corrupt      ") (td "SQLITE_CORRUPT")) "\n" (tr (td "not-found  ") (td "SQLITE_NOTFOUND")) "\n" (tr (td "full            ") (td "SQLITE_FULL")) "\n" (tr (td "cant-open  ") (td "SQLITE_CANTOPEN")) "\n" (tr (td "protocol    ") (td "SQLITE_PROTOCOL")) "\n" (tr (td "empty          ") (td "SQLITE_EMPTY")) "\n" (tr (td "schema        ") (td "SQLITE_SCHEMA")) "\n" (tr (td "too-big      ") (td "SQLITE_TOOBIG")) "\n" (tr (td "constraint   ") (td "SQLITE_CONSTRAINT")) "\n" (tr (td "mismatch    ") (td "SQLITE_MISMATCH")) "\n" (tr (td "misuse        ") (td "SQLITE_MISUSE")) "\n" (tr (td "no-lfs        ") (td "SQLITE_NOLFS")) "\n" (tr (td "authorization\t ") (td "SQLITE_AUTH")) "\n" (tr (td "format        ") (td "SQLITE_FORMAT")) "\n" (tr (td "range          ") (td "SQLITE_RANGE")) "\n" (tr (td "not-a-database\t") (td "SQLITE_NOTADB")) "\n" (tr (td "row              ") (td "SQLITE_ROW")) "\n" (tr (td "done            ") (td "SQLITE_DONE"))))
(def (sig (procedure "(error-message db)" (id error-message))) (p "Returns the last database error message as a string."))
(def (sig (parameter "(raise-database-errors BOOLEAN) [default: #t]" (id raise-database-errors))) (p "Set to " (tt "#t") " to raise an exception on database error, " (tt "#f") " to return a false value.  Note that certain critical errors, such as \"misuse of interface\" and arity mismatches of bound parameters will raise exceptions regardless.  Procedures in this extension that utilize the low-level interface are written to work correctly with both " (tt "#f") " return values and errors.") (p "Disabling raising of database errors is intended for experts and this option may be removed."))
(def (sig (procedure "(set-busy-handler! db proc)" (id set-busy-handler!))) (p "Register the busy handler " (tt "proc") " on the open connection " (tt "db") "; the handler will be called repeatedly when a " (tt "prepare") " or " (tt "step") " operation returns SQLITE_BUSY.  It is passed the two arguments " (tt "(db count)") ", which are the associated database connection and the number of times this busy handler has been invoked so far for this operation. The procedure should return " (tt "#f") " to stop retrying and have the operation return a BUSY error to the caller, or " (tt "#t") " if the busy operation should be retried.") (p "By default, no busy handler is registered.  Busy handlers are unique to each connection and must be registered after the connection is open.") (pre "(call-with-database\n (lambda (db)\n  (set-busy-handler! db (busy-timeout 10000)) ; 10 second timeout\n  ...))"))
(def (sig (procedure "(busy-timeout ms)" (id busy-timeout))) (p "Return a procedure suitable for use in set-busy-handler!, implementing a spinning busy timeout using the SQLite3 busy wait algorithm.  This handler will wait up to " (tt "ms") " milliseconds total before giving up. Other threads may be scheduled while this one is busy-waiting."))
(def (sig (procedure "(register-scalar-function! db name nargs proc)" (id register-scalar-function!))) (p "Register a user-defined scalar function " (tt "name") " of arity " (tt "nargs") ". " (tt "nargs") " may range from 0 to 127, or -1 to define a function taking any number of arguments.  You may define multiple functions with differing numbers of arguments.  Defining a function with the same " (tt "nargs") " as an existing function will redefine it, even built-in functions.") (p (tt "proc") " should be a function taking " (tt "nargs") " arguments; to delete an existing function, set proc to " (tt "#f") ".  The return value is used as the value of the scalar function.  If an error occurs during the function, it is signaled as a database error.") (p "Functions must be defined anew for every database connection.") (p "Be very careful when combining " (int-link "#Callbacks and SRFI-18" "user-defined functions and SRFI-18 threads") "."))
(def (sig (procedure "(register-aggregate-function! db name nargs pstep #!optional (seed 0) (pfinal identity))" (id register-aggregate-function!))) (p "Register a user-defined aggregate function " (tt "name") " of arity " (tt "nargs") ". " (tt "nargs") " may range from 0 to 127, or -1 to define a function taking any number of arguments.  You may define multiple functions with differing numbers of arguments.  Defining a function with the same " (tt "nargs") " as an existing function will redefine it, even built-in functions.") (p (tt "seed") " is the initial seed passed to this particular invocation of the aggregate function.  At every step, " (tt "pstep") " is invoked as " (tt "(pstep seed arg1 ... argn)") " and its return value becomes the next seed.  Finally, " (tt "(pfinal seed)") " is invoked to do any final transformation necessary on the seed.  (For example, if " (tt "seed") " is a record, you may need to pull out and return the relevant data.)  The return value of " (tt "pfinal") " is used as the value of the aggregate function. If an error occurs during " (tt "pstep") " or " (tt "pfinal") ", it is signaled as a database error.") (p (tt "pstep") " should be a function taking " (tt "nargs") " arguments.  To delete an existing aggregate function, set pstep to " (tt "#f") ".  In this case the values of " (tt "seed") " and " (tt "pfinal") " are ignored.") (p "Functions must be defined anew for every database connection.") (p "Be very careful when combining " (int-link "#Callbacks and SRFI-18" "user-defined functions and SRFI-18 threads") "."))
(def (sig (procedure "(load-extension! db filename #!optional entry-point)" (id load-extension!))) (p "Loads a SQLite extension library from " (tt "filename") " and initializes it by calling " (tt "entry-point") ", a string containing the name of a C function. If " (tt "filename") " is not found, it will try " (tt "filename.so") ", " (tt "filename.dylib") " or " (tt "filename.dll") " as appropriate for the platform. If " (tt "entry-point") " is omitted or " (tt "#f") ", SQLite guesses the entry point name from the filename. See the documentation for " (link "https://sqlite.org/c3ref/load_extension.html" "sqlite3_load_extension") " for further details.") (p "As an example, see " (link "https://github.com/ursetto/sql-de-lite/blob/70833b5aae10de136963b0c488fda2e974a3bcef/tests/run.scm#L1199" "tests/run.scm") " and " (link "https://github.com/ursetto/sql-de-lite/blob/70833b5aae10de136963b0c488fda2e974a3bcef/tests/rot13.c" "tests/rot13.c") " in the egg source, which define and call a rot13 function.") (p (b "Warning.") " This allows arbitrary code to be loaded and executed from disk at runtime, and could conceivably cause the extension's state to get out of sync. Please proceed with extreme caution."))
(def (sig (procedure "(schema db)" (id schema))) (p "Returns a list of SQL statements making up the database schema."))
(def (sig (procedure "(print-schema db)" (id print-schema))) (p "Displays the database schema to the current output port; the result is similar to using " (tt ".schema") " at the " (tt "sqlite3") " command prompt."))
(def (sig (procedure "(flush-cache! db)" (id flush-cache!))) (p "Flush the prepared statement cache. All cached statements will be finalized (in the underlying library sense)."))
(def (sig (procedure "(finalized? statement)" (id finalized?))) (p "Returns " (tt "#t") " if the statement is finalized or has never been prepared.") (pre "(finalized? (sql db \"select 1;\"))     ; => #t\n(finalized? (prepare db \"select 1;\")) ; => #f"))
(def (sig (string "library-version" (id library-version))) (p "A string representing the SQLite3 library version (e.g. \"3.6.11\")."))
