libfossil
db.h
Go to the documentation of this file.
1/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* vim: set ts=2 et sw=2 tw=80: */
3#if !defined(ORG_FOSSIL_SCM_FSL_DB_H_INCLUDED)
4#define ORG_FOSSIL_SCM_FSL_DB_H_INCLUDED
5/*
6 Copyright 2013-2021 The Libfossil Authors, see LICENSES/BSD-2-Clause.txt
7
8 SPDX-License-Identifier: BSD-2-Clause-FreeBSD
9 SPDX-FileCopyrightText: 2021 The Libfossil Authors
10 SPDX-FileType: Code
11
12 Heavily indebted to the Fossil SCM project (https://fossil-scm.org).
13
14
15 ******************************************************************************
16 This file declares public APIs for working with fossil's database
17 abstraction layer.
18*/
19
20#include "core.h" /* MUST come first b/c of config macros */
21/*
22 We don't _really_ want to include sqlite3.h at this point, but if we
23 do not then we have to typedef the sqlite3 struct here and that
24 breaks when client code includes both this file and sqlite3.h.
25*/
26#include "sqlite3.h"
27
28#if defined(__cplusplus)
29extern "C" {
30#endif
31
32#if 0
33/* We can't do this because it breaks when clients include both
34 this header and sqlite3.h. Is there a solution which lets us
35 _not_ include sqlite3.h from this file and also compiles when
36 clients include both?
37*/
38#if !defined(SQLITE_OK)
39typedef struct sqlite3 sqlite3;
40#endif
41#endif
42
43/**
44 Flags for use with fsl_db_open() and friends.
45*/
47/**
48 The "no flags" value.
49*/
51
52/**
53 Flag for fsl_db_open() specifying that the db should be opened
54 in read-only mode.
55*/
57
58/**
59 Flag for fsl_db_open() specifying that the db should be opened
60 in read-write mode, but should not create the db if it does
61 not already exist.
62*/
64
65/**
66 Flag for fsl_db_open() specifying that the db should be opened in
67 read-write mode, creating the db if it does not already exist.
68
69 ACHTUNG: this flag propagates from an OPEN'd db handle to the
70 ATTACH SQL command run via that handle, such that ATTACHing a
71 non-existing db file will fail if the FSL_DB_OPEN_CREATE flag is
72 _not_ used. Historically (prior to 2022-01-01), fsl_db_open() would
73 automatically apply this flag to DBs named ":memory:" or ""
74 (unnamed temp dbs), but that ended up causing a full day of
75 confusion, hair-pulling, and bug-hunting when lib-level code was
76 migrated from an anonymous temp db to a "real" db and ATTACH
77 suddenly failed. As of 2022-01-01, fsl_db_open() always takes the
78 open-mode flags as provided by the client, regardless of the DB
79 name, and never automatically rewrites them to include
80 FSL_DB_OPEN_CREATE.
81*/
83
84/**
85 Shorthand for RW+CREATE flags.
86*/
88
89/**
90 Currently unused. It "should" be used to tell fsl_repo_open_xxx()
91 to confirm that the db is a repository, but how to propagate
92 that through the corresponding APIs is not currently clear.
93*/
95
96/**
97 Used by fsl_db_open() to to tell the underlying db connection to
98 trace all SQL to stdout. This is often useful for testing,
99 debugging, and learning about what's going on behind the scenes.
100*/
102};
103
104/**
105 A level of indirection to "hide" the actual db driver
106 implementation from the public API. It uses SQLite3 but this gives
107 us a comforting level of abstraction.
108
109 Sidebar: at the time this code was originally written, sqlite4 was
110 in an experimental stage to explore a new storage engine which, it
111 was hoped, would speed up sqlite considerably. It ended up never
112 leaving that stage because the performance gains of the storage
113 engine did not justify such a significant upheaval. Even so,
114 sqlite4 "might" come around sometime within the lifetime of this
115 project, so it behooves us to abstract away this type from the
116 public API.
117*/
118typedef sqlite3 fsl_db_t;
119
120/**
121 Bitmasks for use with fsl_db_event_e.
122*/
125
126 /**
127 Describes a data type for fsl_db_event::payload.
128 */
130
131 /** (fsl_buffer const *) payload. */
133
134 /**
135 All concrete message IDs are masked with this.
136 */
138
139 /**
140 Convenience entry for use with fsl_db_event_listener().
141 */
143};
144
145/**
146 A map of fsl_db_event types.
147*/
148#define fsl_db_event_map(E) \
149 E(FSL_DB_EVENT_BEGIN, 0x01) \
150 E(FSL_DB_EVENT_COMMIT, 0x02) \
151 E(FSL_DB_EVENT_ROLLING_BACK, 0x04) \
152 E(FSL_DB_EVENT_ROLLED_BACK, 0x08) \
153 E(FSL_DB_EVENT_CLOSING, 0x10) \
154 E(FSL_DB_EVENT_TRACE_SQL, 0x20 \
155 | FSL_DB_EVENT_payload_buffer \
156 /*unexpanded SQL*/) \
157 E(FSL_DB_EVENT_TRACE_SQLX, 0x40 \
158 | FSL_DB_EVENT_payload_buffer \
159 /*expanded SQL*/)
160
161/**
162 A flag type for use with fsl_db_event_f() implementations.
163*/
165#define E(X,V) X = V,
167#undef E
168};
170
171/**
172 Convenience FSL_DB_EVENT_... entries which cannot be defined until
173 after fsl_db_event_e is.
174*/
176 /** Mask of the IDs of transaction-specific events. */
178 & (FSL_DB_EVENT_BEGIN | FSL_DB_EVENT_COMMIT
179 | FSL_DB_EVENT_ROLLING_BACK | FSL_DB_EVENT_ROLLED_BACK),
180 /** Mask of the IDs of SQL tracing events. */
182 & (FSL_DB_EVENT_TRACE_SQL
183 | FSL_DB_EVENT_TRACE_SQLX)
184};
185
186/**
187 An "event" message type for use with fsl_db.
188*/
190 /**
191 The event-firing db.
192 */
194 /**
195 The event listener state.
196 */
197 void * state;
198 /**
199 A message-type-specific payload. Its native type is encoded in
200 this->type.
201 */
202 void const * payload;
203 /**
204 Event type.
205 */
207 /**
208 The db's current savepoint level (because most events deal with
209 transactions and this info has proven useful in downstream code).
210 This will usually have a value of 1 or higher, the exception
211 being FSL_DB_EVENT_CLOSING, where a that level is 0.
212 */
214};
216
217/**
218 An event callback for fsl_db objects, primarily for communicating
219 on-transaction-start/end. Each fsl_db instance may have a single
220 one of these installed and it gets called via at various points to
221 fire well-defined events.
222
223 When the docs below refer to BEGIN and COMMIT, they're actually
224 referring to their SAVEPOINT counterparts. That's partly
225 historical, from a time when this API uses BEGIN/COMMIT, but it's
226 also thought to be clearer terminology here.
227
228 Doc references below to fsl_db_txn_begin() and fsl_db_txn_end()
229 also imply their v2 variants.
230
231 ev->state holds the state registered with the callback in
232 fsl_db_event_listener().
233
234 ev->type explains the nature of the event:
235
236 - FSL_DB_EVENT_CLOSING is fired early on in fsl_db_close(). If
237 closing is forced to roll back savepoints, those events are fired
238 first and their result codes are ignored. The result of this event
239 is likewise also ignored. Though the callback may (technically
240 speaking) still perform db operations, it must never start a new
241 transaction (unless it also closes it before returning) nor may it
242 close the db object. If either of those conditions is violated,
243 results are undefined. This event is _not_ fired when a DETACH'ing
244 database, as this API does not have any insight into when ATTACH
245 and DETACH are used.
246
247 - FSL_DB_TXN_BEGIN is passed immediately after fsl_db_txn_begin()
248 starts the transaction. If this function returns non-0, the
249 transaction is _immediately_ rolled back but the rollback event is
250 not triggered for this particular failure. Unless the starting of a
251 new transaction level actually fails, the callback's return value
252 because the result of fsl_db_txn_begin().
253
254 - FSL_DB_TXN_COMMIT is called immediately before fsl_db_txn_end()
255 runs COMMIT on the db. If it returns non-0, the pending COMMIT is
256 replaced with a ROLLBACK and that result code becomes the result of
257 fsl_db_txn_end(). The rollback events are _not_ triggered in this
258 case.
259
260 - FSL_DB_TXN_ROLLING_BACK is called immediately before
261 fsl_db_txn_end() runs ROLLBACK on the db. If it returns non-0 but
262 the SQL-level succeeds, its result becomes the result of
263 fsl_db_txn_end(), but it does not cancel the pending db-side
264 ROLLBACK. Only one of FSL_DB_TXN_COMMIT or FSL_DB_TXN_ROLLING_BACK
265 is invoked for a given call to fsl_db_txn_end(). If
266 FSL_DB_TXN_COMMIT returns non-zero, no FSL_DB_TXN_ROLLING_BACK
267 invocation is made.
268
269 - FSL_DB_TXN_ROLLED_BACK is called immediately after
270 fsl_db_txn_end() has run a ROLLBACK. If this function returns non-0
271 but both the the SQL-level rollback and the FSL_DB_TXN_ROLLING_BACK
272 event succeededsucceeded, this event's result becames the result
273 value of fsl_db_txn_end().
274
275 To summarize, priority of determining which error code to return
276 from fsl_db_txn_end(), in combination with the potential for errors
277 when submitting the resulting SQL to commit/roll back, are:
278
279 - Commit: COMMIT event (this callback) -> SQLite step()
280
281 - Rollback: ROLLING_BACK event -> SQLite step() -> ROLLBACK event
282
283 This hook is NOT called for IMPLICIT transactions. It is only
284 called for explicit calls to fsl_db_txn_begin(), fsl_db_txn_end(),
285 and fsl_db_rollback_force(). Clients must never execute SQL-level
286 (BEGIN, COMMIT, ROLLBACK, SAVEPOINT) calls on fsl_db instances or
287 they risk getting it out of sync. There are exceptions where
288 they're safe but, generically speaking, they're not.
289
290 @see fsl_db_event_listener()
291*/
292typedef int (*fsl_db_event_f)(fsl_db_event const * e);
293
294/**
295 Db handle wrapper class. Each instance wraps a single sqlite
296 database handle. Though this type's interface is not opaque, it is
297 never legal for clients to directly manipulate the members.
298
299 Fossil is built upon sqlite3, but this abstraction is intended to
300 hide that, insofar as possible, from clients so as to simplify an
301 eventual port from v3 to v4. Clients should avoid relying on the
302 underlying db being sqlite (or at least not rely on a specific
303 version), but may want to register custom functions with the driver
304 (or perform similar low-level operations) and the option is left
305 open for them to access that handle via the fsl_db::dbh member. In
306 practice, library clients do not ever need to use the underlying
307 sqlite API.
308
309 @see fsl_db_open();
310 @see fsl_db_close();
311 @see fsl_stmt
312*/
313struct fsl_db {
314
315 /**
316 Underlying db driver handle.
317 */
319
320 /**
321 Holds error state from the underlying driver. fsl_db and
322 fsl_stmt operations which fail at the driver level "should"
323 update this state to include error info from the driver.
324 fsl_cx APIs which fail at the DB level uplift this (using
325 fsl_error_swap()) so that they can pass it on up the call chain.
326 */
328
329 /**
330 Holds the file name used when opening this db. Might not refer to
331 a real file (e.g. might be ":memory:" or "" (similar to
332 ":memory:" but may swap to temp storage).
333
334 Design note: we currently hold the name as it is passed to the
335 db-open routine, without canonicalizing it. That is very possibly
336 a mistake, as it makes it impossible to properly compare the name
337 to another arbitrary checkout-relative name for purposes of
338 fsl_reserved_fn_check(). For purposes of fsl_cx we currently
339 (2021-03-12) canonicalize db's which we fsl_db_open(), but not
340 those which we ATTACH (which includes the repo and checkout
341 dbs). We cannot reasonably canonicalize the repo db filename
342 because it gets written into the checkout db so that the checkout
343 knows where to find the repository. History has shown that that
344 path needs to be stored exactly as a user entered it, which is
345 often relative.
346
347 Memory is owned by this object.
348 */
349 char * filename;
350
351 /**
352 Holds the database name for use in creating queries.
353 Might or might not be set/needed, depending on
354 the context.
355
356 Memory is owned by this object.
357 */
358 char * name;
359 /**
360 Describes what role(s) this db connection plays in fossil (if
361 any). This is a bitmask of fsl_dbrole_e values, and a db
362 connection may have multiple roles. This is only used by the
363 fsl_cx-internal API.
364 */
366
367 /**
368 Private implementation details.
369 */
370 struct {
371 /**
372 Debugging/test counter. Closing a db with opened statements
373 might assert() or trigger debug output when the db is closed.
374 */
376
377 /**
378 Internal flags.
379 */
381
382 struct {
383 /** Event listener callback. */
385 /** Impl-specific state for f. */
386 void * state;
387 /**
388 The FSL_DB_EVENT_mask_id-masked part of event IDs to
389 fire the callback for.
390 */
392 /** Older-style (pre-fsl_db_event) trace output channel. */
393 FILE * fpTrace;
395
396 /** Transaction-related state. */
397 struct {
398 /** Counter for fsl_db_txn_begin/end(). */
399 int level;
400 /** Prepared statements for SAVEPOINT management. */
401 sqlite3_stmt * sSavepoint;
402 /** Prepared statements for SAVEPOINT RELEASE. */
403 sqlite3_stmt * sRelease;
404 /** Prepared statements for ROLLBACK TO SAVEPOINT. */
405 sqlite3_stmt * sRollback;
407
408 /** State for use with fsl_db_prepare_cached(). */
409 struct {
410
411 /**
412 An internal cache of "static" queries - those which do not rely
413 on call-time state unless that state can be bind()ed. Holds a
414 linked list of (fsl_stmt*) instances, managed by the
415 fsl_db_prepare_cached() and fsl_stmt_cached_yield() APIs.
416
417 @see fsl_db_prepare_cached()
418 */
421 /**
422 Internal buffer to reduce reallocations caused via
423 fsl_db_prepare_cached(), fsl_db_see_check(),
424 and perhaps other internals.
425 */
427
428 /**
429 A marker which tells fsl_db_close() whether or not
430 fsl_db_malloc() allocated this instance (in which case
431 fsl_db_close() will fsl_free() it) or not (in which case it
432 does not fsl_free() it).
433 */
434 void const * allocStamp;
436};
437/**
438 Empty-initialized fsl_db structure, intended for const-copy
439 initialization.
440*/
441#define fsl_db_empty_m { \
442 .dbh = NULL, \
443 .error = fsl_error_empty_m, \
444 .filename = NULL, \
445 .name = NULL, \
446 .role = 0, \
447 .impl = { \
448 .openStatementCount = 0, \
449 .flags = 0, \
450 .event = { \
451 .f=NULL, \
452 .state=NULL, \
453 .maskIds=0, \
454 .fpTrace=NULL \
455 }, \
456 .txn = { \
457 .level = 0, \
458 .sSavepoint=NULL, \
459 .sRelease=NULL, \
460 .sRollback=NULL \
461 }, \
462 .stCache = { \
463 .head = NULL \
464 }, \
465 .buffer = fsl_buffer_empty_m, \
466 .allocStamp = NULL \
467 } \
468}
469
470/**
471 Empty-initialized fsl_db structure, intended for copy
472 initialization.
473*/
475
476/**
477 If db is not NULL then this function returns its name (the one used
478 to fsl_db_open() it). The bytes are valid until the db connection
479 is closed or until someone mucks with db->filename. If len is not
480 NULL then *len is (on success) assigned to the length of the
481 returned string, in bytes. The string is NUL-terminated, so
482 fetching the length (by passing a non-NULL 2nd parameter) is
483 optional but sometimes useful to eliminate a downstream call to
484 fsl_strlen().
485
486 Results are undefined if db is NULL or was improperly initialized.
487 Will return NULL if db was properly initialized (via copying
488 fsl_db_empty) but has not yet been opened.
489*/
490FSL_EXPORT char const * fsl_db_filename(fsl_db const * db, fsl_size_t * len);
491
492typedef sqlite3_stmt fsl_stmt_t;
493/**
494 Represents a prepared statement handle.
495 Intended usage:
496
497 ```
498 fsl_stmt st = fsl_stmt_empty;
499 int rc = fsl_db_prepare( db, &st, "..." );
500 if(rc){ // Error!
501 assert(!st.stmt);
502 // db->error might hold driver-level error details.
503 }else{
504 // use st and eventually finalize it:
505 fsl_stmt_finalize( &st );
506 }
507 ```
508
509
510 Script binding implementations can largely avoid exposing the
511 statement handle (and its related cleanup ordering requirements)
512 to script code. They need to have some mechanism for binding
513 values to SQL (or implement all the escaping themselves), but
514 that can be done without exposing all of the statement class if
515 desired. For example, here's some hypothetical script code:
516
517 ```
518 var st = db.prepare(".... where i=:i and x=:x");
519 // st is-a Statement, but we need not add script bindings for
520 // the whole Statement.bind() API. We can instead simplify that
521 // to something like:
522 try {
523 st.exec( {i: 42, x: 3} )
524 // or, for a SELECT query:
525 st.each({
526 bind{i:42, x:3},
527 rowType: 'array', // or 'object'
528 callback: function(row,state,colNames){ print(row.join('\t')); },
529 state: {...callback function state...}
530 });
531 } finally {
532 st.finalize();
533 // It is critical that st gets finalized before its DB, and
534 // that'shard to guaranty if we leave st to the garbage collector!
535 }
536 // see below for another (less messy) alternative
537 ```
538
539 Ideally, script code should not have direct access to the
540 Statement because managing lifetimes can be difficult in the
541 face of flow-control changes caused by exceptions (as the above
542 example demonstrates). Statements can be completely hidden from
543 clients if the DB wrapper is written to support it. For example,
544 in pseudo-JavaScript that might look like:
545
546 ```
547 db.exec("...where i=? AND x=?", 42, 3);
548 db.each({sql:"select ... where id<?", bind:[10],
549 rowType: 'array', // or 'object'
550 callback: function(row,state,colNames){ print(row.join('\t')); },
551 state: {...arbitrary state for the callback...}
552 });
553 ```
554*/
555struct fsl_stmt {
556 /**
557 The db which prepared this statement.
558 */
560
561 /**
562 Underlying db driver-level statement handle. Clients should
563 not rely on the specify concrete type if they can avoid it, to
564 simplify an eventual port from sqlite3 to sqlite4.
565 */
567
568 /**
569 Describes the database(s) used by this statement handle, in the
570 form of a bitmask of fsl_dbrole_e values. This is a bit of a
571 kludge used to allow the internals to flush cached statements
572 from the fossil global config db when detaching that database.
573 Code which requires this to be set must set it itself and must
574 set it correctly. Hypothetically, no client-level code requires
575 it but _some_ libfossil-internal code does.
576 */
578
579 /**
580 The SQL used to prepare this statement. We keep this, rather than
581 simply fetching the SQL on demand, only for facilitate
582 fsl_db_prepare_cached(). But since we have it, and it might be
583 interesting, in client code, it's a public part of the interface.
584 */
586
587 /**
588 The number of times this statement has fetched a row via
589 fsl_stmt_step(). This is primarily intended for use by
590 fsl_stmt_each_f() implementations so that they can keep track of
591 when to emit a header (or similar pre-first-row setup).
592 */
594
595 /**
596 Private implementation details.
597 */
598 struct {
599
600 /**
601 Internal state flags.
602 */
604
605 /**
606 Internal use only: counts the number of times this query has
607 been resolved as cached via fsl_db_prepare_cached().
608 */
609 uint32_t cachedHits;
610
611 /**
612 For _internal_ use in creating linked lists. Clients _must_not_
613 modify this field.
614 */
616
617 /**
618 A marker which tells fsl_stmt_finalize() whether or not
619 fsl_stmt_malloc() allocated this instance (in which case
620 fsl_stmt_finalize() will fsl_free() it) or not (in which case
621 it does not free() it).
622 */
623 void const * allocStamp;
625};
626
627/**
628 Empty-initialized fsl_stmt instance, intended for use as an
629 in-struct initializer.
630*/
631#define fsl_stmt_empty_m { \
632 .db = NULL, \
633 .stmt = NULL, \
634 .role = 0, \
635 .sql = fsl_buffer_empty_m, \
636 .rowCount = 0, \
637 .impl = { \
638 .flags = 0, \
639 .cachedHits = 0, \
640 .next = NULL, \
641 .allocStamp = NULL \
642 } \
643}
644
645/**
646 Empty-initialized fsl_stmt instance, intended for
647 copy-constructing.
648*/
650
651/**
652 Allocates a new, cleanly-initialized fsl_stmt instance using
653 fsl_malloc(). The returned pointer must eventually be passed to
654 fsl_stmt_finalize() to free it (whether or not it is ever passed
655 to fsl_db_prepare()).
656
657 Returns NULL on allocation error.
658*/
660
661
662/**
663 Behaves like fsl_error_get(), using the db's underlying error
664 state. Results are undefined if !db.
665*/
667 char const ** msg, fsl_size_t * len );
668
669/**
670 Resets any error state in db, but might keep the string
671 memory allocated for later use.
672*/
674
675/**
676 Prepares an SQL statement for execution. On success it returns
677 0, populates tgt with the statement's state, and the caller is
678 obligated to eventually pass tgt to fsl_stmt_finalize(). tgt
679 must have been cleanly initialized, either via allocation via
680 fsl_stmt_malloc() or by copy-constructing fsl_stmt_empty
681 resp. fsl_stmt_empty_m (depending on the context).
682
683 On error non-0 is returned and tgt is not modified. If
684 preparation of the statement fails at the db level then
685 FSL_RC_DB is returned f's error state (fsl_cx_err_get())
686 "should" contain more details about the problem. Returns
687 FSL_RC_MISUSE if !db, !callback, or !sql. Returns
688 FSL_RC_NOT_FOUND if db is not opened. Returns FSL_RC_RANGE if
689 !*sql.
690
691 The sql string and the following arguments get routed through
692 fsl_appendf(), so any formatting options supported by that
693 routine may be used here. In particular, the %%q and %%Q
694 formatting options are intended for use in escaping SQL for
695 routines such as this one.
696
697 Compatibility note: in sqlite, empty SQL code evaluates
698 successfully but with a NULL statement. This API disallows empty
699 SQL because it uses NULL as a "no statement" marker and because
700 empty SQL is arguably not a query at all.
701
702 Tips:
703
704 - fsl_stmt_col_count() can be used to determine whether a
705 statement is a fetching query (fsl_stmt_col_count()>0) or not
706 (fsl_stmt_col_count()==0) without having to know the contents
707 of the query.
708
709 - fsl_db_prepare_cached() can be used to cache often-used or
710 expensive-to-prepare queries within the context of their parent
711 db handle.
712*/
714 char const * sql, ... );
715
716/**
717 va_list counterpart of fsl_db_prepare().
718*/
720 char const * sql, va_list args );
721
722/**
723 A special-purpose variant of fsl_db_prepare() which caches
724 statements based on their SQL code. This works very much like
725 fsl_db_prepare() and friends except that it can return the same
726 statement (via *st) multiple times (statements with identical
727 SQL are considered equivalent for caching purposes). Clients
728 need not explicitly pass the returned statement to
729 fsl_stmt_finalize() - the db holds these statements and will
730 finalize them when it is closed. It is legal to pass them to
731 finalize, in which case they will be cleaned up immediately but
732 that also invalidates _all_ pointers to the shared instances.
733
734 If client code does not call fsl_stmt_finalize(), it MUST pass
735 the statement pointer to fsl_stmt_cached_yield(st) after is done
736 with it. That makes the query available for use again with this
737 routine. If a cached query is not yielded via
738 fsl_stmt_cached_yield() then this routine will return
739 FSL_RC_ACCESS on subsequent requests for that SQL to prevent
740 that recursive (mis)use of the statement causes problems.
741
742 This routine is intended to be used in oft-called routines
743 where the cost of re-creating statements on each execution could
744 be prohibitive (or at least a bummer).
745
746 Returns 0 on success, FSL_RC_MISUSE if any arguments are
747 invalid. On error, *st is not written to. On other errors
748 db->error might be updated with more useful information. See the
749 Caveats section below for more details.
750
751 Its intended usage looks like:
752
753 ```
754 fsl_stmt * st = NULL;
755 int rc = fsl_db_prepare_cached(myDb, &st, "SELECT ...");
756 if(rc) { assert(!st); ...error... }
757 else {
758 ...use it, and _be sure_ to yield it when done:...
759 fsl_stmt_cached_yield(st);
760 }
761 ```
762
763 Though this function allows a formatted SQL string, caching is
764 generally only useful with statements which have "static" SQL,
765 i.e. no call-dependent values embedded within the SQL. It _can_,
766 however, contain bind() placeholders which get reset for each
767 use. Note that fsl_stmt_cached_yield() resets the statement, so
768 most uses of cached statements do not require that the client
769 explicitly reset cached statements (doing so is harmless,
770 however).
771
772 Caveats:
773
774 Cached queries must not be used in contexts where recursion might
775 cause the same query to be returned from this function while it is
776 being processed at another level in the execution stack. Results
777 would be undefined. Caching is primarily intended for often-used
778 routines which bind and fetch simple values, and not for queries
779 which bind large inlined values or might invoke recursion. Because
780 of the potential for recursive breakage, this function flags
781 queries it doles out and requires that clients call
782 fsl_stmt_cached_yield() to un-flag them for re-use. It will return
783 FSL_RC_ACCESS if an attempt is made to (re)prepare a statement for
784 which a fsl_stmt_cached_yield() is pending, and db->error will be
785 populated with a (long) error string describing the problem and
786 listing the SQL which caused the collision/misuse. Such SQL can
787 often be disambiguated by adding a \%s, wrapped in a C-style
788 comment, to the end and passing `__func__` as its value (which is
789 also useful for debugging in conjunction with SQL tracing).
790
791 Design note: for the recursion/parallel use case we "could"
792 reimplement this to dole out a new statement (e.g. by appending
793 " -- a_number" to the SQL to bypass the collision) and free it in
794 fsl_stmt_cached_yield(), but that (A) gets uglier than it needs
795 to be and (B) is not needed unless/until we really need cached
796 queries in spots which would normally break them. The whole
797 recursion problem is still theoretical at this point but could
798 easily affect small, often-used queries without recursion.
799
800 @see fsl_db_stmt_cache_clear()
801 @see fsl_stmt_cached_yield()
802*/
804 char const * sql, ... );
805
806/**
807 The va_list counterpart of fsl_db_prepare_cached().
808*/
810 char const * sql, va_list args );
811
812/**
813 "Yields" a statement which was prepared with
814 fsl_db_prepare_cached(), such that that routine can once again
815 use/re-issue that statement. Statements prepared this way must be
816 yielded in order to prevent that recursion causes
817 difficult-to-track errors when a given cached statement is used
818 concurrently in different code contexts.
819
820 If st is not NULL then this also calls fsl_stmt_reset() and
821 fsl_stmt_clear_bindings() on the statement.
822
823 Returns 0 on success, FSL_RC_MISUSE if !st or if st does not
824 appear to have been doled out from fsl_db_prepare_cached().
825
826 @see fsl_db_prepare_cached()
827 @see fsl_db_stmt_cache_clear()
828*/
830
831/**
832 Frees memory associated with stmt but does not free stmt unless
833 it was allocated by fsl_stmt_malloc() (these objects are
834 normally stack-allocated, and such object must be initialized by
835 copying fsl_stmt_empty so that this function knows whether or
836 not to fsl_free() them). Returns FSL_RC_MISUSE if !stmt or it
837 has already been finalized (but was not freed).
838*/
840
841/**
842 "Steps" the given SQL cursor one time. The return values
843 FSL_RC_STEP_ROW and FSL_RC_STEP_DONE are both success cases, the
844 former indicating that one row has been fetched and the latter
845 indicating that either no rows are left to fetch or the statement
846 is a non-fetching query. On error some other non-zero code will be
847 returned. On a db error this will update the underlying db's error
848 state. This function increments stmt->rowCount by 1 if it returns
849 FSL_RC_STEP_ROW.
850
851 Returns FSL_RC_MISUSE if !stmt or stmt has not been prepared.
852
853 It is only legal to call the fsl_stmt_g_xxx() and
854 fsl_stmt_get_xxx() functions if this functon returns
855 FSL_RC_STEP_ROW. FSL_RC_STEP_DONE is returned upon successfully
856 ending iteration or if there is no iteration to perform
857 (e.g. typically an UPDATE or INSERT, but see the next paragraph).
858
859 Though the historical definition of non-fetching query was pretty
860 clear, the addition of the RETURNING keyword to sqlite3's dialect
861 means that even an INSERT or DELETE can return data.
862
863 @see fsl_stmt_reset()
864 @see fsl_stmt_reset2()
865 @see fsl_stmt_each()
866*/
868
869/**
870 A callback interface for use with fsl_stmt_each() and
871 fsl_db_each(). It will be called one time for each row fetched,
872 passed the statement object and the state parameter passed to
873 fsl_stmt_each() resp. fsl_db_each(). If it returns non-0 then
874 iteration stops and that code is returned UNLESS it returns
875 FSL_RC_BREAK, in which case fsl_stmt_each() stops iteration and
876 returns 0. i.e. implementations may return FSL_RC_BREAK to
877 prematurly end iteration without causing an error.
878
879 This callback is not called for non-fetching queries or queries
880 which return no results, though it might (or might not) be
881 interesting for it to do so, passing a NULL stmt for that case.
882
883 stmt->rowCount can be used to determine how many times the
884 statement has called this function. Its counting starts at 1.
885
886 It is strictly illegal for a callback to pass stmt to
887 fsl_stmt_step(), fsl_stmt_reset(), fsl_stmt_finalize(), or any
888 similar routine which modifies its state. It must only read the
889 current column data (or similar metatdata, e.g. column names)
890 from the statement, e.g. using fsl_stmt_g_int32(),
891 fsl_stmt_get_text(), or similar.
892*/
893typedef int (*fsl_stmt_each_f)( fsl_stmt * stmt, void * state );
894
895/**
896 Calls the given callback one time for each result row in the
897 given statement, iterating over stmt using fsl_stmt_step(). It
898 applies no meaning to the callbackState parameter, which gets
899 passed as-is to the callback. See fsl_stmt_each_f() for the
900 semantics of the callback.
901
902 Returns 0 on success. Returns FSL_RC_MISUSE if !stmt or
903 !callback.
904*/
906 void * callbackState );
907
908/**
909 Resets the given statement, analog to sqlite3_reset(). Should be
910 called one time between fsl_stmt_step() iterations when running
911 multiple INSERTS, UPDATES, etc. via the same statement. If
912 resetRowCounter is true then the statement's row counter
913 (st->rowCount) is also reset to 0, else it is left
914 unmodified. (Most use cases don't use the row counter.)
915
916 Returns 0 on success, FSL_RC_MISUSE if stmt has not been prepared
917 or has not been cleanly initialized via copying from fsl_stmt_empty
918 or fsl_stmt_empty_m, FSL_RC_DB if the underlying reset fails (in
919 which case the error state of the stmt->db handle is updated to
920 contain the error information).
921
922 @see fsl_stmt_db()
923 @see fsl_stmt_reset()
924*/
925FSL_EXPORT int fsl_stmt_reset2( fsl_stmt * stmt, bool resetRowCounter );
926
927/**
928 Equivalent to fsl_stmt_reset2(stmt, false).
929*/
931
932/**
933 Clears memory associtated with any bindings on this statement.
934 This is a no-op if stmt is not prepared.
935*/
937
938/**
939 Returns the db handle which prepared the given statement, or
940 NULL if stmt has not been prepared.
941*/
943
944/**
945 Returns the SQL string used to prepare the given statement, or NULL
946 if stmt has not been prepared. If len is not NULL then *len is set
947 to the length of the returned string (which is NUL-terminated). The
948 returned bytes are owned by stmt and are invalidated when it is
949 finalized.
950*/
951FSL_EXPORT char const * fsl_stmt_sql( fsl_stmt * stmt,
952 fsl_size_t * len );
953
954/**
955 Returns the name of the given 0-based result column index, or
956 NULL if !stmt, stmt is not prepared, or index is out out of
957 range. The returned bytes are owned by the statement object and
958 may be invalidated shortly after this is called, so the caller
959 must copy the returned value if it needs to have any useful
960 lifetime guarantees. It's a bit more complicated than this, but
961 assume that any API calls involving the statement handle might
962 invalidate the column name bytes.
963
964 The API guarantees that the returned value is either NULL or
965 NUL-terminated.
966
967 @see fsl_stmt_param_count()
968 @see fsl_stmt_col_count()
969*/
970FSL_EXPORT char const * fsl_stmt_col_name(fsl_stmt * stmt, int index);
971
972/**
973 Returns the result column count for the given statement, or -1 if
974 !stmt or it has not been prepared. Note that this value is cached
975 when the statement is created. Note that non-fetching queries
976 (e.g. INSERT and UPDATE) have a column count of 0 unless they have
977 a RETURNING clause. Some non-SELECT constructs, e.g. PRAGMA
978 table_info(tname) and INSERT/UPDATE/DELETE with a RETURNING clause,
979 behave like a SELECT and have a positive column count.
980
981 @see fsl_stmt_param_count()
982 @see fsl_stmt_col_name()
983*/
985
986/**
987 Returns the bound parameter count for the given statement, or -1
988 if !stmt or it has not been prepared. Note that this value is
989 cached when the statement is created.
990
991 @see fsl_stmt_col_count()
992 @see fsl_stmt_col_name()
993*/
995
996/**
997 Returns the index of the given named parameter for the given
998 statement, or -1 if !stmt or stmt is not prepared.
999*/
1000FSL_EXPORT int fsl_stmt_param_index( fsl_stmt * stmt, char const * param);
1001
1002/**
1003 Binds NULL to the given 1-based parameter index. Returns 0 on
1004 succcess. Sets the DB's error state on error.
1005*/
1006FSL_EXPORT int fsl_stmt_bind_null( fsl_stmt * stmt, int index );
1007
1008/**
1009 Equivalent to fsl_stmt_bind_null_name() but binds to
1010 a named parameter.
1011*/
1012FSL_EXPORT int fsl_stmt_bind_null_name( fsl_stmt * stmt, char const * param );
1013
1014/**
1015 Binds v to the given 1-based parameter index. Returns 0 on
1016 succcess. Sets the DB's error state on error.
1017*/
1018FSL_EXPORT int fsl_stmt_bind_int32( fsl_stmt * stmt, int index, int32_t v );
1019
1020/**
1021 Equivalent to fsl_stmt_bind_int32() but binds to a named
1022 parameter.
1023*/
1024FSL_EXPORT int fsl_stmt_bind_int32_name( fsl_stmt * stmt, char const * param, int32_t v );
1025
1026/**
1027 Binds v to the given 1-based parameter index. Returns 0 on
1028 succcess. Sets the DB's error state on error.
1029*/
1030FSL_EXPORT int fsl_stmt_bind_int64( fsl_stmt * stmt, int index, int64_t v );
1031
1032/**
1033 Equivalent to fsl_stmt_bind_int64() but binds to a named
1034 parameter.
1035*/
1036FSL_EXPORT int fsl_stmt_bind_int64_name( fsl_stmt * stmt, char const * param, int64_t v );
1037
1038/**
1039 Binds v to the given 1-based parameter index. Returns 0 on
1040 succcess. Sets the Fossil context's error state on error.
1041*/
1042FSL_EXPORT int fsl_stmt_bind_double( fsl_stmt * stmt, int index, double v );
1043
1044/**
1045 Equivalent to fsl_stmt_bind_double() but binds to a named
1046 parameter.
1047*/
1048FSL_EXPORT int fsl_stmt_bind_double_name( fsl_stmt * stmt, char const * param, double v );
1049
1050/**
1051 Binds v to the given 1-based parameter index. Returns 0 on
1052 succcess. Sets the DB's error state on error.
1053*/
1054FSL_EXPORT int fsl_stmt_bind_id( fsl_stmt * stmt, int index, fsl_id_t v );
1055
1056/**
1057 Equivalent to fsl_stmt_bind_id() but binds to a named
1058 parameter.
1059*/
1060FSL_EXPORT int fsl_stmt_bind_id_name( fsl_stmt * stmt, char const * param, fsl_id_t v );
1061
1062/**
1063 Binds the first n bytes of v as text to the given 1-based bound
1064 parameter column in the given statement. If makeCopy is true then
1065 the binding makes an copy of the data. Set makeCopy to false ONLY
1066 if you KNOW that the bytes will outlive the binding.
1067
1068 Returns 0 on success. On error stmt's underlying db's error state
1069 is updated, hopefully with a useful error message.
1070*/
1072 char const * v, fsl_int_t n,
1073 bool makeCopy );
1074
1075/**
1076 Equivalent to fsl_stmt_bind_text() but binds to a named
1077 parameter.
1078*/
1079FSL_EXPORT int fsl_stmt_bind_text_name( fsl_stmt * stmt, char const * param,
1080 char const * v, fsl_int_t n,
1081 bool makeCopy );
1082/**
1083 Binds the first n bytes of v as a blob to the given 1-based bound
1084 parameter column in the given statement. See fsl_stmt_bind_text()
1085 for the semantics of the makeCopy parameter and return value.
1086*/
1088 void const * v, fsl_size_t len,
1089 bool makeCopy );
1090
1091/**
1092 Equivalent to fsl_stmt_bind_blob() but binds to a named
1093 parameter.
1094*/
1095FSL_EXPORT int fsl_stmt_bind_blob_name( fsl_stmt * stmt, char const * param,
1096 void const * v, fsl_int_t len,
1097 bool makeCopy );
1098
1099/**
1100 Gets an integer value from the given 0-based result set column,
1101 assigns *v to that value, and returns 0 on success.
1102
1103 Returns FSL_RC_RANGE if index is out of range for stmt, FSL_RC_MISUSE
1104 if stmt has no result columns.
1105*/
1106FSL_EXPORT int fsl_stmt_get_int32( fsl_stmt * stmt, int index, int32_t * v );
1107
1108/**
1109 Gets an integer value from the given 0-based result set column,
1110 assigns *v to that value, and returns 0 on success.
1111
1112 Returns FSL_RC_RANGE if index is out of range for stmt, FSL_RC_MISUSE
1113 if stmt has no result columns.
1114*/
1115FSL_EXPORT int fsl_stmt_get_int64( fsl_stmt * stmt, int index, int64_t * v );
1116
1117/**
1118 The fsl_id_t counterpart of fsl_stmt_get_int32(). Depending on
1119 the sizeof(fsl_id_t), it behaves as one of fsl_stmt_get_int32()
1120 or fsl_stmt_get_int64().
1121*/
1122FSL_EXPORT int fsl_stmt_get_id( fsl_stmt * stmt, int index, fsl_id_t * v );
1123
1124/**
1125 Convenience form of fsl_stmt_get_id() which returns the value
1126 directly but cannot report errors. It returns -1 on error, but
1127 that is not unambiguously an error value.
1128*/
1130
1131/**
1132 Convenience form of fsl_stmt_get_int32() which returns the value
1133 directly but cannot report errors. It returns 0 on error, but
1134 that is not unambiguously an error.
1135*/
1136FSL_EXPORT int32_t fsl_stmt_g_int32( fsl_stmt * stmt, int index );
1137
1138/**
1139 Convenience form of fsl_stmt_get_int64() which returns the value
1140 directly but cannot report errors. It returns 0 on error, but
1141 that is not unambiguously an error.
1142*/
1143FSL_EXPORT int64_t fsl_stmt_g_int64( fsl_stmt * stmt, int index );
1144
1145/**
1146 Convenience form of fsl_stmt_get_double() which returns the value
1147 directly but cannot report errors. It returns 0 on error, but
1148 that is not unambiguously an error.
1149*/
1150FSL_EXPORT double fsl_stmt_g_double( fsl_stmt * stmt, int index );
1151
1152/**
1153 Convenience form of fsl_stmt_get_text() which returns the value
1154 directly but cannot report errors. It returns NULL on error, but
1155 that is not unambiguously an error because it also returns NULL
1156 if the column contains an SQL NULL value. If outLen is not NULL
1157 then it is set to the byte length of the returned string.
1158*/
1159FSL_EXPORT char const * fsl_stmt_g_text( fsl_stmt * stmt, int index, fsl_size_t * outLen );
1160
1161/**
1162 Gets double value from the given 0-based result set column,
1163 assigns *v to that value, and returns 0 on success.
1164
1165 Returns FSL_RC_RANGE if index is out of range for stmt, FSL_RC_MISUSE
1166 if stmt has no result columns.
1167*/
1168FSL_EXPORT int fsl_stmt_get_double( fsl_stmt * stmt, int index, double * v );
1169
1170/**
1171 Gets a string value from the given 0-based result set column,
1172 assigns *out (if out is not NULL) to that value, assigns *outLen
1173 (if outLen is not NULL) to *out's length in bytes, and returns 0
1174 on success. Ownership of the string memory is unchanged - it is owned
1175 by the statement and the caller should immediately copy it if
1176 it will be needed for much longer.
1177
1178 Returns FSL_RC_RANGE if index is out of range for stmt,
1179 FSL_RC_MISUSE if stmt has no result columns. Returns FSL_RC_OOM if
1180 fetching the text from the underlying statement handle fails due to
1181 an allocation error.
1182*/
1183FSL_EXPORT int fsl_stmt_get_text( fsl_stmt * stmt, int index, char const **out,
1184 fsl_size_t * outLen );
1185
1186/**
1187 The Blob counterpart of fsl_stmt_get_text(). Identical to that
1188 function except that its output result (3rd paramter) type
1189 differs, and it fetches the data as a raw blob, without any sort
1190 of string interpretation.
1191
1192 Returns FSL_RC_RANGE if index is out of range for stmt,
1193 FSL_RC_MISUSE if stmt has no result columns. Returns FSL_RC_OOM if
1194 fetching the text from the underlying statement handle fails due to
1195 an allocation error.
1196*/
1197FSL_EXPORT int fsl_stmt_get_blob( fsl_stmt * stmt, int index, void const **out, fsl_size_t * outLen );
1198
1199/**
1200 Executes multiple SQL statements, ignoring any results they might
1201 collect. Returns 0 on success, non-0 on error. On error
1202 db->error might be updated to report the problem.
1203*/
1204FSL_EXPORT int fsl_db_exec_multi( fsl_db * db, const char * sql, ...);
1205
1206/**
1207 va_list counterpart of db_exec_multi().
1208*/
1209FSL_EXPORT int fsl_db_exec_multiv( fsl_db * db, const char * sql, va_list args);
1210
1211/**
1212 Executes a single SQL statement, skipping over any results it may
1213 have. Returns 0 on success. On error db's error state may be
1214 updated. Note that this function translates FSL_RC_STEP_DONE and
1215 FSL_RC_STEP_ROW to 0. For cases where those particular result codes
1216 are significant, use fsl_db_prepare() and fsl_stmt_step() (for
1217 which this function is just a proxy).
1218*/
1219FSL_EXPORT int fsl_db_exec( fsl_db * db, char const * sql, ... );
1220
1221/**
1222 va_list counterpart of fs_db_exec().
1223*/
1224FSL_EXPORT int fsl_db_execv( fsl_db * db, char const * sql, va_list args );
1225
1226/**
1227 Begins a transaction on the given db.
1228
1229 This API historically used pseudo-nested transactions based off of
1230 BEGIN/COMMIT. As of 2025-08-09 it uses SAVEPOINTs instead. The
1231 difference is subtle but was a necessary change for the libfossil
1232 SCM pieces to be able to behave sensibly in some cases. These docs
1233 use the term "transaction" to mean "savepoint".
1234
1235 Returns FSL_RC_MISUSE if !db or the db is not connected, else the
1236 result of the underlying db call(s).
1237
1238 Transactions are an easy way to implement "dry-run" mode for
1239 some types of applications. For example:
1240
1241 ```
1242 bool dryRunMode = ...;
1243 fsl_db_txn_begin(db);
1244 ...do your stuff...
1245 fsl_db_txn_end_v2(db, dryRunMode, false);
1246 ```
1247
1248 Here's a tip for propagating error codes when using
1249 transactions:
1250
1251 ```
1252 ...
1253 if(rc) fsl_db_txn_end_v2(db, false, possiblyTrue);
1254 else rc = fsl_db_txn_end_v2(db, true, false);
1255 ```
1256
1257 That ensures that we propagate rc in the face of a rollback but we
1258 also capture the rc for a commit (which might yet fail).
1259
1260 Sidebar: this API, prior to 2025-08, used pseudo-nested
1261 transactions directly ported from fossil(1) (essentially a
1262 reference-counted BEGIN/END block, with each level representing one
1263 reference count point). As of 2025-08 it exclusively uses sqlite3's
1264 SAVEPOINT[^1] feature, which is essentially nested transactions.
1265 This change enables better support for dry-run modes and more
1266 flexible non-fatal-to-the-transaction error handling. e.g. we can
1267 fail certain opertations, e.g. lookup of a resources, without
1268 inherently invalidating the whole transaction stack.
1269
1270 [^1]: https://sqlite.org/lang_savepoint.html
1271*/
1273
1274/**
1275 Equivalent to fsl_db_txn_end_v2(db, true, false).
1276*/
1278
1279/**
1280 Equivalent to fsl_db_txn_end_v2(db, false, true), noting that the
1281 final value of true there is for historical API compatibility and
1282 will be changed to false if we can get away with it elsewhere.
1283*/
1285
1286#if 0
1287/**
1288 Forces a rollback of any pending transaction in db, regardless of
1289 the internal transaction begin/end counter. Returns FSL_RC_MISUSE
1290 if db is not opened, else returns the value of the underlying
1291 ROLLBACK call. This also re-sets/frees any transaction-related
1292 state held by db (e.g. db->beforeCommit). Use with care, as this
1293 mucks about with db state in a way which is not all that pretty and
1294 it may confuse downstream code.
1295
1296 Returns 0 on success.
1297
1298 Never, ever use this. In 12+ years it has never proven necessary to
1299 use this function, and doing so can easily lead to a mismatch in
1300 transaction-using code and the transaction stack level.
1301*/
1302FSL_EXPORT int fsl_db_rollback_force(fsl_db * db);
1303#endif
1304
1305/**
1306 Decrements the transaction counter incremented by
1307 fsl_db_txn_begin() and commits or rolls back the
1308 savepoint if the counter goes to 0.
1309
1310 The behavior of keepSavepoint depends on the transaction depth:
1311
1312 - If this is not the top-most savepoint, it is "released" (applied)
1313 if keepSavepoint is true or rolled back if keepSavepoint false,
1314 and that resulting db result code is returned. A value of true
1315 releases this savepoint regardless of the bubbleRollback flag
1316 (see below).
1317
1318 - If this is the top-most savepoint then keepSavepoint will be
1319 considered to be false if bubbleRollback is true or if any call
1320 to this function in the same top-level transaction stack flag has
1321 passed true for that argument.
1322
1323 If bubbleRollback is true, or any call to this function within the
1324 same top-level savepoint passed true as the bubbleRollback
1325 argument, the transaction is put into a persistent will-rollback
1326 mode. In this mode, individual savepoints can still be applied by
1327 passing true as the second argument, but when the final one is
1328 popped, the whole thing will be rolled back instead of applied.
1329
1330 To reiterate: if db fsl_db_txn_begin() is used in a nested manner
1331 and bubbleRollback is true for any one of the nested calls, then
1332 that value will be remembered, such that the downstream calls to
1333 this function within the same transaction will behave as if
1334 bubbleRollback were true even if they pass false for the third
1335 argument.
1336
1337 Achtung: the bubbleRollback==true behavior is, as of 2025-08,
1338 considered "legacy" and should no longer be used, but much code
1339 still currently expects that behavior.
1340
1341 The distinction been whether retaining a savepoint should put the
1342 transaction into a persistent rollback state is primarily of
1343 interest to operations which implement "dry-run" mode. For
1344 dry-run, keepSavepoint should always ben false, while
1345 bubbleRollback should be true if the operation failed in a way
1346 which could impact further operations in the same transaction.
1347
1348 Returns FSL_RC_MISUSE if db is not opened, 0 if the transaction
1349 counter is above 0, else the result of the (potentially many)
1350 underlying database operations.
1351*/
1352FSL_EXPORT int fsl_db_txn_end_v2(fsl_db * db, bool keepSavepoint,
1353 bool bubbleRollback);
1354
1355/**
1356 Equivalent to fsl_db_txn_end_v2(DB, !DOROLLBACK, !!DOROLLBACK),
1357 which mimics the historical behavior of this API.
1358*/
1359#define fsl_db_txn_end(DB,DOROLLBACK) \
1360 fsl_db_txn_end_v2((DB), !(DOROLLBACK), !!(DOROLLBACK))
1361
1362/**
1363 Returns the given db's current transaction depth. If the value is
1364 negative, its absolute value represents the depth but indicates
1365 that a rollback is pending. If it is positive, the transaction is
1366 still in a "good" state. If it is 0, no transaction is active.
1367*/
1369
1370/**
1371 Runs the given SQL query on the given db and returns true if the
1372 query returns any rows, else false. Returns 0 for any error as
1373 well.
1374*/
1375FSL_EXPORT bool fsl_db_exists(fsl_db * db, char const * sql, ... );
1376
1377/**
1378 va_list counterpart of fsl_db_exists().
1379*/
1380FSL_EXPORT bool fsl_db_existsv(fsl_db * db, char const * sql, va_list args );
1381
1382/**
1383 Runs a fetch-style SQL query against DB and returns the first
1384 column of the first result row via *rv. If the query returns no
1385 rows, *rv is not modified. The intention is that the caller sets
1386 *rv to his preferred default (or sentinel) value before calling
1387 this.
1388
1389 The format string (the sql parameter) accepts all formatting
1390 options supported by fsl_appendf().
1391
1392 Returns 0 on success. On error db's error state is updated and
1393 *rv is not modified.
1394
1395 Returns FSL_RC_MISUSE without side effects if !db, !rv, !sql,
1396 or !*sql.
1397*/
1398FSL_EXPORT int fsl_db_get_int32( fsl_db * db, int32_t * rv,
1399 char const * sql, ... );
1400
1401/**
1402 va_list counterpart of fsl_db_get_int32().
1403*/
1404FSL_EXPORT int fsl_db_get_int32v( fsl_db * db, int32_t * rv,
1405 char const * sql, va_list args);
1406
1407/**
1408 Convenience form of fsl_db_get_int32() which returns the value
1409 directly but provides no way of checking for errors. On error,
1410 or if no result is found, defaultValue is returned.
1411*/
1413 int32_t defaultValue,
1414 char const * sql, ... );
1415
1416/**
1417 The int64 counterpart of fsl_db_get_int32(). See that function
1418 for the semantics.
1419*/
1420FSL_EXPORT int fsl_db_get_int64( fsl_db * db, int64_t * rv,
1421 char const * sql, ... );
1422
1423/**
1424 va_list counterpart of fsl_db_get_int64().
1425*/
1426FSL_EXPORT int fsl_db_get_int64v( fsl_db * db, int64_t * rv,
1427 char const * sql, va_list args);
1428
1429/**
1430 Convenience form of fsl_db_get_int64() which returns the value
1431 directly but provides no way of checking for errors. On error,
1432 or if no result is found, defaultValue is returned.
1433*/
1434FSL_EXPORT int64_t fsl_db_g_int64( fsl_db * db, int64_t defaultValue,
1435 char const * sql, ... );
1436
1437
1438/**
1439 The fsl_id_t counterpart of fsl_db_get_int32(). See that function
1440 for the semantics.
1441*/
1443 char const * sql, ... );
1444
1445/**
1446 va_list counterpart of fsl_db_get_id().
1447*/
1449 char const * sql, va_list args);
1450
1451/**
1452 Convenience form of fsl_db_get_id() which returns the value
1453 directly but provides no way of checking for errors. On error,
1454 or if no result is found, defaultValue is returned.
1455*/
1457 char const * sql, ... );
1458
1459
1460/**
1461 The fsl_size_t counterpart of fsl_db_get_int32(). See that
1462 function for the semantics. If this function would fetch a
1463 negative value, it returns FSL_RC_RANGE and *rv is not modified.
1464*/
1466 char const * sql, ... );
1467
1468/**
1469 va_list counterpart of fsl_db_get_size().
1470*/
1472 char const * sql, va_list args);
1473
1474/**
1475 Convenience form of fsl_db_get_size() which returns the value
1476 directly but provides no way of checking for errors. On error,
1477 or if no result is found, defaultValue is returned.
1478*/
1480 fsl_size_t defaultValue,
1481 char const * sql, ... );
1482
1483
1484/**
1485 The double counterpart of fsl_db_get_int32(). See that function
1486 for the semantics.
1487*/
1488FSL_EXPORT int fsl_db_get_double( fsl_db * db, double * rv,
1489 char const * sql, ... );
1490
1491/**
1492 va_list counterpart of fsl_db_get_double().
1493*/
1494FSL_EXPORT int fsl_db_get_doublev( fsl_db * db, double * rv,
1495 char const * sql, va_list args);
1496
1497/**
1498 Convenience form of fsl_db_get_double() which returns the value
1499 directly but provides no way of checking for errors. On error,
1500 or if no result is found, defaultValue is returned.
1501*/
1502FSL_EXPORT double fsl_db_g_double( fsl_db * db, double defaultValue,
1503 char const * sql, ... );
1504
1505/**
1506 The C-string counterpart of fsl_db_get_int32(). On success *rv
1507 will be set to a dynamically allocated string copied from the
1508 first column of the first result row. If rvLen is not NULL then
1509 *rvLen will be assigned the byte-length of that string. If no
1510 row is found, *rv is set to NULL and *rvLen (if not NULL) is set
1511 to 0, and 0 is returned. Note that NULL is also a legal result
1512 (an SQL NULL translates as a NULL string), The caller must
1513 eventually free the returned string value using fsl_free().
1514*/
1515FSL_EXPORT int fsl_db_get_text( fsl_db * db, char ** rv, fsl_size_t * rvLen,
1516 char const * sql, ... );
1517
1518/**
1519 va_list counterpart of fsl_db_get_text().
1520*/
1521FSL_EXPORT int fsl_db_get_textv( fsl_db * db, char ** rv, fsl_size_t * rvLen,
1522 char const * sql, va_list args );
1523
1524/**
1525 Convenience form of fsl_db_get_text() which returns the value
1526 directly but provides no way of checking for errors. On error,
1527 or if no result is found, NULL is returned. The returned string
1528 must eventually be passed to fsl_free() to free it. If len is
1529 not NULL then if non-NULL is returned, *len will be assigned the
1530 byte-length of the returned string.
1531*/
1533 char const * sql,
1534 ... );
1535
1536/**
1537 The Blob counterpart of fsl_db_get_text(). Identical to that
1538 function except that its output result (2nd paramter) type
1539 differs, and it fetches the data as a raw blob, without any sort
1540 of string interpretation. The returned *rv memory must
1541 eventually be passed to fsl_free() to free it. If len is not
1542 NULL then on success *len will be set to the byte length of the
1543 returned blob. If no row is found, *rv is set to NULL and *rvLen
1544 (if not NULL) is set to 0, and 0 is returned. Note that NULL is
1545 also a legal result (an SQL NULL translates as a NULL string),
1546*/
1547FSL_EXPORT int fsl_db_get_blob( fsl_db * db, void ** rv, fsl_size_t * len,
1548 char const * sql, ... );
1549
1550
1551/**
1552 va_list counterpart of fsl_db_get_blob().
1553*/
1554FSL_EXPORT int fsl_db_get_blobv( fsl_db * db, void ** rv, fsl_size_t * stmtLen,
1555 char const * sql, va_list args );
1556
1557/**
1558 Convenience form of fsl_db_get_blob() which returns the value
1559 directly but provides no way of checking for errors. On error,
1560 or if no result is found, NULL is returned.
1561*/
1563 char const * sql,
1564 ... );
1565/**
1566 Similar to fsl_db_get_text() and fsl_db_get_blob(), but writes
1567 its result to tgt, appending its results to the given buffer.
1568
1569 If asBlob is true then the underlying BLOB API is used to
1570 populate the buffer, else the underlying STRING/TEXT API is
1571 used. For many purposes there will be no difference, but if you
1572 know you might have binary data, be sure to pass a true value
1573 for asBlob to avoid any potential encoding-related problems.
1574
1575 Results are undefined if any pointer argument is NULL. Returns
1576 FSL_RC_MISUSE if the SQL is an empty string.
1577*/
1579 bool asBlob, char const * sql,
1580 ... );
1581
1582/**
1583 va_list counterpart of fsl_db_get_buffer().
1584*/
1586 bool asBlob, char const * sql,
1587 va_list args );
1588
1589
1590/**
1591 Expects sql to be a SELECT-style query which (potentially)
1592 returns a result set. For each row in the set callback() is
1593 called, as described for fsl_stmt_each(). Returns 0 on success.
1594 The callback is _not_ called for queries which return no
1595 rows. If clients need to know if rows were returned, they can
1596 add a counter to their callbackState and increment it from the
1597 callback.
1598
1599 Returns FSL_RC_MISUSE if db is not opened, !callback,
1600 !sql. Returns FSL_RC_RANGE if !*sql.
1601*/
1603 void * callbackState, char const * sql, ... );
1604
1605/**
1606 va_list counterpart to fsl_db_each().
1607*/
1609 void * callbackState, char const * sql, va_list args );
1610
1611
1612/**
1613 Returns the given Julian date value formatted as an ISO8601
1614 string (with a fractional seconds part if msPrecision is true,
1615 else without it). Returns NULL if !db, db is not connected, j
1616 is less than 0, or on allocation error. The returned memory must
1617 eventually be freed using fsl_free().
1618
1619 If localTime is true then the value is converted to the local time,
1620 otherwise it is not.
1621
1622 @see fsl_db_unix_to_iso8601()
1623 @see fsl_julian_to_iso8601()
1624 @see fsl_iso8601_to_julian()
1625*/
1627 bool msPrecision, bool localTime );
1628
1629/**
1630 Returns the given Julian date value formatted as an ISO8601
1631 string (with a fractional seconds part if msPrecision is true,
1632 else without it). Returns NULL if !db, db is not connected, j
1633 is less than 0, or on allocation error. The returned memory must
1634 eventually be freed using fsl_free().
1635
1636 If localTime is true then the value is converted to the local time,
1637 otherwise it is not.
1638
1639 @see fsl_db_julian_to_iso8601()
1640 @see fsl_julian_to_iso8601()
1641 @see fsl_iso8601_to_julian()
1642*/
1644 bool localTime );
1645
1646
1647/**
1648 Returns the current time in Julian Date format. Returns a negative
1649 value if !db or db is not opened.
1650*/
1652
1653/**
1654 Uses the given db to convert the given time string to Julian Day
1655 format. If it cannot be converted, a negative value is returned.
1656 The str parameter can be anything suitable for passing to sqlite's:
1657
1658 SELECT julianday(str)
1659
1660 Note that this routine will escape str for use with SQL - the
1661 caller must not do so.
1662
1663 @see fsl_julian_to_iso8601()
1664 @see fsl_iso8601_to_julian()
1665*/
1666FSL_EXPORT double fsl_db_string_to_julian(fsl_db * db, char const * str);
1667
1668/**
1669 Opens the given db file and populates db with its handle. db
1670 must have been cleanly initialized by copy-initializing it from
1671 fsl_db_empty (or fsl_db_empty_m) or by allocating it using
1672 fsl_db_malloc(). Failure to do so will lead to undefined
1673 behaviour.
1674
1675 openFlags may be a mask of FSL_DB_OPEN_xxx values, but not all are
1676 used/supported here. If FSL_DB_OPEN_CREATE is _not_ set in
1677 openFlags and dbFile does not exist, it will return
1678 FSL_RC_NOT_FOUND. The existence of FSL_DB_OPEN_CREATE in the flags
1679 will cause this routine to try to create the file if needed. If
1680 conflicting flags are specified (e.g. FSL_DB_OPEN_RO and
1681 FSL_DB_OPEN_RWC) then which one takes precedence is unspecified and
1682 possibly unpredictable. If openFlags is 0 then FSL_DB_OPEN_RO is
1683 assumed.
1684
1685 This routine normally looks for the given file before attempting to
1686 open it and will update db's error state if the file cannot be
1687 found. Those checks are skipped if (1) openFlags has the
1688 FSL_DB_OPEN_CREATE bit set, (2) dbName is empty (indicating a
1689 nameless temporary database), (3) the string contains a ":" in any
1690 byte position, in which case it is assumed to be a URL-style name
1691 or ":memory:". The exception to (3) is on Windows platforms, where
1692 it recognize drive letter prefixes in the form "X:".
1693
1694 See this page for the differences between ":memory:" and "":
1695
1696 https://www.sqlite.org/inmemorydb.html
1697
1698 This routine does not handle URL-style file names.
1699
1700 Returns FSL_RC_MISUSE if !db, !dbFile, or if db->dbh is not NULL
1701 (i.e. if it is already opened or its memory was default-initialized
1702 (use fsl_db_empty to cleanly copy-initialize new stack-allocated
1703 instances).
1704
1705 On error db->dbh will be NULL, but db->error might contain error
1706 details.
1707
1708 Regardless of success or failure, db should be passed to
1709 fsl_db_close() to free up all memory associated with it. It is
1710 not closed automatically by this function because doing so cleans
1711 up the error state, which the caller will presumably want to
1712 have.
1713
1714 @see fsl_db_close()
1715 @see fsl_db_prepare()
1716 @see fsl_db_malloc()
1717*/
1718FSL_EXPORT int fsl_db_open( fsl_db * db, char const * dbFile,
1719 fsl_flag32_t openFlags );
1720
1721/**
1722 Closes the given db handle and frees any resources owned by
1723 db. This function is a no-op if db is NULL.
1724
1725 If db was allocated using fsl_db_malloc() (as determined by
1726 examining db->allocStamp) then this routine also fsl_free()s it,
1727 otherwise it is assumed to either be on the stack or part of a
1728 larger struct and is not freed, but any resources it allocated are
1729 freed.
1730
1731 If db has any pending transactions, they are rolled back by this
1732 function before a FSL_DB_EVENT_CLOSING event is fired.
1733*/
1735
1736/**
1737 If db is an opened db handle, this registers a debugging
1738 function with the db which traces all SQL to the given FILE
1739 handle. If outStream is NULL then tracing events will be
1740 emitted via FSL_DB_EVENT_TRACE_SQLX instead.
1741
1742 If expandedSql is true then it uses sqlite3_expanded_sql() to
1743 expand each traced statement, else it uses unexpanded SQL (which is
1744 much faster).
1745
1746 If outStream is not NULL then tracing will go there, otherwise it
1747 will go out via a FSL_DB_EVENT_TRACE_SQL or FSL_DB_EVENT_TRACE_SQLX
1748 event (depending on the value of expandedSql). Ownership of
1749 outStream is not modified by this call and outStream must outlive
1750 its association with db.
1751
1752 This is a no-op if db is closed.
1753
1754 This mechanism is only intended for debugging and exploration of
1755 how Fossil works. Tracing is often as easy way to ensure that a
1756 given code block is getting run.
1757
1758 TODOs:
1759
1760 - Expand this API to take a client-side callback and state
1761 object, rather than a FILE pointer.
1762
1763 - Provide a toggle for the tracing level: with and without
1764 "expanded" SQL. Expanding the SQL to include its bound values is
1765 far more expensive (but also far more informative).
1766*/
1767FSL_EXPORT void fsl_db_sqltrace_enable( fsl_db * db, FILE * outStream,
1768 bool expandSql);
1769
1770/**
1771 Returns the row ID of the most recent insertion,
1772 or -1 if !db, db is not connected, or 0 if no inserts
1773 have been performed.
1774*/
1776
1777/**
1778 Returns non-0 (true) if the database (which must be open) table
1779 identified by zTableName has a column named zColName
1780 (case-sensitive), else returns 0.
1781*/
1783 char const *zTableName,
1784 char const *zColName );
1785
1786/**
1787 If a db name has been associated with db then it is returned,
1788 otherwise NULL is returned. A db has no name by default, but
1789 fsl_cx-used ones get their database name assigned to them
1790 (e.g. "main" for the main db).
1791*/
1792FSL_EXPORT char const * fsl_db_name(fsl_db const * db);
1793
1794/**
1795 Returns a db name string for the given fsl_db_role value. The
1796 string is static, guaranteed to live as long as the app. It
1797 returns NULL if passed FSL_DBROLE_NONE or some value out of range
1798 for the enum.
1799*/
1801
1802/**
1803 Allocates a new fsl_db instance(). Returns NULL on allocation
1804 error. Note that fsl_db instances can often be used from the
1805 stack - allocating them dynamically is an uncommon case necessary
1806 for script bindings.
1807
1808 Achtung: the returned value's allocStamp member is used for
1809 determining if fsl_db_close() should free the value or not. Thus
1810 if clients copy over this value without adjusting allocStamp back
1811 to its original value, the library will likely leak the instance.
1812 Been there, done that.
1813*/
1815
1816/**
1817 The fsl_stmt counterpart of fsl_db_malloc(). See that function
1818 for when you might want to use this and a caveat involving the
1819 allocStamp member of the returned value. fsl_stmt_finalize() will
1820 free statements created with this function.
1821*/
1823
1824/**
1825 ATTACHes the file zDbName to db using the database name zLabel
1826 (which gets quoted as an SQL identifier). Returns 0 on
1827 success. Returns FSL_RC_MISUSE if any argument is NULL or any
1828 string argument starts with a NUL byte, else it returns the result
1829 of fsl_db_exec() which attaches the db. On db-level errors db's
1830 error state will be updated.
1831*/
1832FSL_EXPORT int fsl_db_attach(fsl_db * db, const char *zDbName,
1833 const char *zLabel);
1834
1835/**
1836 The converse of fsl_db_detach(). Must be passed the same arguments
1837 which were passed as the 1st and 3rd arguments to fsl_db_attach().
1838 Returns 0 on success, FSL_RC_MISUSE if !db, !zLabel, or !*zLabel,
1839 else it returns the result of the underlying fsl_db_exec()
1840 call.
1841*/
1842FSL_EXPORT int fsl_db_detach(fsl_db * db, const char *zLabel);
1843
1844/**
1845 Expects fmt to be a SELECT-style query. For each row in the
1846 query, the first column is fetched as a string and appended to
1847 the tgt list.
1848
1849 Returns 0 on success, FSL_RC_MISUSE if !fmt or fmt is empty, or any
1850 number of potential FSL_RC_OOM or db-related errors.
1851
1852 Results rows with a NULL value (resulting from an SQL NULL) are
1853 added to the list as NULL entries.
1854
1855 Each entry appended to the list is a (char *) which must
1856 be freed using fsl_free(). To easiest way to clean up
1857 the list and its contents is:
1858
1859 ```
1860 fsl_list_visit_free(tgt,...);
1861 ```
1862
1863 On error the list may be partially populated.
1864
1865 Complete example:
1866
1867 ```
1868 fsl_list li = fsl_list_empty;
1869 int rc = fsl_db_select_slist(db, &li,
1870 "SELECT uuid FROM blob WHERE rid<20");
1871 if(!rc){
1872 fsl_size_t i;
1873 for(i = 0;i < li.used; ++i){
1874 char const * uuid = (char const *)li.list[i];
1875 fsl_fprintf(stdout, "UUID: %s\n", uuid);
1876 }
1877 }
1878 fsl_list_visit_free(&li, 1);
1879 ```
1880
1881 Of course fsl_list_visit() may be used to traverse the list as
1882 well, as long as the visitor expects (char [const]*) list
1883 elements.
1884*/
1886 char const * fmt, ... );
1887
1888/**
1889 The va_list counterpart of fsl_db_select_slist().
1890*/
1892 char const * fmt, va_list args );
1893
1894/**
1895 Returns n bytes of random lower-case hexidecimal characters
1896 using the given db as its data source, plus a terminating NUL
1897 byte. The returned memory must eventually be freed using
1898 fsl_free(). Returns NULL if !n, db is not opened, or on a db-level error.
1899*/
1901
1902/**
1903 Returns the "number of database rows that were changed or inserted
1904 or deleted by the most recently completed SQL statement" (to quote
1905 the underlying APIs). Returns 0 if db is not opened.
1906
1907 See: https://sqlite.org/c3ref/changes.html
1908*/
1910
1911/**
1912 Returns "the number of row changes caused by INSERT, UPDATE or
1913 DELETE statements since the database connection was opened" (to
1914 quote the underlying APIs). Returns 0 if db is not opened.
1915
1916 See; https://sqlite.org/c3ref/total_changes.html
1917*/
1919
1920/**
1921 Initializes the given database file. zFilename is the name of
1922 the db file. It is created if needed, but any directory
1923 components are not created. zSchema is the base schema to
1924 install. The following arguments may be (char const *) SQL
1925 code, each of which gets run against the db after the main
1926 schema is called. The variadic argument list MUST end with NULL
1927 (0), even if there are no non-NULL entries.
1928
1929 Returns 0 on success.
1930
1931 On error, if err is not NULL then it is populated with any error
1932 state from the underlying (temporary) db handle.
1933*/
1934FSL_EXPORT int fsl_db_init( fsl_error * err, char const * zFilename,
1935 char const * zSchema, ... );
1936
1937/**
1938 A fsl_stmt_each_f() impl, intended primarily for debugging, which
1939 simply outputs row data in tabular form via fsl_output(). The
1940 state argument must be a valid fsl_cx pointer. On
1941 the first row, the column names are output.
1942
1943 Achtung: this function's expectations were changed on 2024-09-16:
1944 prior to this, stmt's db handle had access to a fsl_cx instance,
1945 but that was factored out. It now requires the state argument to be
1946 a fsl_cx.
1947*/
1948FSL_EXPORT int fsl_stmt_each_f_dump( fsl_stmt * stmt, void * state );
1949
1950/**
1951 Returns true if the table name specified by the final argument
1952 exists in the fossil database specified by the 2nd argument on the
1953 db connection specified by the first argument, else returns false.
1954
1955 Trivia: this is one of the few libfossil APIs which makes use of
1956 FSL_DBROLE_TEMP.
1957
1958 Potential TODO: this is a bit of a wonky interface. Consider
1959 changing it to eliminate the role argument, which is only really
1960 needed if we have duplicate table names across attached dbs or if
1961 we internally mess up and write a table to the wrong db.
1962*/
1964 const char *zTable);
1965
1966/**
1967 The elipsis counterpart of fsl_stmt_bind_fmtv().
1968*/
1969FSL_EXPORT int fsl_stmt_bind_fmt( fsl_stmt * st, char const * fmt, ... );
1970
1971/**
1972 Binds a series of values using a formatting string.
1973
1974 The string may contain the following characters, each of which
1975 refers to the next argument in the args list:
1976
1977 '-': binds a NULL and expects a NULL placeholder
1978 in the argument list (for consistency's sake).
1979
1980 'i': binds an int32
1981
1982 'I': binds an int64
1983
1984 'R': binds a fsl_id_t ('R' as in 'RID' or 'ROWID')
1985
1986 'f': binds a double
1987
1988 's': binds a (char const *) as text or NULL. See below.
1989
1990 'S': binds a (char const *) as a blob or NULL. See below.
1991
1992 'b': binds a (fsl_buffer const *) as text or NULL. See below.
1993
1994 'B': binds a (fsl_buffer const *) as a blob or NULL. See below.
1995
1996 ' ': spaces are allowed for readability and are ignored.
1997
1998 '^': An optional modifier for "sSbB". See below.
1999
2000 Returns 0 on success, any number of other FSL_RC_xxx codes on
2001 error.
2002
2003 About the sSbB bindings:
2004
2005 - If their argument is NULL they bind as SQL NULL.
2006
2007 - ACHTUNG: the "sSbB" bindings assume, because of how this API is
2008 normally used, that the memory pointed to by the given argument
2009 will outlive the pending step of the given statement, so that
2010 memory is NOT copied by this call. Thus results are undefined if
2011 such an argument's memory is invalidated before the statement is
2012 done with it. The default behavior can be overridden by adding
2013 the character '^' immediately after the "sSbB" entry (with no
2014 intervening spaces), which will tell it to make a copy of the
2015 content. e.g. "ss^i" would bind one string without making a
2016 copy, then one string with a copy, then an int32.
2017
2018 Example:
2019
2020 ```
2021 int rc = fsl_stmt_bind_fmt(&stmt, "ss^i", "hello", "world", (int32_t)12);
2022 ```
2023
2024 Note the cast on the final argument to ensure that it's of the
2025 proper size for the 'i' type.
2026*/
2027FSL_EXPORT int fsl_stmt_bind_fmtv( fsl_stmt * st, char const * fmt,
2028 va_list args );
2029
2030/**
2031 Works like fsl_stmt_bind_fmt() but:
2032
2033 1) It calls fsl_stmt_reset() before binding the arguments.
2034
2035 2) If binding succeeds then it steps the given statement a single
2036 time.
2037
2038 3) If the result is _NOT_ FSL_RC_STEP_ROW then it also resets the
2039 statement before returning. It does not do so for
2040 FSL_RC_STEP_ROW because doing so would make it impossible to
2041 fetch the current row's data.
2042
2043 Returns the result of the underlying step() call. It never returns
2044 0.
2045
2046 Design note: the return value for FSL_RC_STEP_ROW, as opposed to
2047 returning 0, is necessary for proper statement use if the client
2048 wants to fetch any result data from the statement afterwards (which
2049 is only legal if FSL_RC_STEP_ROW was the result). This is also why
2050 it cannot reset the statement if that result is returned.
2051*/
2052FSL_EXPORT int fsl_stmt_bind_stepv_v2( fsl_stmt * st, char const * fmt,
2053 va_list args );
2054
2055/**
2056 The elipsis counterpart of fsl_stmt_bind_step_v2().
2057*/
2058FSL_EXPORT int fsl_stmt_bind_step_v2( fsl_stmt * st, char const * fmt, ... );
2059
2060/**
2061 Works exactly like fsl_stmt_bind_stepv_v2() except that it returns
2062 0 if stepping results in FSL_RC_STEP_DONE. That behavior is legacy
2063 and now consider to have been a poor design decision, but those
2064 semantics are currently heavily relied on throughout the library.
2065
2066 To re-iterate: this routine NEVER returns FSL_RC_STEP_DONE. We say
2067 that because some folks (🙋‍♂️) keep breaking things by checking for
2068 that code instead of 0. That's why fsl_stmt_bind_step_v2() was
2069 introduced.
2070
2071*/
2072FSL_EXPORT int fsl_stmt_bind_stepv( fsl_stmt * st, char const * fmt,
2073 va_list args );
2074
2075/**
2076 The elipsis counterpart of fsl_stmt_bind_step().
2077*/
2078FSL_EXPORT int fsl_stmt_bind_step( fsl_stmt * st, char const * fmt, ... );
2079
2080/**
2081 Sets the on-transaction hook for the given db, overwriting any
2082 prior one. To clear the hook, pass NULL for the 2nd and 3rd
2083 arguments.
2084
2085 The final argument specifies what events type to look for. It may
2086 be an OR of any FSL_DB_EVENT_... events. Use
2087 FSL_DB_EVENT_listen_all to listen to all events. The stored mask is
2088 bitwise ANDed against FSL_DB_EVENT_mask_id, so only the concrete
2089 message IDs are recorded here.
2090
2091 Achtung: fsl_cx instances install this hook on database handles
2092 they manage, so never call this on such a handle.
2093*/
2095 void * pState, fsl_flag32_t mask);
2096
2097/**
2098 Returns true if db is opened and sqlite3_db_readonly() returns 0
2099 for it, else returns false. If zSchema is NULL then "main" is
2100 assumed.
2101*/
2102FSL_EXPORT bool fsl_db_is_writeable( fsl_db * db, char const *zSchema );
2103
2104#if defined(__cplusplus)
2105} /*extern "C"*/
2106#endif
2107#endif /* ORG_FOSSIL_SCM_FSL_DB_H_INCLUDED */
uint16_t fsl_flag16_t
Definition config.h:155
int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
Definition config.h:271
uint64_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
Definition config.h:192
int64_t fsl_time_t
The type used to represent type values.
Definition config.h:296
uint32_t fsl_flag32_t
A 32-bit unsigned int type.
Definition config.h:154
int64_t fsl_int_t
fsl_int_t is a signed integer type used to denote "relative" ranges and lengths, or to tell a routine...
Definition config.h:143
#define FSL_EXPORT
Definition config.h:66
This file declares the core SCM-related public APIs.
fsl_dbrole_e
This enum defines type ID tags with which the API tags fsl_db instances so that the library can figur...
Definition core.h:156
#define E(N, V, H)
Definition core.h:497
FSL_EXPORT int fsl_db_exec_multiv(fsl_db *db, const char *sql, va_list args)
va_list counterpart of db_exec_multi().
FSL_EXPORT fsl_id_t fsl_db_last_insert_id(fsl_db *db)
Returns the row ID of the most recent insertion, or -1 if !db, db is not connected,...
FSL_EXPORT char * fsl_db_julian_to_iso8601(fsl_db *db, double j, bool msPrecision, bool localTime)
Returns the given Julian date value formatted as an ISO8601 string (with a fractional seconds part if...
FSL_EXPORT int fsl_stmt_bind_blob_name(fsl_stmt *stmt, char const *param, void const *v, fsl_int_t len, bool makeCopy)
Equivalent to fsl_stmt_bind_blob() but binds to a named parameter.
FSL_EXPORT int fsl_stmt_bind_int32(fsl_stmt *stmt, int index, int32_t v)
Binds v to the given 1-based parameter index.
FSL_EXPORT int fsl_db_get_int64v(fsl_db *db, int64_t *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_int64().
FSL_EXPORT int fsl_stmt_reset(fsl_stmt *stmt)
Equivalent to fsl_stmt_reset2(stmt, false).
FSL_EXPORT int fsl_db_txn_level(fsl_db *db)
Returns the given db's current transaction depth.
FSL_EXPORT double fsl_db_g_double(fsl_db *db, double defaultValue, char const *sql,...)
Convenience form of fsl_db_get_double() which returns the value directly but provides no way of check...
FSL_EXPORT int fsl_db_err_get(fsl_db const *db, char const **msg, fsl_size_t *len)
Behaves like fsl_error_get(), using the db's underlying error state.
FSL_EXPORT int fsl_db_get_sizev(fsl_db *db, fsl_size_t *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_size().
FSL_EXPORT int64_t fsl_db_g_int64(fsl_db *db, int64_t defaultValue, char const *sql,...)
Convenience form of fsl_db_get_int64() which returns the value directly but provides no way of checki...
FSL_EXPORT int fsl_stmt_each_f_dump(fsl_stmt *stmt, void *state)
A fsl_stmt_each_f() impl, intended primarily for debugging, which simply outputs row data in tabular ...
FSL_EXPORT int32_t fsl_stmt_g_int32(fsl_stmt *stmt, int index)
Convenience form of fsl_stmt_get_int32() which returns the value directly but cannot report errors.
FSL_EXPORT int fsl_db_prepare_cached(fsl_db *db, fsl_stmt **st, char const *sql,...)
A special-purpose variant of fsl_db_prepare() which caches statements based on their SQL code.
FSL_EXPORT int fsl_stmt_bind_fmtv(fsl_stmt *st, char const *fmt, va_list args)
Binds a series of values using a formatting string.
fsl_db_event_e
A flag type for use with fsl_db_event_f() implementations.
Definition db.h:164
FSL_EXPORT int fsl_stmt_bind_fmt(fsl_stmt *st, char const *fmt,...)
The elipsis counterpart of fsl_stmt_bind_fmtv().
FSL_EXPORT double fsl_db_string_to_julian(fsl_db *db, char const *str)
Uses the given db to convert the given time string to Julian Day format.
FSL_EXPORT int fsl_stmt_get_int64(fsl_stmt *stmt, int index, int64_t *v)
Gets an integer value from the given 0-based result set column, assigns *v to that value,...
FSL_EXPORT int fsl_db_open(fsl_db *db, char const *dbFile, fsl_flag32_t openFlags)
Opens the given db file and populates db with its handle.
FSL_EXPORT int fsl_stmt_get_int32(fsl_stmt *stmt, int index, int32_t *v)
Gets an integer value from the given 0-based result set column, assigns *v to that value,...
sqlite3_stmt fsl_stmt_t
Definition db.h:492
FSL_EXPORT int fsl_db_get_textv(fsl_db *db, char **rv, fsl_size_t *rvLen, char const *sql, va_list args)
va_list counterpart of fsl_db_get_text().
FSL_EXPORT int fsl_stmt_bind_blob(fsl_stmt *stmt, int index, void const *v, fsl_size_t len, bool makeCopy)
Binds the first n bytes of v as a blob to the given 1-based bound parameter column in the given state...
FSL_EXPORT fsl_id_t fsl_db_g_id(fsl_db *db, fsl_id_t defaultValue, char const *sql,...)
Convenience form of fsl_db_get_id() which returns the value directly but provides no way of checking ...
FSL_EXPORT char const * fsl_stmt_col_name(fsl_stmt *stmt, int index)
Returns the name of the given 0-based result column index, or NULL if !stmt, stmt is not prepared,...
FSL_EXPORT const fsl_stmt fsl_stmt_empty
Empty-initialized fsl_stmt instance, intended for copy-constructing.
Definition db.h:649
FSL_EXPORT void fsl_stmt_clear_bindings(fsl_stmt *stmt)
Clears memory associtated with any bindings on this statement.
FSL_EXPORT const char * fsl_db_role_name(enum fsl_dbrole_e r)
Returns a db name string for the given fsl_db_role value.
FSL_EXPORT int fsl_db_changes_recent(fsl_db *db)
Returns the "number of database rows that were changed or insertedor deleted by the most recently com...
FSL_EXPORT int fsl_stmt_bind_id_name(fsl_stmt *stmt, char const *param, fsl_id_t v)
Equivalent to fsl_stmt_bind_id() but binds to a named parameter.
FSL_EXPORT int fsl_stmt_bind_double(fsl_stmt *stmt, int index, double v)
Binds v to the given 1-based parameter index.
FSL_EXPORT const fsl_db fsl_db_empty
Empty-initialized fsl_db structure, intended for copy initialization.
Definition db.h:474
FSL_EXPORT fsl_stmt * fsl_stmt_malloc(void)
Allocates a new, cleanly-initialized fsl_stmt instance using fsl_malloc().
FSL_EXPORT int fsl_db_get_id(fsl_db *db, fsl_id_t *rv, char const *sql,...)
The fsl_id_t counterpart of fsl_db_get_int32().
FSL_EXPORT void * fsl_db_g_blob(fsl_db *db, fsl_size_t *len, char const *sql,...)
Convenience form of fsl_db_get_blob() which returns the value directly but provides no way of checkin...
FSL_EXPORT int fsl_db_select_slistv(fsl_db *db, fsl_list *tgt, char const *fmt, va_list args)
The va_list counterpart of fsl_db_select_slist().
FSL_EXPORT char const * fsl_stmt_g_text(fsl_stmt *stmt, int index, fsl_size_t *outLen)
Convenience form of fsl_stmt_get_text() which returns the value directly but cannot report errors.
FSL_EXPORT int fsl_db_exec_multi(fsl_db *db, const char *sql,...)
Executes multiple SQL statements, ignoring any results they might collect.
FSL_EXPORT int fsl_db_get_blob(fsl_db *db, void **rv, fsl_size_t *len, char const *sql,...)
The Blob counterpart of fsl_db_get_text().
FSL_EXPORT char * fsl_db_random_hex(fsl_db *db, fsl_size_t n)
Returns n bytes of random lower-case hexidecimal characters using the given db as its data source,...
FSL_EXPORT int fsl_db_get_int32(fsl_db *db, int32_t *rv, char const *sql,...)
Runs a fetch-style SQL query against DB and returns the first column of the first result row via *rv.
int(* fsl_stmt_each_f)(fsl_stmt *stmt, void *state)
A callback interface for use with fsl_stmt_each() and fsl_db_each().
Definition db.h:893
FSL_EXPORT int fsl_db_get_buffer(fsl_db *db, fsl_buffer *tgt, bool asBlob, char const *sql,...)
Similar to fsl_db_get_text() and fsl_db_get_blob(), but writes its result to tgt, appending its resul...
FSL_EXPORT int fsl_db_exec(fsl_db *db, char const *sql,...)
Executes a single SQL statement, skipping over any results it may have.
FSL_EXPORT bool fsl_db_existsv(fsl_db *db, char const *sql, va_list args)
va_list counterpart of fsl_db_exists().
FSL_EXPORT int fsl_stmt_bind_step_v2(fsl_stmt *st, char const *fmt,...)
The elipsis counterpart of fsl_stmt_bind_step_v2().
FSL_EXPORT int fsl_stmt_bind_text_name(fsl_stmt *stmt, char const *param, char const *v, fsl_int_t n, bool makeCopy)
Equivalent to fsl_stmt_bind_text() but binds to a named parameter.
FSL_EXPORT char const * fsl_stmt_sql(fsl_stmt *stmt, fsl_size_t *len)
Returns the SQL string used to prepare the given statement, or NULL if stmt has not been prepared.
FSL_EXPORT int fsl_db_changes_total(fsl_db *db)
Returns "the number of row changes caused by INSERT, UPDATE orDELETE statements since the database co...
FSL_EXPORT int fsl_db_get_blobv(fsl_db *db, void **rv, fsl_size_t *stmtLen, char const *sql, va_list args)
va_list counterpart of fsl_db_get_blob().
FSL_EXPORT int fsl_stmt_bind_id(fsl_stmt *stmt, int index, fsl_id_t v)
Binds v to the given 1-based parameter index.
FSL_EXPORT char const * fsl_db_name(fsl_db const *db)
If a db name has been associated with db then it is returned, otherwise NULL is returned.
FSL_EXPORT int fsl_stmt_bind_null_name(fsl_stmt *stmt, char const *param)
Equivalent to fsl_stmt_bind_null_name() but binds to a named parameter.
FSL_EXPORT void fsl_db_event_listener(fsl_db *db, fsl_db_event_f f, void *pState, fsl_flag32_t mask)
Sets the on-transaction hook for the given db, overwriting any prior one.
FSL_EXPORT int fsl_db_txn_end_v2(fsl_db *db, bool keepSavepoint, bool bubbleRollback)
Decrements the transaction counter incremented by fsl_db_txn_begin() and commits or rolls back the sa...
FSL_EXPORT int fsl_stmt_bind_int32_name(fsl_stmt *stmt, char const *param, int32_t v)
Equivalent to fsl_stmt_bind_int32() but binds to a named parameter.
FSL_EXPORT char const * fsl_db_filename(fsl_db const *db, fsl_size_t *len)
If db is not NULL then this function returns its name (the one used to fsl_db_open() it).
FSL_EXPORT int fsl_stmt_get_blob(fsl_stmt *stmt, int index, void const **out, fsl_size_t *outLen)
The Blob counterpart of fsl_stmt_get_text().
FSL_EXPORT int fsl_db_get_int32v(fsl_db *db, int32_t *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_int32().
FSL_EXPORT fsl_size_t fsl_db_g_size(fsl_db *db, fsl_size_t defaultValue, char const *sql,...)
Convenience form of fsl_db_get_size() which returns the value directly but provides no way of checkin...
FSL_EXPORT int fsl_db_preparev(fsl_db *db, fsl_stmt *tgt, char const *sql, va_list args)
va_list counterpart of fsl_db_prepare().
FSL_EXPORT int fsl_stmt_bind_step(fsl_stmt *st, char const *fmt,...)
The elipsis counterpart of fsl_stmt_bind_step().
FSL_EXPORT int fsl_stmt_param_count(fsl_stmt const *stmt)
Returns the bound parameter count for the given statement, or -1 if !stmt or it has not been prepared...
FSL_EXPORT int fsl_db_attach(fsl_db *db, const char *zDbName, const char *zLabel)
ATTACHes the file zDbName to db using the database name zLabel (which gets quoted as an SQL identifie...
FSL_EXPORT int fsl_stmt_param_index(fsl_stmt *stmt, char const *param)
Returns the index of the given named parameter for the given statement, or -1 if !...
FSL_EXPORT int fsl_db_txn_begin(fsl_db *db)
Begins a transaction on the given db.
FSL_EXPORT int fsl_stmt_reset2(fsl_stmt *stmt, bool resetRowCounter)
Resets the given statement, analog to sqlite3_reset().
FSL_EXPORT bool fsl_db_table_has_column(fsl_db *db, char const *zTableName, char const *zColName)
Returns non-0 (true) if the database (which must be open) table identified by zTableName has a column...
FSL_EXPORT double fsl_stmt_g_double(fsl_stmt *stmt, int index)
Convenience form of fsl_stmt_get_double() which returns the value directly but cannot report errors.
FSL_EXPORT int fsl_db_each(fsl_db *db, fsl_stmt_each_f callback, void *callbackState, char const *sql,...)
Expects sql to be a SELECT-style query which (potentially) returns a result set.
FSL_EXPORT bool fsl_db_is_writeable(fsl_db *db, char const *zSchema)
Returns true if db is opened and sqlite3_db_readonly() returns 0 for it, else returns false.
FSL_EXPORT int fsl_stmt_get_double(fsl_stmt *stmt, int index, double *v)
Gets double value from the given 0-based result set column, assigns *v to that value,...
FSL_EXPORT int fsl_stmt_each(fsl_stmt *stmt, fsl_stmt_each_f callback, void *callbackState)
Calls the given callback one time for each result row in the given statement, iterating over stmt usi...
FSL_EXPORT int fsl_db_get_double(fsl_db *db, double *rv, char const *sql,...)
The double counterpart of fsl_db_get_int32().
FSL_EXPORT int fsl_db_txn_commit(fsl_db *db)
Equivalent to fsl_db_txn_end_v2(db, true, false).
FSL_EXPORT int fsl_db_detach(fsl_db *db, const char *zLabel)
The converse of fsl_db_detach().
FSL_EXPORT int fsl_db_get_idv(fsl_db *db, fsl_id_t *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_id().
FSL_EXPORT int fsl_db_get_text(fsl_db *db, char **rv, fsl_size_t *rvLen, char const *sql,...)
The C-string counterpart of fsl_db_get_int32().
FSL_EXPORT int fsl_stmt_bind_text(fsl_stmt *stmt, int index, char const *v, fsl_int_t n, bool makeCopy)
Binds the first n bytes of v as text to the given 1-based bound parameter column in the given stateme...
FSL_EXPORT char * fsl_db_unix_to_iso8601(fsl_db *db, fsl_time_t j, bool localTime)
Returns the given Julian date value formatted as an ISO8601 string (with a fractional seconds part if...
int(* fsl_db_event_f)(fsl_db_event const *e)
An event callback for fsl_db objects, primarily for communicating on-transaction-start/end.
Definition db.h:292
FSL_EXPORT int fsl_stmt_get_text(fsl_stmt *stmt, int index, char const **out, fsl_size_t *outLen)
Gets a string value from the given 0-based result set column, assigns *out (if out is not NULL) to th...
FSL_EXPORT int fsl_db_init(fsl_error *err, char const *zFilename, char const *zSchema,...)
Initializes the given database file.
FSL_EXPORT int fsl_stmt_step(fsl_stmt *stmt)
"Steps" the given SQL cursor one time.
FSL_EXPORT int fsl_db_txn_rollback(fsl_db *db)
Equivalent to fsl_db_txn_end_v2(db, false, true), noting that the final value of true there is for hi...
FSL_EXPORT int fsl_db_execv(fsl_db *db, char const *sql, va_list args)
va_list counterpart of fs_db_exec().
FSL_EXPORT int fsl_db_eachv(fsl_db *db, fsl_stmt_each_f callback, void *callbackState, char const *sql, va_list args)
va_list counterpart to fsl_db_each().
FSL_EXPORT fsl_id_t fsl_stmt_g_id(fsl_stmt *stmt, int index)
Convenience form of fsl_stmt_get_id() which returns the value directly but cannot report errors.
FSL_EXPORT void fsl_db_close(fsl_db *db)
Closes the given db handle and frees any resources owned by db.
FSL_EXPORT void fsl_db_sqltrace_enable(fsl_db *db, FILE *outStream, bool expandSql)
If db is an opened db handle, this registers a debugging function with the db which traces all SQL to...
FSL_EXPORT int fsl_stmt_bind_int64(fsl_stmt *stmt, int index, int64_t v)
Binds v to the given 1-based parameter index.
FSL_EXPORT int fsl_stmt_bind_stepv(fsl_stmt *st, char const *fmt, va_list args)
Works exactly like fsl_stmt_bind_stepv_v2() except that it returns 0 if stepping results in FSL_RC_ST...
FSL_EXPORT bool fsl_db_table_exists(fsl_db *db, fsl_dbrole_e whichDb, const char *zTable)
Returns true if the table name specified by the final argument exists in the fossil database specifie...
FSL_EXPORT int fsl_stmt_cached_yield(fsl_stmt *st)
"Yields" a statement which was prepared with fsl_db_prepare_cached(), such that that routine can once...
FSL_EXPORT double fsl_db_julian_now(fsl_db *db)
Returns the current time in Julian Date format.
FSL_EXPORT bool fsl_db_exists(fsl_db *db, char const *sql,...)
Runs the given SQL query on the given db and returns true if the query returns any rows,...
FSL_EXPORT int fsl_stmt_bind_stepv_v2(fsl_stmt *st, char const *fmt, va_list args)
Works like fsl_stmt_bind_fmt() but:
FSL_EXPORT char * fsl_db_g_text(fsl_db *db, fsl_size_t *len, char const *sql,...)
Convenience form of fsl_db_get_text() which returns the value directly but provides no way of checkin...
FSL_EXPORT void fsl_db_err_reset(fsl_db *db)
Resets any error state in db, but might keep the string memory allocated for later use.
FSL_EXPORT int fsl_stmt_get_id(fsl_stmt *stmt, int index, fsl_id_t *v)
The fsl_id_t counterpart of fsl_stmt_get_int32().
FSL_EXPORT int fsl_db_get_int64(fsl_db *db, int64_t *rv, char const *sql,...)
The int64 counterpart of fsl_db_get_int32().
FSL_EXPORT int fsl_stmt_bind_int64_name(fsl_stmt *stmt, char const *param, int64_t v)
Equivalent to fsl_stmt_bind_int64() but binds to a named parameter.
FSL_EXPORT fsl_db * fsl_db_malloc(void)
Allocates a new fsl_db instance().
FSL_EXPORT int32_t fsl_db_g_int32(fsl_db *db, int32_t defaultValue, char const *sql,...)
Convenience form of fsl_db_get_int32() which returns the value directly but provides no way of checki...
FSL_EXPORT int fsl_db_prepare(fsl_db *db, fsl_stmt *tgt, char const *sql,...)
Prepares an SQL statement for execution.
FSL_EXPORT int fsl_stmt_bind_double_name(fsl_stmt *stmt, char const *param, double v)
Equivalent to fsl_stmt_bind_double() but binds to a named parameter.
#define fsl_db_event_map(E)
A map of fsl_db_event types.
Definition db.h:148
FSL_EXPORT int fsl_stmt_finalize(fsl_stmt *stmt)
Frees memory associated with stmt but does not free stmt unless it was allocated by fsl_stmt_malloc()...
sqlite3 fsl_db_t
A level of indirection to "hide" the actual db driver implementation from the public API.
Definition db.h:118
fsl_db_open_flags_e
Flags for use with fsl_db_open() and friends.
Definition db.h:46
@ FSL_DB_OPEN_RW
Flag for fsl_db_open() specifying that the db should be opened in read-write mode,...
Definition db.h:63
@ FSL_DB_OPEN_NONE
The "no flags" value.
Definition db.h:50
@ FSL_DB_OPEN_RO
Flag for fsl_db_open() specifying that the db should be opened in read-only mode.
Definition db.h:56
@ FSL_DB_OPEN_TRACE_SQL
Used by fsl_db_open() to to tell the underlying db connection to trace all SQL to stdout.
Definition db.h:101
@ FSL_DB_OPEN_SCHEMA_VALIDATE
Currently unused.
Definition db.h:94
@ FSL_DB_OPEN_CREATE
Flag for fsl_db_open() specifying that the db should be opened in read-write mode,...
Definition db.h:82
@ FSL_DB_OPEN_RWC
Shorthand for RW+CREATE flags.
Definition db.h:87
FSL_EXPORT int fsl_db_get_size(fsl_db *db, fsl_size_t *rv, char const *sql,...)
The fsl_size_t counterpart of fsl_db_get_int32().
FSL_EXPORT int fsl_db_get_doublev(fsl_db *db, double *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_double().
FSL_EXPORT int fsl_db_get_bufferv(fsl_db *db, fsl_buffer *tgt, bool asBlob, char const *sql, va_list args)
va_list counterpart of fsl_db_get_buffer().
FSL_EXPORT int fsl_stmt_bind_null(fsl_stmt *stmt, int index)
Binds NULL to the given 1-based parameter index.
fsl_db_event_mask2_e
Convenience FSL_DB_EVENT_... entries which cannot be defined until after fsl_db_event_e is.
Definition db.h:175
@ FSL_DB_EVENT_group_txn
Mask of the IDs of transaction-specific events.
Definition db.h:177
@ FSL_DB_EVENT_group_sql_trace
Mask of the IDs of SQL tracing events.
Definition db.h:181
FSL_EXPORT int fsl_db_select_slist(fsl_db *db, fsl_list *tgt, char const *fmt,...)
Expects fmt to be a SELECT-style query.
FSL_EXPORT int64_t fsl_stmt_g_int64(fsl_stmt *stmt, int index)
Convenience form of fsl_stmt_get_int64() which returns the value directly but cannot report errors.
FSL_EXPORT fsl_db * fsl_stmt_db(fsl_stmt *stmt)
Returns the db handle which prepared the given statement, or NULL if stmt has not been prepared.
fsl_db_event_mask_e
Bitmasks for use with fsl_db_event_e.
Definition db.h:123
@ FSL_DB_EVENT_mask_payload
Describes a data type for fsl_db_event::payload.
Definition db.h:129
@ FSL_DB_EVENT_payload_buffer
(fsl_buffer const *) payload.
Definition db.h:132
@ FSL_DB_EVENT_mask_id
All concrete message IDs are masked with this.
Definition db.h:137
@ FSL_DB_EVENT_listen_all
Convenience entry for use with fsl_db_event_listener().
Definition db.h:142
@ FSL_DB_EVENT_mask_reserved
Definition db.h:124
FSL_EXPORT int fsl_db_preparev_cached(fsl_db *db, fsl_stmt **st, char const *sql, va_list args)
The va_list counterpart of fsl_db_prepare_cached().
FSL_EXPORT int fsl_stmt_col_count(fsl_stmt const *stmt)
Returns the result column count for the given statement, or -1 if !stmt or it has not been prepared.
A general-purpose buffer class, analog to Fossil's Blob class, but it is not called fsl_blob to avoid...
Definition util.h:684
An "event" message type for use with fsl_db.
Definition db.h:189
void * state
The event listener state.
Definition db.h:197
fsl_db * db
The event-firing db.
Definition db.h:193
fsl_db_event_e type
Event type.
Definition db.h:206
void const * payload
A message-type-specific payload.
Definition db.h:202
int savepointLevel
The db's current savepoint level (because most events deal with transactions and this info has proven...
Definition db.h:213
Db handle wrapper class.
Definition db.h:313
struct fsl_db::@316105345303111027035325362263037170313261254037::@331140356012215264240306074346040363221336276352 txn
Transaction-related state.
sqlite3_stmt * sRelease
Prepared statements for SAVEPOINT RELEASE.
Definition db.h:403
fsl_db_t * dbh
Underlying db driver handle.
Definition db.h:318
int level
Counter for fsl_db_txn_begin/end().
Definition db.h:399
char * filename
Holds the file name used when opening this db.
Definition db.h:349
sqlite3_stmt * sRollback
Prepared statements for ROLLBACK TO SAVEPOINT.
Definition db.h:405
int openStatementCount
Debugging/test counter.
Definition db.h:375
fsl_buffer buffer
Internal buffer to reduce reallocations caused via fsl_db_prepare_cached(), fsl_db_see_check(),...
Definition db.h:426
fsl_stmt * head
An internal cache of "static" queries - those which do not rely on call-time state unless that state ...
Definition db.h:419
char * name
Holds the database name for use in creating queries.
Definition db.h:358
fsl_error error
Holds error state from the underlying driver.
Definition db.h:327
struct fsl_db::@316105345303111027035325362263037170313261254037::@265153334322072202076113040112070317014315122116 event
fsl_flag32_t flags
Internal flags.
Definition db.h:380
fsl_db_event_f f
Event listener callback.
Definition db.h:384
void const * allocStamp
A marker which tells fsl_db_close() whether or not fsl_db_malloc() allocated this instance (in which ...
Definition db.h:434
fsl_flag16_t role
Describes what role(s) this db connection plays in fossil (if any).
Definition db.h:365
fsl_flag32_t maskIds
The FSL_DB_EVENT_mask_id-masked part of event IDs to fire the callback for.
Definition db.h:391
FILE * fpTrace
Older-style (pre-fsl_db_event) trace output channel.
Definition db.h:393
struct fsl_db::@316105345303111027035325362263037170313261254037::@025146014153060240206145300313221172252240144027 stCache
State for use with fsl_db_prepare_cached().
void * state
Impl-specific state for f.
Definition db.h:386
sqlite3_stmt * sSavepoint
Prepared statements for SAVEPOINT management.
Definition db.h:401
struct fsl_db::@316105345303111027035325362263037170313261254037 impl
Private implementation details.
A container for storing generic error state.
Definition util.h:781
Generic list container type.
Definition util.h:156
Represents a prepared statement handle.
Definition db.h:555
fsl_db * db
The db which prepared this statement.
Definition db.h:559
fsl_flag16_t role
Describes the database(s) used by this statement handle, in the form of a bitmask of fsl_dbrole_e val...
Definition db.h:577
fsl_stmt * next
For internal use in creating linked lists.
Definition db.h:615
fsl_size_t rowCount
The number of times this statement has fetched a row via fsl_stmt_step().
Definition db.h:593
fsl_stmt_t * stmt
Underlying db driver-level statement handle.
Definition db.h:566
fsl_buffer sql
The SQL used to prepare this statement.
Definition db.h:585
fsl_flag16_t flags
Internal state flags.
Definition db.h:603
uint32_t cachedHits
Internal use only: counts the number of times this query has been resolved as cached via fsl_db_prepa...
Definition db.h:609
void const * allocStamp
A marker which tells fsl_stmt_finalize() whether or not fsl_stmt_malloc() allocated this instance (in...
Definition db.h:623
struct fsl_stmt::@241310320130362112273312176156263277022126132200 impl
Private implementation details.