Minimal SQLite key-value store for OCaml
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Thomas Gazagnaire. All rights reserved.
3 SPDX-License-Identifier: MIT
4 ---------------------------------------------------------------------------*)
5
6(** Pure OCaml B-tree backed key-value store.
7
8 A simple key-value store with SQLite-compatible semantics using a pure OCaml
9 B-tree implementation. Supports namespaced tables and reading any SQLite
10 database. *)
11
12type t
13(** A B-tree backed key-value store. *)
14
15val pp : t Fmt.t
16(** Pretty-print a database handle. *)
17
18(** {1 Record Values}
19
20 Re-exported from {!Btree.Record} so users don't need to depend on btree
21 directly. *)
22
23type value = Btree.Record.value =
24 | Vnull
25 | Vint of int64
26 | Vfloat of float
27 | Vblob of string
28 | Vtext of string (** Column values decoded from SQLite records. *)
29
30val pp_value : Format.formatter -> value -> unit
31(** Pretty-print a value. *)
32
33(** {1 Schema} *)
34
35type column = {
36 col_name : string;
37 col_affinity : string;
38 col_is_rowid_alias : bool;
39}
40(** A column definition parsed from CREATE TABLE SQL. [col_is_rowid_alias] is
41 [true] for [INTEGER PRIMARY KEY] columns, which are aliases for the rowid.
42*)
43
44type schema = { tbl_name : string; columns : column list; sql : string }
45(** Table schema with the original CREATE TABLE SQL. *)
46
47(** {1 Database Lifecycle} *)
48
49val in_memory : unit -> t
50(** [in_memory ()] creates a purely in-memory database. No file I/O is
51 performed. Useful for testing. *)
52
53val open_ : sw:Eio.Switch.t -> ?create:bool -> Eio.Fs.dir_ty Eio.Path.t -> t
54(** [open_ ~sw ?create path] opens a database at [path].
55
56 If [create] is [true] (the default), the database is created if it does not
57 exist. If [create] is [false], the file must already exist or [Sys_error] is
58 raised.
59
60 {b Warning}: does {b not} truncate existing files. Works with any SQLite
61 database, not just ones created by this library. If the database contains a
62 [kv] table, the KV API functions below will work; otherwise, use the generic
63 read API.
64 @raise Failure if the file doesn't exist or is not a valid SQLite database.
65*)
66
67val sync : t -> unit
68(** [sync t] flushes all pending writes to disk. Uses a write-ahead log for
69 crash safety when backed by a file. *)
70
71val close : t -> unit
72(** [close t] syncs and closes the database. *)
73
74val with_transaction : t -> (unit -> 'a) -> 'a
75(** [with_transaction t f] runs [f ()] atomically. If [f] raises an exception,
76 all modifications to the database are rolled back and the exception is
77 re-raised. If [f] returns normally, the changes are kept in memory but not
78 yet synced to disk — call {!sync} for durability.
79
80 Transactions do not nest: calling [with_transaction] inside [f] is permitted
81 but the inner transaction has no independent rollback — a failure in the
82 inner transaction rolls back to the outermost savepoint. *)
83
84(** {1 Key-Value API}
85
86 These functions operate on the default [kv] table. They raise [Failure] if
87 the database was opened from a file that has no [kv] table. *)
88
89val find : t -> string -> string option
90(** [find t key] returns the value for [key], or [None] if not found. *)
91
92val put : t -> string -> string -> unit
93(** [put t key value] stores [value] at [key], replacing any existing value. *)
94
95val delete : t -> string -> unit
96(** [delete t key] removes [key] from the store. No-op if key doesn't exist. *)
97
98val mem : t -> string -> bool
99(** [mem t key] is [true] if [key] exists in the store. *)
100
101val iter : t -> f:(string -> string -> unit) -> unit
102(** [iter t ~f] calls [f key value] for each entry in the store. *)
103
104val fold : t -> init:'a -> f:(string -> string -> 'a -> 'a) -> 'a
105(** [fold t ~init ~f] folds over all entries in the store. *)
106
107(** {1 Generic Read API}
108
109 Read any table in the database, regardless of schema. *)
110
111val tables : t -> schema list
112(** [tables t] returns the schema of every table in the database. *)
113
114val iter_table : t -> string -> f:(int64 -> value list -> unit) -> unit
115(** [iter_table t name ~f] calls [f rowid values] for each row in table [name].
116 For [INTEGER PRIMARY KEY] columns, [Vnull] is replaced with [Vint rowid].
117 Trailing [Vnull]s are padded if the record has fewer values than columns.
118 @raise Failure if the table doesn't exist. *)
119
120val fold_table :
121 t -> string -> init:'a -> f:(int64 -> value list -> 'a -> 'a) -> 'a
122(** [fold_table t name ~init ~f] folds over all rows in table [name]. *)
123
124val read_table : t -> string -> (int64 * value list) list
125(** [read_table t name] returns all rows from table [name] as a list. *)
126
127(** {1 Generic Write API}
128
129 Create arbitrary tables and insert rows. *)
130
131exception Unique_violation of string
132(** Raised by {!insert} when a row would violate a [UNIQUE] constraint. The
133 string names the constrained columns (e.g. ["provider, provider_uid"]). *)
134
135val create_table : t -> sql:string -> unit
136(** [create_table t ~sql] creates a new table from a CREATE TABLE statement. The
137 SQL is stored in sqlite_master and the column definitions are parsed for
138 schema metadata. [UNIQUE] constraints (both column-level and table-level)
139 are parsed and enforced on subsequent {!insert} calls. *)
140
141val insert : t -> table:string -> value list -> int64
142(** [insert t ~table values] inserts a row into [table] with the given column
143 values. Returns the rowid of the inserted row.
144
145 For tables with an [INTEGER PRIMARY KEY] column, if the corresponding value
146 is [Vint n], the row is inserted with rowid [n]. If the value is [Vnull],
147 the rowid is auto-assigned.
148
149 @raise Failure if the table doesn't exist.
150 @raise Unique_violation if the row violates a [UNIQUE] constraint. *)
151
152val delete_row : t -> table:string -> int64 -> unit
153(** [delete_row t ~table rowid] deletes the row with the given [rowid] from
154 [table]. No-op if the rowid doesn't exist.
155 @raise Failure if the table doesn't exist. *)
156
157(** {1 Schema Parsing} *)
158
159val parse_create_table : string -> column list
160(** [parse_create_table sql] parses a CREATE TABLE statement and returns the
161 column definitions. Returns an empty list if parsing fails. *)
162
163(** {1 Namespaced Tables}
164
165 Tables provide isolated key-value namespaces within a single database. *)
166
167module Table : sig
168 type db = t
169 (** The parent database type. *)
170
171 type t
172 (** A namespaced table within a database. *)
173
174 val create : db -> name:string -> t
175 (** [create db ~name] creates or opens a table named [name] within [db]. The
176 table name must be a valid SQL identifier. *)
177
178 val find : t -> string -> string option
179 (** [find t key] returns the value for [key], or [None]. *)
180
181 val put : t -> string -> string -> unit
182 (** [put t key value] stores [value] at [key]. *)
183
184 val delete : t -> string -> unit
185 (** [delete t key] removes [key] from the table. *)
186
187 val mem : t -> string -> bool
188 (** [mem t key] is [true] if [key] exists in the table. *)
189
190 val iter : t -> f:(string -> string -> unit) -> unit
191 (** [iter t ~f] calls [f key value] for each entry in the table. *)
192end