anil.recoil.org
This a test repository for the unpac monorepo tool
1(**************************************************************************)
2(* Copyright © 2010- Markus Mottl *)
3(* Copyright © 2007-2010 Jane Street Holding, LLC *)
4(* Copyright © 2005-2007 Christian Szegedy *)
5(* *)
6(* Permission is hereby granted, free of charge, to any person *)
7(* obtaining a copy of this software and associated documentation files *)
8(* (the "Software"), to deal in the Software without restriction, *)
9(* including without limitation the rights to use, copy, modify, merge, *)
10(* publish, distribute, sublicense, and/or sell copies of the Software, *)
11(* and to permit persons to whom the Software is furnished to do so, *)
12(* subject to the following conditions: *)
13(* *)
14(* The above copyright notice and this permission notice shall be *)
15(* included in all copies or substantial portions of the Software. *)
16(* *)
17(* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, *)
18(* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES *)
19(* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND *)
20(* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS *)
21(* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN *)
22(* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN *)
23(* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE *)
24(* SOFTWARE. *)
25(**************************************************************************)
26
27(** API for Sqlite 3.* databases *)
28
29(** {2 Exceptions} *)
30
31exception InternalError of string
32(** [InternalError reason] is raised when the bindings detect an
33 unknown/unsupported situation. *)
34
35exception Error of string
36(** [Error reason] is raised when some SQL operation is called on a nonexistent
37 handle and the functions does not return a return code, or if there is no
38 error code corresponding to this error. Functions returning return codes
39 communicate errors by returning the specific error code. *)
40
41exception RangeError of int * int
42(** [RangeError (index, maximum)] is raised if some column or bind operation
43 refers to a nonexistent column or binding. The first entry of the returned
44 tuple is the specified index, the second is the limit which was violated. *)
45
46exception DataTypeError of string
47(** [DataTypeError msg] is raised when you attempt to convert a [Data.t]
48 structure to an object via an invalid conversion. *)
49
50exception SqliteError of string
51(** [SqliteError err_msg] is raised after calling [Rc.check] on a return code
52 that does not indicate success. *)
53
54(** {2 Library Information} *)
55
56val sqlite_version : unit -> int
57(** [sqlite_version ()]
58 @return
59 the version of the SQLite3 library being used, in format [3XXXYYY] where
60 [XXX] is the minor version and [YYY] is the patch level. For example,
61 [3030001] for 3.30.1. *)
62
63val sqlite_version_info : unit -> string
64(** [sqlite_version_info ()]
65 @return
66 the version of the SQLite3 library being used in a human-readable string.
67*)
68
69(** {2 Types} *)
70
71type db
72(** Database handle. Used to store information regarding open databases and the
73 error code from the last operation if the function implementing that
74 operation takes a database handle as a parameter.
75
76 NOTE: database handles are closed (see {!db_close}) automatically when they
77 are reclaimed by the GC unless they have already been closed earlier by the
78 user. It is good practice to manually close database handles to free
79 resources as quickly as possible.
80
81 @see <https://sqlite.org/threadsafe.html>
82 about thread safety when accessing database handles and also consider
83 using the [mutex] flag with {!db_open} if necessary. *)
84
85type stmt
86(** Compiled statement handle. Stores information about compiled statements
87 created by the [prepare] or [prepare_tail] functions.
88
89 @see <https://sqlite.org/threadsafe.html>
90 about thread safety when accessing statement handles. *)
91
92type header = string
93(** Type of name of a column returned by queries. *)
94
95type headers = header array
96(** Type of names of columns returned by queries. *)
97
98type row = string option array
99(** Type of row data (with potential NULL-values) *)
100
101type row_not_null = string array
102(** Type of row data (without NULL-values) *)
103
104(** {2 Return codes} *)
105
106module Rc : sig
107 type unknown
108 (** Type of unknown return codes *)
109
110 val int_of_unknown : unknown -> int
111 (** [int_of_unknown n] converts unknown return code [rc] to an integer. *)
112
113 (** Type of return codes from failed or successful operations. *)
114 type t =
115 | OK
116 | ERROR
117 | INTERNAL
118 | PERM
119 | ABORT
120 | BUSY
121 | LOCKED
122 | NOMEM
123 | READONLY
124 | INTERRUPT
125 | IOERR
126 | CORRUPT
127 | NOTFOUND
128 | FULL
129 | CANTOPEN
130 | PROTOCOL
131 | EMPTY
132 | SCHEMA
133 | TOOBIG
134 | CONSTRAINT
135 | MISMATCH
136 | MISUSE
137 | NOFLS
138 | AUTH
139 | FORMAT
140 | RANGE
141 | NOTADB
142 | ROW
143 | DONE
144 | UNKNOWN of unknown
145
146 val to_string : t -> string
147 (** [to_string rc] converts return code [rc] to a string. *)
148
149 val check : t -> unit
150 (** [check rc] raises an exception if [rc] does not correspond to a return
151 code indicating success. *)
152
153 val is_success : t -> bool
154 (** [is_success rc]
155 @return
156 [true] if [rc] indicates success ([OK] or [DONE]), [false] otherwise. *)
157end
158
159(** {2 Column data types} *)
160
161module Data : sig
162 (** Type of columns *)
163 type t =
164 | NONE
165 | NULL
166 | INT of int64
167 | FLOAT of float
168 | TEXT of string
169 | BLOB of string
170
171 val opt_text : string option -> t
172 (** [opt_text value] converts [value] to a [Data.t] [TEXT] value, converting
173 [None] to SQLite [NULL]. *)
174
175 val opt_int : int option -> t
176 (** [opt_int value] converts [value] to a [Data.t] [INT] value, converting
177 [None] to SQLite [NULL]. *)
178
179 val opt_nativeint : nativeint option -> t
180 (** [opt_nativeint value] converts [value] to a [Data.t] [INT] value,
181 converting [None] to SQLite [NULL]. *)
182
183 val opt_int32 : int32 option -> t
184 (** [opt_int32 value] converts [value] to a [Data.t] [INT] value, converting
185 [None] to SQLite [NULL]. *)
186
187 val opt_int64 : int64 option -> t
188 (** [opt_int64 value] converts [value] to a [Data.t] [INT] value, converting
189 [None] to SQLite [NULL]. *)
190
191 val opt_float : float option -> t
192 (** [opt_float value] converts [value] to a [Data.t] [FLOAT] value, converting
193 [None] to SQLite [NULL]. *)
194
195 val opt_bool : bool option -> t
196 (** [opt_bool value] converts [value] to a [Data.t] [INT] value, converting
197 [None] to SQLite [NULL]. *)
198
199 val to_string_exn : t -> string
200 (** [to_string_exn data] converts [TEXT] and [BLOB] [data] to a string.
201
202 @raise DataTypeError if [data] is invalid. *)
203
204 val to_int_exn : t -> int
205 (** [to_int_exn data] converts [INT] [data] to an int.
206
207 @raise DataTypeError if [data] is invalid.
208 @raise Failure if the integer conversion over- or underflows. *)
209
210 val to_nativeint_exn : t -> nativeint
211 (** [to_nativeint_exn data] converts [INT] [data] to a nativeint.
212
213 @raise DataTypeError if [data] is invalid.
214 @raise Failure if the integer conversion over- or underflows. *)
215
216 val to_int32_exn : t -> int32
217 (** [to_int32_exn data] converts [INT] [data] to an int32.
218
219 @raise DataTypeError if [data] is invalid.
220 @raise Failure if the integer conversion over- or underflows. *)
221
222 val to_int64_exn : t -> int64
223 (** [to_int64_exn data] converts [INT] [data] to an int64.
224
225 @raise DataTypeError if [data] is invalid. *)
226
227 val to_float_exn : t -> float
228 (** [to_float_exn data] converts [FLOAT] [data] to a float.
229
230 @raise DataTypeError if [data] is invalid. *)
231
232 val to_bool_exn : t -> bool
233 (** [to_bool_exn data] converts [INT] [data] to a bool.
234
235 @raise DataTypeError if [data] is invalid. *)
236
237 val to_string : t -> string option
238 (** [to_string data] converts [data] to [Some string] or [None] if it is not a
239 valid conversion. This method also converts data of type BLOB to a string.
240 *)
241
242 val to_int : t -> int option
243 (** [to_int data] converts [data] to [Some int] or [None] if it is not a valid
244 conversion.
245
246 @raise Failure if the integer conversion over- or underflows. *)
247
248 val to_nativeint : t -> nativeint option
249 (** [to_nativeint data] converts [data] to [Some nativeint] or [None] if it is
250 not a valid conversion.
251
252 @raise Failure if the integer conversion over- or underflows. *)
253
254 val to_int32 : t -> int32 option
255 (** [to_int32 data] converts [data] to [Some int32] or [None] if it is not a
256 valid conversion.
257
258 @raise Failure if the integer conversion over- or underflows. *)
259
260 val to_int64 : t -> int64 option
261 (** [to_int64 data] converts [data] to [Some int64] or [None] if it is not a
262 valid conversion. *)
263
264 val to_float : t -> float option
265 (** [to_float data] converts [data] to [Some float] or [None] if it is not a
266 valid conversion. *)
267
268 val to_bool : t -> bool option
269 (** [to_bool data] converts [data] to [Some bool] or [None] if it is not a
270 valid conversion. *)
271
272 val to_string_coerce : t -> string
273 (** [to_string_coerce data] coerces [data] to a string, using coercion on
274 ints, NULLs, floats, and other data types. *)
275
276 val to_string_debug : t -> string
277 (** [to_string_debug data] converts [data] to a string including the data
278 constructor. The contents of blobs will not be printed, only its length.
279 Useful for debugging. *)
280end
281
282(** {2 General database operations} *)
283
284val db_open :
285 ?mode:[ `READONLY | `NO_CREATE ] ->
286 ?uri:bool ->
287 ?memory:bool ->
288 ?mutex:[ `NO | `FULL ] ->
289 ?cache:[ `SHARED | `PRIVATE ] ->
290 ?vfs:string ->
291 string ->
292 db
293(** [db_open ?mode ?uri ?memory ?mutex ?cache ?vfs filename] opens the database
294 file [filename], and returns a database handle.
295
296 Special filenames: ":memory:" and "" open an in-memory or temporary database
297 respectively. Behaviour explained here:
298 https://www.sqlite.org/inmemorydb.html
299
300 The optional arguments [mode], [uri], [memory] and [mutex] are only
301 meaningful with SQLite versions >= 3.5, [cache] only for versions >= 3.6.18.
302 For older versions an exception will be raised if any of them is set to a
303 non-default value. The database is opened read-only if [`READONLY] is passed
304 as mode. The database file will not be created if it is missing and
305 [`NO_CREATE] is set. The [uri] parameter enables URI filename interpretation
306 and corresponds to [SQLITE_OPEN_URI] in the SQLite3 API. The [memory]
307 parameter opens an in-memory database and corresponds to
308 [SQLITE_OPEN_MEMORY] in the SQLite3 API. [mutex] determines how the database
309 is accessed. The mutex parameters [`NO] and [`FULL] correspond to
310 [SQLITE_OPEN_NOMUTEX] and [SQLITE_OPEN_FULLMUTEX] in the SQLite3 API
311 respectively. The cache parameters [`SHARED] and [`PRIVATE] correspond to
312 [SQLITE_OPEN_SHAREDCACHE] and [SQLITE_OPEN_PRIVATECACHE] in the SQLite3 API
313 respectively.
314
315 @param mode default = read-write, create
316 @param uri default = false
317 @param memory default = false
318 @param mutex default = nothing
319 @param cache default = nothing
320 @param vfs default = nothing *)
321
322val db_close : db -> bool
323(** [db_close db] closes database [db] and invalidates the handle.
324 @return
325 [false] if database was busy (database not closed in this case!), [true]
326 otherwise.
327
328 @raise SqliteError if an invalid database handle is passed. *)
329
330val ( let& ) : db -> (db -> 'a) -> 'a
331(** [let& db = db_open "..." in ...scope that uses db...] ensures that the
332 database [db] is safely closed at the end of the scope, even if there is an
333 exception somewhere in the scope.
334
335 @raise Fun.Finally_raised if the database could not be closed successfully.
336*)
337
338val enable_load_extension : db -> bool -> bool
339(** [enable_load_extension db onoff] enable/disable the SQLite3 load extension.
340 @return [false] if the operation fails, [true] otherwise. *)
341
342val errcode : db -> Rc.t
343(** [errcode db]
344 @return the error code of the last operation on database [db].
345
346 @raise SqliteError if an invalid database handle is passed. *)
347
348val errmsg : db -> string
349(** [errmsg db]
350 @return the error message of the last operation on database [db].
351
352 @raise SqliteError if an invalid database handle is passed. *)
353
354val extended_errcode_int : db -> int
355(** [extended_errcode_int db]
356 @return
357 the extended error code of the last operation on the database [db] as an
358 integer.
359
360 @raise SqliteError if an invalid database handle is passed. *)
361
362val last_insert_rowid : db -> int64
363(** [last_insert_rowid db]
364 @return
365 the index of the row inserted by the last operation on database [db].
366
367 @raise SqliteError if an invalid database handle is passed. *)
368
369val exec : db -> ?cb:(row -> headers -> unit) -> string -> Rc.t
370(** [exec db ?cb sql] performs SQL-operation [sql] on database [db]. If the
371 operation contains query statements, then the callback function [cb] will be
372 called for each matching row. The first parameter of the callback contains
373 the contents of the row, the second parameter contains the headers of the
374 columns associated with the row. Exceptions raised within the callback will
375 abort the execution and escape {!exec}.
376
377 @return the return code of the operation.
378
379 @param cb default = no callback
380
381 @raise SqliteError if an invalid database handle is passed. *)
382
383val exec_no_headers : db -> cb:(row -> unit) -> string -> Rc.t
384(** [exec_no_headers db ?cb sql] performs SQL-operation [sql] on database [db].
385 If the operation contains query statements, then the callback function [cb]
386 will be called for each matching row. The parameter of the callback is the
387 contents of the row. Exceptions raised within the callback will abort the
388 execution and escape {!exec_no_headers}.
389
390 @return the return code of the operation.
391
392 @raise SqliteError if an invalid database handle is passed. *)
393
394val exec_not_null : db -> cb:(row_not_null -> headers -> unit) -> string -> Rc.t
395(** [exec_not_null db ~cb sql] performs SQL-operation [sql] on database [db]. If
396 the operation contains query statements, then the callback function [cb]
397 will be called for each matching row. The first parameter of the callback is
398 the contents of the row, which must not contain NULL-values, the second
399 paramater are the headers of the columns associated with the row. Exceptions
400 raised within the callback will abort the execution and escape
401 {!exec_not_null}.
402
403 @return the return code of the operation.
404
405 @raise SqliteError if an invalid database handle is passed.
406 @raise SqliteError if a row contains NULL. *)
407
408val exec_not_null_no_headers : db -> cb:(row_not_null -> unit) -> string -> Rc.t
409(** [exec_not_null_no_headers db ~cb sql] performs SQL-operation [sql] on
410 database [db]. If the operation contains query statements, then the callback
411 function [cb] will be called for each matching row. The parameter of the
412 callback is the contents of the row, which must not contain NULL-values.
413 Exceptions raised within the callback will abort the execution and escape
414 {!exec_not_null_no_headers}.
415
416 @return the return code of the operation.
417
418 @raise SqliteError if an invalid database handle is passed.
419 @raise SqliteError if a row contains NULL. *)
420
421val changes : db -> int
422(** [changes db]
423 @return
424 the number of rows that were changed or inserted or deleted by the most
425 recently completed SQL statement on database [db]. *)
426
427(** {2 Prepared Statements} *)
428
429val prepare : db -> string -> stmt
430(** [prepare db sql] compile SQL-statement [sql] for database [db] into
431 bytecode. The statement may be only partially compiled. In this case
432 {!prepare_tail} can be called on the returned statement to compile the
433 remaining part of the SQL-statement.
434
435 NOTE: this really uses the C-function [sqlite3_prepare_v2], i.e. avoids the
436 older, deprecated [sqlite3_prepare]-function.
437
438 @raise SqliteError if an invalid database handle is passed.
439 @raise SqliteError if the statement could not be prepared. *)
440
441val prepare_or_reset : db -> stmt option ref -> string -> stmt
442(** [prepare_or_reset db opt_stmt_ref sql] if [opt_stmt_ref] contains
443 [Some stmt], then [stmt] will be reset and returned. Otherwise fresh
444 statement [stmt] will be prepared, stored as [Some stmt] in [opt_stmt_ref]
445 and then returned. This is useful for executing multiple identical commands
446 in a loop, because we can more efficiently reuse the statement from previous
447 iterations.
448
449 @raise SqliteError if the statement could not be prepared or reset. *)
450
451val prepare_tail : stmt -> stmt option
452(** [prepare_tail stmt] compile the remaining part of the SQL-statement [stmt]
453 to bytecode.
454
455 NOTE: this really uses the C-function [sqlite3_prepare_v2], i.e. avoids the
456 older, deprecated [sqlite3_prepare]-function.
457
458 @return
459 [None] if there was no remaining part, or [Some remaining_part] otherwise.
460
461 @raise SqliteError if the statement could not be prepared. *)
462
463val recompile : stmt -> unit
464(** [recompile stmt] recompiles the SQL-statement associated with [stmt] to
465 bytecode. The statement may be only partially compiled. In this case
466 {!prepare_tail} can be called on the statement to compile the remaining part
467 of the SQL-statement. Call this function if the statement expires due to
468 some schema change.
469
470 @raise SqliteError if the statement could not be recompiled. *)
471
472val finalize : stmt -> Rc.t
473(** [finalize stmt] finalizes the statement [stmt]. After finalization, the only
474 valid usage of the statement is to use it in {!prepare_tail}, or to
475 {!recompile} it.
476
477 @return the return code of this operation.
478
479 @raise SqliteError if the statement could not be finalized. *)
480
481(** {3 Data query} *)
482
483val data_count : stmt -> int
484(** [data_count stmt]
485 @return
486 the number of columns in the result of the last step of statement [stmt].
487
488 @raise SqliteError if the statement is invalid. *)
489
490val column_count : stmt -> int
491(** [column_count stmt]
492 @return
493 the number of columns that would be returned by executing statement
494 [stmt].
495
496 @raise SqliteError if the statement is invalid. *)
497
498val column : stmt -> int -> Data.t
499(** [column stmt n]
500 @return
501 the data in column [n] of the result of the last step of statement [stmt].
502
503 @raise RangeError if [n] is out of range.
504 @raise SqliteError if the statement is invalid. *)
505
506val column_bool : stmt -> int -> bool
507(** [column_bool stmt n]
508 @return
509 the data in column [n] of the result of the last step of statement [stmt]
510 as a [bool].
511
512 @raise RangeError if [n] is out of range.
513 @raise SqliteError if the statement is invalid. *)
514
515val column_text : stmt -> int -> string
516(** [column_text stmt n]
517 @return
518 the data in column [n] of the result of the last step of statement [stmt]
519 as text (a [string]).
520
521 @raise RangeError if [n] is out of range.
522 @raise SqliteError if the statement is invalid. *)
523
524val column_int : stmt -> int -> int
525(** [column_int stmt n]
526 @return
527 the data in column [n] of the result of the last step of statement [stmt]
528 as an [int].
529
530 @raise RangeError if [n] is out of range.
531 @raise Failure if the integer conversion over- or underflows.
532 @raise SqliteError if the statement is invalid. *)
533
534val column_nativeint : stmt -> int -> nativeint
535(** [column_nativeint stmt n]
536 @return
537 the data in column [n] of the result of the last step of statement [stmt]
538 as a [nativeint].
539
540 @raise RangeError if [n] is out of range.
541 @raise Failure if the integer conversion over- or underflows.
542 @raise SqliteError if the statement is invalid. *)
543
544val column_int32 : stmt -> int -> int32
545(** [column_int32 stmt n]
546 @return
547 the data in column [n] of the result of the last step of statement [stmt]
548 as an [int32]. Note that this function exactly corresponds to the
549 C-library function [sqlite3_column_int] and does not check for over- or
550 underflow during integer conversions.
551
552 @raise RangeError if [n] is out of range.
553 @raise SqliteError if the statement is invalid. *)
554
555val column_int64 : stmt -> int -> int64
556(** [column_int64 stmt n]
557 @return
558 the data in column [n] of the result of the last step of statement [stmt]
559 as an [int64]. Note that this function exactly corresponds to the
560 C-library function [sqlite3_column_int64] and does not check for over- or
561 underflow during integer conversions.
562
563 @raise RangeError if [n] is out of range.
564 @raise SqliteError if the statement is invalid. *)
565
566val column_double : stmt -> int -> float
567(** [column_double stmt n]
568 @return
569 the data in column [n] of the result of the last step of statement [stmt]
570 as a double [float].
571
572 @raise RangeError if [n] is out of range.
573 @raise SqliteError if the statement is invalid. *)
574
575val column_blob : stmt -> int -> string
576(** [column_blob stmt n]
577 @return
578 the blob string in column [n] of the result of the last step of statement
579 [stmt] as a [string].
580
581 @raise RangeError if [n] is out of range.
582 @raise SqliteError if the statement is invalid. *)
583
584val column_name : stmt -> int -> header
585(** [column_name stmt n]
586 @return the header of column [n] in the result set of statement [stmt].
587
588 @raise RangeError if [n] is out of range.
589 @raise SqliteError if the statement is invalid. *)
590
591val column_decltype : stmt -> int -> string option
592(** [column_decltype stmt n]
593 @return
594 the declared type of the specified column in the result set of statement
595 [stmt] as [Some str] if available, or as [None] otherwise.
596
597 @raise RangeError if [n] is out of range.
598 @raise SqliteError if the statement is invalid. *)
599
600(** {3 Binding data to statements} *)
601
602val bind : stmt -> int -> Data.t -> Rc.t
603(** [bind stmt pos data] binds the value [data] to the free variable at position
604 [pos] of statement [stmt]. NOTE: the first variable has index [1]!
605
606 @return the return code of this operation.
607
608 @raise RangeError if [pos] is out of range.
609 @raise SqliteError if the statement is invalid. *)
610
611val bind_text : stmt -> int -> string -> Rc.t
612(** [bind_text stmt pos str] binds the string [str] to the parameter at position
613 [pos] of the statement [stmt] as text.
614
615 @return the return code of this operation.
616
617 @raise RangeError if [pos] is out of range.
618 @raise SqliteError if the statement is invalid. *)
619
620val bind_bool : stmt -> int -> bool -> Rc.t
621(** [bind_bool stmt pos b] binds the boolean [b] to the parameter at position
622 [pos] of the statement [stmt] without having to manually convert it to an
623 [int64] for use with [Data.INT]. [true] is turned into 1, [false] into 0.
624
625 @return the return code of this operation.
626
627 @raise RangeError if [pos] is out of range.
628 @raise SqliteError if the statement is invalid. *)
629
630val bind_int : stmt -> int -> int -> Rc.t
631(** [bind_int stmt pos n] binds the integer [n] to the parameter at position
632 [pos] of the statement [stmt] without having to manually convert it to an
633 [int64] for use with [Data.INT].
634
635 @return the return code of this operation.
636
637 @raise RangeError if [pos] is out of range.
638 @raise SqliteError if the statement is invalid. *)
639
640val bind_nativeint : stmt -> int -> nativeint -> Rc.t
641(** [bind_nativeint stmt pos n] binds the integer [n] to the parameter at
642 position [pos] of the statement [stmt] without having to manually convert it
643 to an [int64] for use with [Data.INT].
644
645 @return the return code of this operation.
646
647 @raise RangeError if [pos] is out of range.
648 @raise SqliteError if the statement is invalid. *)
649
650val bind_int32 : stmt -> int -> int32 -> Rc.t
651(** [bind_int32 stmt pos n] binds the 32-bit integer [n] to the parameter at
652 position [pos] of the statement [stmt] without having to manually convert it
653 to an [int64] for use with [Data.INT].
654
655 @return the return code of this operation.
656
657 @raise RangeError if [pos] is out of range.
658 @raise SqliteError if the statement is invalid. *)
659
660val bind_int64 : stmt -> int -> int64 -> Rc.t
661(** [bind_int64 stmt pos n] binds the 64-bit integer [n] to the parameter at
662 position [pos] of the statement [stmt].
663
664 @return the return code of this operation.
665
666 @raise RangeError if [pos] is out of range.
667 @raise SqliteError if the statement is invalid. *)
668
669val bind_double : stmt -> int -> float -> Rc.t
670(** [bind_double stmt pos n] binds the float [n] to the parameter at position
671 [pos] of the statement [stmt].
672
673 @return the return code of this operation.
674
675 @raise RangeError if [pos] is out of range.
676 @raise SqliteError if the statement is invalid. *)
677
678val bind_blob : stmt -> int -> string -> Rc.t
679(** [bind_blob stmt pos str] binds the string [str] to the parameter at position
680 [pos] of the statement [stmt] as a blob.
681
682 @return the return code of this operation.
683
684 @raise RangeError if [pos] is out of range.
685 @raise SqliteError if the statement is invalid. *)
686
687val bind_values : stmt -> Data.t list -> Rc.t
688(** [bind_values stmt lst] binds the Nth element of [lst] to the Nth parameter
689 of the statement.
690
691 @return the return code of the first binding that fails, or [Rc.OK].
692
693 @raise RangeError
694 if there aren't at least as many parameters as there are elements of the
695 list.
696 @raise SqliteError if the statement is invalid. *)
697
698val bind_name : stmt -> string -> Data.t -> Rc.t
699(** [bind_name stmt name data] binds the value [data] to the named parameter
700 [name] of statement [stmt].
701
702 @return the return code of this operation.
703
704 @raise Not_found if [name] does not exist.
705 @raise SqliteError if the statement is invalid. *)
706
707val bind_names : stmt -> (string * Data.t) list -> Rc.t
708(** [bind_names stmt lst] binds the [(name, data)] pairs in [lst] to the
709 parameters of statement [stmt].
710
711 @return the return code of the first binding that fails, or [Rc.OK].
712
713 @raise Not_found if a [name] does not exist.
714 @raise SqliteError if the statement is invalid. *)
715
716val bind_parameter_count : stmt -> int
717(** [bind_parameter_count stmt]
718 @return the number of free variables in statement [stmt].
719
720 @raise SqliteError if the statement is invalid. *)
721
722val bind_parameter_name : stmt -> int -> string option
723(** [bind_parameter_name stmt pos]
724 @return
725 [Some parameter_name] of the free variable at position [pos] of statement
726 [stmt], or [None] if it is ordinary ("?").
727
728 @raise RangeError if [pos] is out of range.
729 @raise SqliteError if the statement is invalid. *)
730
731val bind_parameter_index : stmt -> string -> int
732(** [bind_parameter_index stmt name]
733 @return
734 the position of the free variable with name [name] in statement [stmt].
735
736 @raise Not_found if [name] was not found.
737 @raise SqliteError if the statement is invalid. *)
738
739val clear_bindings : stmt -> Rc.t
740(** [clear_bindings stmt] resets all bindings associated with prepared statement
741 [stmt].
742
743 @return the return code of this operation.
744
745 @raise SqliteError if the statement is invalid. *)
746
747(** {3 Executing statements} *)
748
749val step : stmt -> Rc.t
750(** [step stmt] performs one step of the query associated with SQL-statement
751 [stmt].
752
753 @return the return code of this operation.
754
755 @raise SqliteError if the step could not be executed. *)
756
757val reset : stmt -> Rc.t
758(** [reset stmt] resets the statement [stmt], e.g. to restart the query, perhaps
759 with different bindings.
760
761 @return the return code of this operation.
762
763 @raise SqliteError if the statement could not be reset. *)
764
765val iter : stmt -> f:(Data.t array -> unit) -> Rc.t
766(** [iter stmt ~f] will call [f] once per row returned by stepping through
767 [stmt]. The statement is automatically reset afterwards.
768
769 @return [Rc.DONE] on success or another return code on error.
770
771 @raise SqliteError if the statement is invalid. *)
772
773val fold : stmt -> f:('a -> Data.t array -> 'a) -> init:'a -> Rc.t * 'a
774(** [fold stmt ~f ~init] folds over the rows returned by [stmt] with function
775 [f] and initial value [init]. The statement is automatically reset
776 afterwards.
777
778 @return
779 [(rc, acc)] where [acc] is the last accumulated value returned by [f]
780 after being called on a row. [rc] is [Rc.DONE] if all rows were processed
781 and if the statement could be reset, otherwise an error code.
782
783 @raise SqliteError if the statement is invalid. *)
784
785(** {3 Stepwise query convenience functions} *)
786
787val row_blobs : stmt -> string array
788(** [row_blobs stmt]
789 @return
790 the blobs returned by the last query step performed with statement [stmt]
791 (array of blobs).
792
793 @raise SqliteError if the statement is invalid. *)
794
795val row_data : stmt -> Data.t array
796(** [row_data stmt]
797 @return
798 all data values in the row returned by the last query step performed with
799 statement [stmt].
800
801 @raise SqliteError if the statement is invalid. *)
802
803val row_names : stmt -> headers
804(** [row_names stmt]
805 @return
806 all column headers of the row returned by the last query step performed
807 with statement [stmt].
808
809 @raise SqliteError if the statement is invalid. *)
810
811val row_decltypes : stmt -> string option array
812(** [row_decltypes stmt]
813 @return
814 all column type declarations of the row returned by the last query step
815 performed with statement [stmt].
816
817 @raise SqliteError if the statement is invalid. *)
818
819(** {2 User-defined functions} *)
820
821val create_funN : db -> string -> (Data.t array -> Data.t) -> unit
822(** [create_funN db name f] registers function [f] under name [name] with
823 database handle [db]. The function has arity [N].
824
825 @raise SqliteError if an invalid database handle is passed. *)
826
827val create_fun0 : db -> string -> (unit -> Data.t) -> unit
828(** [create_funN db name f] registers function [f] under name [name] with
829 database handle [db]. The function has arity [0].
830
831 @raise SqliteError if an invalid database handle is passed. *)
832
833val create_fun1 : db -> string -> (Data.t -> Data.t) -> unit
834(** [create_fun1 db name f] registers function [f] under name [name] with
835 database handle [db]. The function has arity [1].
836
837 @raise SqliteError if an invalid database handle is passed. *)
838
839val create_fun2 : db -> string -> (Data.t -> Data.t -> Data.t) -> unit
840(** [create_fun2 db name f] registers function [f] under name [name] with
841 database handle [db]. The function has arity [2].
842
843 @raise SqliteError if an invalid database handle is passed. *)
844
845val create_fun3 : db -> string -> (Data.t -> Data.t -> Data.t -> Data.t) -> unit
846(** [create_fun3 db name f] registers function [f] under name [name] with
847 database handle [db]. The function has arity [3].
848
849 @raise SqliteError if an invalid database handle is passed. *)
850
851val delete_function : db -> string -> unit
852(** [delete_function db name] deletes function with name [name] from database
853 handle [db].
854
855 @raise SqliteError if an invalid database handle is passed. *)
856
857module Aggregate : sig
858 (** Create user-defined aggregate and window functions.
859
860 Aggregate functions provide the [step] function, which is called once per
861 value being added to the aggregate, and the [final] function is called
862 once to return the final value.
863
864 To make a window function (requires SQLite3 3.25 or newer; on older
865 versions a normal aggregate function is created), the additional [inverse]
866 function, which removes a value from the window, and [value], which can be
867 called many times and returns the current computed value of the window,
868 must both be included. *)
869
870 val create_fun0 :
871 ?inverse:('a -> 'a) ->
872 ?value:('a -> Data.t) ->
873 db ->
874 string ->
875 init:'a ->
876 step:('a -> 'a) ->
877 final:('a -> Data.t) ->
878 unit
879 (** [create_fun0 ?inverse ?value db name ~init ~step ~final] registers the
880 step and finalizer functions and optional inverse and value functions
881 under name [name] with database handle [db]. This function has arity [0].
882
883 @raise SqliteError if an invalid database handle is passed. *)
884
885 val create_fun1 :
886 ?inverse:('a -> Data.t -> 'a) ->
887 ?value:('a -> Data.t) ->
888 db ->
889 string ->
890 init:'a ->
891 step:('a -> Data.t -> 'a) ->
892 final:('a -> Data.t) ->
893 unit
894 (** [create_fun1 ?inverse ?value db name ~init ~step ~final] registers the
895 step and finalizer functions and optional inverse and value functions
896 under name [name] with database handle [db]. This function has arity [1].
897
898 @raise SqliteError if an invalid database handle is passed. *)
899
900 val create_fun2 :
901 ?inverse:('a -> Data.t -> Data.t -> 'a) ->
902 ?value:('a -> Data.t) ->
903 db ->
904 string ->
905 init:'a ->
906 step:('a -> Data.t -> Data.t -> 'a) ->
907 final:('a -> Data.t) ->
908 unit
909 (** [create_fun2 ?inverse ?value db name ~init ~step ~final] registers the
910 step and finalizer functions and optional inverse and value functions
911 under name [name] with database handle [db]. This function has arity [2].
912
913 @raise SqliteError if an invalid database handle is passed. *)
914
915 val create_fun3 :
916 ?inverse:('a -> Data.t -> Data.t -> Data.t -> 'a) ->
917 ?value:('a -> Data.t) ->
918 db ->
919 string ->
920 init:'a ->
921 step:('a -> Data.t -> Data.t -> Data.t -> 'a) ->
922 final:('a -> Data.t) ->
923 unit
924 (** [create_fun3 ?inverse ?value db name ~init ~step ~final] registers the
925 step and finalizer functions and optional inverse and value functions
926 under name [name] with database handle [db]. This function has arity [3].
927
928 @raise SqliteError if an invalid database handle is passed. *)
929
930 val create_funN :
931 ?inverse:('a -> Data.t array -> 'a) ->
932 ?value:('a -> Data.t) ->
933 db ->
934 string ->
935 init:'a ->
936 step:('a -> Data.t array -> 'a) ->
937 final:('a -> Data.t) ->
938 unit
939 (** [create_funN ?inverse ?value db name ~init ~step ~final] registers the
940 step and finalizer functions and optional inverse and value functions
941 under name [name] with database handle [db]. This function has arity [N].
942
943 @raise SqliteError if an invalid database handle is passed. *)
944end
945
946val create_collation : db -> string -> (string -> string -> int) -> unit
947(** [create_collation db name func] creates a collation with [name] in database
948 handle [db]. [func] is called when the collation is needed, it must return
949 an integer that is negative, zero, or positive if the first string is less
950 than, equal to, or greater than the second, respectively
951
952 @raise SqliteError if an invalid database handle is passed. *)
953
954val delete_collation : db -> string -> unit
955(** [delete_collation db name] deletes collation with name [name] from database
956 handle [db].
957
958 @raise SqliteError if an invalid database handle is passed. *)
959
960module Backup : sig
961 type t
962 (** Type of a backup between two databases *)
963
964 val init : dst:db -> dst_name:string -> src:db -> src_name:string -> t
965 (** [init ~dst ~dst_name ~src ~src_name] initializes a backup from the
966 database [src]/[src_name] to the database [dst]/[dst_name].
967
968 @raise SqliteError
969 if there is already a read or read-write transaction open on the
970 destination database *)
971
972 val step : t -> int -> Rc.t
973 (** [step backup pagecount] will copy up to [pagecount] pages between the
974 associated databases of [backup]. *)
975
976 val finish : t -> Rc.t
977 (** [finish backup] destroys the association [backup]; this is to be called
978 after [step] returns [SQLITE_DONE]. *)
979
980 val remaining : t -> int
981 (** [remaining backup] returns the number of pages still to be backed up in
982 [backup]. *)
983
984 val pagecount : t -> int
985 (** [pagecount backup] returns the total number of pages in the source
986 database of [backup]. *)
987end
988
989(** {2 Utility functions} *)
990
991val busy_timeout : db -> int -> unit
992(** [busy_timeout db ms] sets a busy handler that sleeps for a specified amount
993 of time when a table is locked. The handler will sleep multiple times until
994 at least [ms] milliseconds of sleeping have accumulated.
995
996 @raise SqliteError if an invalid database handle is passed. *)
997
998val sleep : int -> int
999(** [sleep ms] sleeps at least [ms] milliseconds.
1000 @return
1001 the number of milliseconds of sleep actually requested from the operating
1002 system. *)