source: project/wiki/eggref/5/sqlite3pth @ 37636

Last change on this file since 37636 was 36410, checked in by svnwiki, 17 months ago

Anonymous wiki edit for IP [185.220.101.44]:

File size: 3.3 KB
Line 
1== sqlite3pth
2
3== Overview
4
5* Run SQLite queries asynchronously in pthreads. Supports calling Scheme from SQLite's VFS to supply database block storage.
6
7* Offloads the SQL work to pthreads; the chicken thread is free to continue.
8
9* VFS support allows sqlite3 to call back into chicken to supply blocks of the data base. (This is a breakout from ball.askemos.org - where the VFS is used to implement versioning and replication of the databases.)
10
11* Safe to be used with CHICKEN's srfi-18 threads.  (I.e., does {{NOT}} use {{define-external}}.)
12
13== Requirements
14
15[[sql-null]], [[pthreads]], [[srfi-18]], [[srfi-34]], [[llrb-tree]], [[miscmacros]], [[srfi-1]]
16
17== API
18
19<procedure>(:sql-result: string --> (or false fixnum))</procedure>
20convert field name to index
21
22<procedure>(: sqlite3-prepare ((struct <sqlite3-database>) string --> (struct <sqlite3-statement>)))</procedure>
23
24Prepare query.
25
26<procedure>(: sqlite3-exec ((struct <sqlite3-database>) (or string (struct <sqlite3-statement>)) #!rest -> :sql-result:))</procedure>
27
28Execute statement or prepared query.
29
30<procedure>(: sqlite3-call-with-transaction ((struct <sqlite3-database>) (procedure ((procedure (string #!rest) :sql-result:)) :sql-result:) -> :sql-result:))</procedure>
31
32Call procedure in a sqlite transaction.
33
34<procedure>sqlite3-call-test/set</procedure>
35questionable, undocumented
36
37<procedure>(: sqlite3-close ((struct <sqlite3-database>) -> . *))</procedure>
38
39Close database.
40
41<procedure>sqlite3-interrupt!</procedure>
42
43Call sqlite_interrupt to abort running query.
44
45<procedure>sql-result?</procedure>
46
47Test predicate for the sql result type.
48
49<procedure>(sql-value RESULT ROW FIELD) --> *</procedure>
50
51Result Accessor.
52
53<procedure>(: sql-ref (:sql-result: (or boolean fixnum) (or boolean fixnum string symbol) --> *))</procedure>
54
55<procedure>(: sql-fold (:sql-result: (procedure ((procedure (fixnum) *) *) *) * -> *))</procedure>
56
57Fold procedure over results.
58
59<procedure>sqlite3-open</procedure>
60<procedure>sqlite3-close</procedure>
61<procedure>(: sqlite3-open-restricted (string #!optional string vector --> (struct <sqlite3-database>)))</procedure>
62Restricted open optionally with VFS.  SQL may not attach other files.
63optional string requests sqlite3 VFS, vector holds VFS callbacks
64
65<procedure>(: sqlite3-open-restricted-ro (string #!optional string vector --> (struct <sqlite3-database>)))</procedure>
66Restricted open read only optionally with VFS.  SQL may not attach other files.
67optional string requests sqlite3 VFS, vector holds VFS callbacks
68
69=== Accessors
70
71    sqlite3-database-name
72    sqlite3-changes
73    sqlite3-statement?
74    sqlite3-statement-name
75
76    sqlite3-error? sqlite3-error-code sqlite3-error-args
77
78<procedure>sqlite3-error-db-locked?</procedure>
79
80=== debug aid
81<procedure>(sqlite3-debug-statements FLAG)</procedure>
82
83Log queries.
84
85== VFS Interface
86
87The VFS allows to call back to Chicken when sqlite need to read data.
88
89This is currently only lightly documented in
90[[https://github.com/0-8-15/sqlite3pth/blob/master/tests/run.scm|tests/run.scm]].
91
92
93== Examples
94
95    (define db (sqlite-open "path"))
96    (sqlite3-exec db "select 1") ; 1
97    (sqlite3-exec db (sqlite3-prepare db "select ?1") 1) ; 1
98
99
100== About this egg
101
102=== Source Code
103
104Currently [[https://github.com/0-8-15/sqlite3pth/|maintained here]] at github.
105
106=== Author
107
108Jörg F. Wittenberger
109
110=== License
111
112BSD
Note: See TracBrowser for help on using the repository browser.