package sqlite3_bindings
import "core:c"
/* Opaque handle to an open SQLite database connection, created via open() / open_v2() and closed via close() / close_v2(). */
Connection :: distinct rawptr
/* An SQL statement compiled into binary form and ready to be evaluated. Created by prepare_v2() / prepare_v3() and destroyed by finalize(). */
Statement :: distinct rawptr
/*
A dynamically typed value that can hold an integer, float, text, BLOB, or NULL.
Protected Value objects (passed to application-defined SQL functions) are safe for
general use; unprotected values from column_value may only be passed to bind_value,
result_value, or value_dup.
*/
Value :: distinct rawptr
/* Records state information about an ongoing online backup operation. Created by backup_init() and destroyed by backup_finish(). */
Backup :: distinct rawptr
/*
A handle to an open BLOB on which incremental I/O can be performed.
Created by blob_open() and destroyed by blob_close(). Supports partial reads and
writes via blob_read() / blob_write() without loading the entire value into memory.
*/
Blob :: distinct rawptr
/*
The execution context passed as the first argument to application-defined SQL
functions. Used with result_*, aggregate_context, user_data, context_db_handle,
and get/set_auxdata.
*/
Context :: distinct rawptr
/* Special destructor values for bind/result functions: STATIC means SQLite borrows the caller's memory; TRANSIENT means SQLite makes its own copy immediately. */
STATIC :: rawptr(uintptr(0))
TRANSIENT :: rawptr(~uintptr(0))
/*
Primary and extended SQLite result codes returned by most API functions.
Primary codes occupy the low 8 bits; extended codes add detail in higher bits
and can be enabled per-connection with extended_result_codes().
*/
Result :: enum c.int {
Ok = 0, // Successful result.
Error = 1, // Generic error.
Internal = 2, // Internal logic error in SQLite.
Perm = 3, // Access permission denied.
Abort = 4, // Callback routine requested an abort.
Auth = 23, // Authorization denied.
Busy = 5, // Database file is locked by another connection.
Cantopen = 14, // Unable to open the database file.
Constraint = 19, // Abort due to constraint violation.
Corrupt = 11, // Database disk image is malformed.
Done = 101, // step() has finished executing; no more rows.
Empty = 16, // Internal use only; not returned to callers.
Format = 24, // Not currently used.
Full = 13, // Insertion failed because the database or disk is full.
Interrupt = 9, // Operation interrupted via interrupt().
Ioerr = 10, // OS-level I/O error occurred.
Locked = 6, // Write operation failed due to a conflict within the same connection.
Mismatch = 20, // Datatype mismatch (e.g. assigning a non-integer rowid).
Misuse = 21, // API called in an undefined or unsupported way.
Nolfs = 22, // OS does not support large files.
Nomem = 7, // A malloc() call failed.
Notadb = 26, // File opened that is not an SQLite database.
Notfound = 12, // File control opcode was not recognized.
Notice = 27, // Unusual operation logged via sqlite3_log() (not returned to callers).
Protocol = 15, // File locking protocol error (typically WAL mode).
Range = 25, // Parameter index or column index out of range.
Readonly = 8, // Attempt to write to a read-only database.
Row = 100, // step() has another row of data ready.
Schema = 17, // Database schema changed; the prepared statement was invalidated.
Toobig = 18, // String or BLOB exceeds the size limit.
Warning = 28, // Unusual but non-fatal condition reported via sqlite3_log().
// Extended result codes — more specific variants of the primary codes above.
// Enable with extended_result_codes(); the low 8 bits always match the primary code.
AbortRollback = 516,
AuthUser = 279,
BusyRecovery = 261,
BusySnapshot = 517,
BusyTimeout = 773,
CantopenConvpath = 1038,
CantopenDirtywal = 1294,
CantopenFullpath = 782,
CantopenIsdir = 526,
CantopenNotempdir = 270,
CantopenSymlink = 1550,
ConstraintCheck = 275,
ConstraintCommithook = 531,
ConstraintDatatype = 3091,
ConstraintForeignkey = 787,
ConstraintFunction = 1043,
ConstraintNotnull = 1299,
ConstraintPinned = 2835,
ConstraintPrimarykey = 1555,
ConstraintRowid = 2579,
ConstraintTrigger = 1811,
ConstraintUnique = 2067,
ConstraintVtab = 2323,
CorruptIndex = 779,
CorruptSequence = 523,
CorruptVtab = 267,
ErrorMissing_Collseq = 257,
ErrorRetry = 513,
ErrorSnapshot = 769,
IoerrAccess = 3338,
IoerrAuth = 7178,
IoerrBegin_atomic = 7434,
IoerrBlocked = 2826,
IoerrCheckreservedlock = 3594,
IoerrClose = 4106,
IoerrCommit_atomic = 7690,
IoerrConvpath = 6666,
IoerrCorruptfs = 8458,
IoerrData = 8202,
IoerrDelete = 2570,
IoerrDelete_noent = 5898,
IoerrDir_close = 4362,
IoerrDir_fsync = 1290,
IoerrFstat = 1802,
IoerrFsync = 1034,
IoerrGettemppath = 6410,
IoerrLock = 3850,
IoerrMmap = 6154,
IoerrNomem = 3082,
IoerrRdlock = 2314,
IoerrRead = 266,
IoerrRollback_atomic = 7946,
IoerrSeek = 5642,
IoerrShmlock = 5130,
IoerrShmmap = 5386,
IoerrShmopen = 4618,
IoerrShmsize = 4874,
IoerrShort_read = 522,
IoerrTruncate = 1546,
IoerrUnlock = 2058,
IoerrVnode = 6922,
IoerrWrite = 778,
LockedSharedcache = 262,
LockedVtab = 518,
NoticeRecover_Rollback = 539,
NoticeRecover_Wal = 283,
OkLoad_permanently = 256,
ReadonlyCantinit = 1288,
ReadonlyCantlock = 520,
ReadonlyDbmoved = 1032,
ReadonlyDirectory = 1544,
ReadonlyRecovery = 264,
ReadonlyRollback = 776,
WarningAutoindex = 284,
}
/* Column data types returned by column_type() and value_type(). */
Datatype :: enum c.int {
Integer = 1,
Float = 2,
Text = 3,
Blob = 4,
Null = 5,
}
/* Flags controlling how a database file is opened; combine with open_v2(). */
OpenFlags :: distinct bit_set[OpenFlag;c.int]
/*
Controls how a database connection is opened via open_v2().
At least one of Readonly, Readwrite, or Readwrite+Create must be present.
*/
OpenFlag :: enum c.int {
Readonly = 0, // Open in read-only mode; fails if the database does not exist.
Readwrite = 1, // Open for read and write; the database must already exist.
Create = 2, // Create the database if it does not exist; use together with Readwrite.
Uri = 6, // Interpret the filename as a URI.
Memory = 7, // Open an in-memory database; the filename is used only for cache sharing.
Nomutex = 15, // Enable multi-thread mode; different threads may use different connections simultaneously.
Fullmutex = 16, // Enable serialized mode; multiple threads may safely share one connection.
Sharedcache = 17, // Enable shared page cache, overriding the default setting.
Privatecache = 18, // Disable shared page cache, overriding the default setting.
Nofollow = 24, // Disallow symbolic links in the database filename.
Exrescode = 25, // Enable extended result codes for this connection.
}
/* Flags passed to prepare_v3() to control statement compilation behaviour. */
PrepareFlags :: distinct bit_set[PrepareFlag;c.uint]
/*
Provides additional options to prepare_v3() for statement compilation.
Persistent hints that the statement will be retained long-term (affects cache behavior).
No_Vtab disallows virtual table access in the statement.
*/
PrepareFlag :: enum c.uint {
Persistent = 0, // The statement will be retained and reused many times; enables query-plan caching.
Normalize = 1, // Normalize the SQL text (whitespace/formatting) before compilation.
No_Vtab = 2, // Disallow use of virtual tables in the query; useful for executing untrusted SQL.
}
/*
Per-connection run-time limits settable via limit().
Limits cap sizes of SQL constructs to prevent denial-of-service from untrusted input.
*/
LimitId :: enum c.int {
Length = 0, // Maximum length of a string or BLOB.
Sql_Length = 1, // Maximum length of an SQL statement.
Column = 2, // Maximum number of columns in a table or result set.
Expr_Depth = 3, // Maximum depth of an expression parse tree.
Compound_Select = 4, // Maximum number of terms in a compound SELECT statement.
Vdbe_Op = 5, // Maximum number of instructions in a VDBE program.
Function_Arg = 6, // Maximum number of arguments to a SQL function.
Attached = 7, // Maximum number of attached databases.
Like_Pattern_Len = 8, // Maximum length of a LIKE or GLOB pattern.
Variable_Number = 9, // Maximum number of host parameters in a single SQL statement.
Trigger_Depth = 10, // Maximum depth of trigger recursion.
Worker_Threads = 11, // Maximum number of worker threads for a prepared statement.
}
/*
Text encodings and function-registration flags used with create_function_v2().
Utf8/Utf16le/Utf16be/Utf16 select the preferred encoding of text arguments.
Deterministic, Directonly, and Innocuous are security/optimisation modifiers.
*/
TextEncoding :: enum c.int {
Utf8 = 1,
Utf16le = 2,
Utf16be = 3,
Utf16 = 4, // Native byte order UTF-16.
Deterministic = 0x000000800, // Function always returns the same result for the same inputs; enables optimiser shortcuts.
Directonly = 0x000080000, // Prevent invocation from views, triggers, or CHECK constraints (recommended for security).
Innocuous = 0x000200000, // Safe to invoke from schema contexts such as index expressions (opposite of Directonly).
}
/* Event mask for trace_v2() — selects which execution events trigger the callback. */
TraceFlags :: distinct bit_set[TraceFlag;c.uint]
/*
Selects which categories of events are reported to the trace_v2() callback.
Stmt fires when a statement first executes; Profile fires after it finishes with timing;
Row fires before each result row; Close fires when a database connection closes.
*/
TraceFlag :: enum c.uint {
Stmt = 0, // Invoked when a prepared statement begins running; X is the unexpanded SQL text.
Profile = 1, // Invoked when a statement finishes; X points to the estimated run time in nanoseconds.
Row = 2, // Invoked each time a prepared statement produces a row.
Close = 3, // Invoked when a database connection closes.
}
/*
Action codes passed to the authorizer callback indicating what SQL operation is being
compiled. Passed as the second argument to the AuthorizerCallback registered with
set_authorizer().
*/
AuthAction :: enum c.int {
Create_Index = 1,
Create_Table = 2,
Create_Temp_Index = 3,
Create_Temp_Table = 4,
Create_Temp_Trigger = 5,
Create_Temp_View = 6,
Create_Trigger = 7,
Create_View = 8,
Delete = 9,
Drop_Index = 10,
Drop_Table = 11,
Drop_Temp_Index = 12,
Drop_Temp_Table = 13,
Drop_Temp_Trigger = 14,
Drop_Temp_View = 15,
Drop_Trigger = 16,
Drop_View = 17,
Insert = 18,
Pragma = 19,
Read = 20,
Select = 21,
Transaction = 22,
Update = 23,
Attach = 24,
Detach = 25,
Alter_Table = 26,
Reindex = 27,
Analyze = 28,
Create_Vtable = 29,
Drop_Vtable = 30,
Function = 31,
Savepoint = 32,
Recursive = 33,
}
/* Return value from an authorizer callback controlling whether the action is permitted. */
AuthReturn :: enum c.int {
Ok = 0, // Allow the action.
Deny = 1, // Reject the entire SQL statement with an error.
Ignore = 2, // Disallow the specific action; substitute NULL for column reads.
}
/*
WAL checkpoint modes passed to wal_checkpoint_v2().
Passive is non-blocking; Truncate is the most thorough mode and also zeroes the WAL
file on success.
*/
CheckpointMode :: enum c.int {
Passive = 0, // Non-blocking; checkpoints as many frames as possible without waiting for readers or writers.
Full = 1, // Block until no writers remain, then checkpoint all WAL frames; blocks new writers during the operation.
Restart = 2, // Like Full, but additionally blocks until all readers read directly from the database file.
Truncate = 3, // Like Restart, and also truncates the WAL file to zero bytes on success.
}
/*
Status codes for the global status() / status64() functions.
Current and highwater values are returned; the highwater mark can optionally be reset.
*/
StatusOp :: enum c.int {
Memory_Used = 0, // Bytes of memory currently allocated by SQLite.
Pagecache_Used = 1, // Number of pages currently checked out from the page cache.
Pagecache_Overflow = 2, // Bytes of page cache memory that spilled to the heap because the cache was full.
Malloc_Size = 5, // Size of the largest individual allocation made from malloc.
Parser_Stack = 6, // Deepest parser stack depth encountered.
Pagecache_Size = 7, // Largest single allocation from the page cache.
Malloc_Count = 9, // Total number of individual memory allocations.
}
/*
Status codes for the per-connection db_status() function.
Covers lookaside allocations, cache usage, schema memory, and deferred foreign keys.
*/
DbStatusOp :: enum c.int {
Lookaside_Used = 0, // Bytes of lookaside memory currently in use.
Cache_Used = 1, // Bytes of page cache memory currently in use.
Schema_Used = 2, // Bytes of memory used to store the database schema.
Stmt_Used = 3, // Bytes of memory used by prepared statements.
Lookaside_Hit = 4, // Number of successful lookaside allocations.
Lookaside_Miss_Size = 5, // Number of lookaside allocation attempts that failed because the request was too large.
Lookaside_Miss_Full = 6, // Number of lookaside allocation attempts that failed because the pool was exhausted.
Cache_Hit = 7, // Number of page cache hits.
Cache_Miss = 8, // Number of page cache misses.
Cache_Write = 9, // Number of dirty pages written to disk.
Deferred_Fks = 10, // Number of outstanding deferred foreign key constraint violations.
Cache_Used_Shared = 11, // Bytes of shared page cache memory in use (shared cache mode only).
Cache_Spill = 12, // Number of pages that spilled from the page cache to disk.
}
/*
Status counters for the per-statement stmt_status() function.
Tracks operations such as full-table scans, sorts, auto-index creation, VM instruction
steps, and re-preparations.
*/
StmtStatusOp :: enum c.int {
Fullscan_Step = 1, // Number of full table scan steps performed.
Sort = 2, // Number of sort operations executed.
Autoindex = 3, // Number of automatic indexes created during the query.
Vm_Step = 4, // Number of virtual machine instructions executed.
Reprepare = 5, // Number of times the statement was automatically reprepared due to a schema change.
Run = 6, // Number of times the statement has been run.
Filter_Miss = 7, // Number of times a Bloom filter test rejected a row as a potential match.
Filter_Hit = 8, // Number of times a Bloom filter test accepted a row as a potential match.
Memused = 99, // Estimated memory used by the prepared statement in bytes.
}
/*
Callback invoked by SQLite to release memory for text/blob bind and result values.
Pass STATIC (borrow caller memory) or TRANSIENT (copy immediately) as special sentinels
instead of a real function pointer when the memory lifetime is known statically.
*/
Destructor :: #type proc "c" (ptr: rawptr)
/*
Row callback for exec(). Called once per result row with the column count, column
values as cstrings (nil for SQL NULL), and column names. Return non-zero to abort
execution; exec() will then return Abort.
*/
ExecProc :: #type proc "c" (user_arg: rawptr, n_cols: c.int, cols: [^]cstring, col_names: [^]cstring) -> c.int
/*
Invoked by busy_handler() when a database table is locked by another connection.
count is the number of prior invocations for the same lock event. Return non-zero
to retry the operation; return zero to make the call return Busy.
*/
BusyHandler :: #type proc "c" (user_arg: rawptr, count: c.int) -> c.int
/*
Invoked periodically during long-running step() and prepare() calls, approximately
every N virtual machine instructions. Return non-zero to interrupt the operation and
cause it to return Interrupt.
*/
ProgressHandler :: #type proc "c" (user_arg: rawptr) -> c.int
/*
Invoked by trace_v2() for each enabled trace event. mask indicates the single event
type (Stmt/Profile/Row/Close); p and x carry event-specific data (e.g. Statement
pointer and SQL text for Stmt events, nanosecond runtime for Profile events).
*/
TraceCallback :: #type proc "c" (mask: TraceFlags, user_arg: rawptr, p: rawptr, x: rawptr) -> c.int
/*
Registered with set_authorizer() and called during SQL compilation for each action
the statement wishes to perform. Return Ok to allow, Deny to reject the statement
with an error, or Ignore to silently disallow the specific action (substituting NULL
for column reads).
*/
AuthorizerCallback :: #type proc "c" (
user_arg: rawptr,
action: AuthAction,
s1: cstring,
s2: cstring,
s3: cstring,
s4: cstring,
) -> AuthReturn
/*
Registered with commit_hook() and called just before each transaction commits.
Returning non-zero converts the commit into a rollback.
*/
CommitHook :: #type proc "c" (user_arg: rawptr) -> c.int
/* Registered with rollback_hook() and called whenever a transaction is rolled back, either explicitly or due to an error. */
RollbackHook :: #type proc "c" (user_arg: rawptr)
/*
Registered with update_hook() and called after each INSERT, UPDATE, or DELETE.
op is SQLITE_INSERT (18), SQLITE_UPDATE (23), or SQLITE_DELETE (9); rowid is the
affected row's rowid.
*/
UpdateHook :: #type proc "c" (user_arg: rawptr, op: c.int, db_name: cstring, table_name: cstring, rowid: c.int64_t)
/*
Registered with wal_hook() and invoked after each WAL-mode commit once the write
lock has been released. n_pages is the current WAL page count. Return Ok or an error
code to propagate back to the triggering statement.
*/
WalHook :: #type proc "c" (user_arg: rawptr, db: Connection, db_name: cstring, n_pages: c.int) -> c.int
/*
Registered with collation_needed() and called whenever an unknown collation sequence
is required during query compilation. The callback should register the named collation
via create_collation_v2() before returning.
*/
CollationNeeded :: #type proc "c" (user_arg: rawptr, db: Connection, text_rep: TextEncoding, name: cstring)
/*
Comparison callback for a custom collation registered with create_collation_v2().
Must return negative, zero, or positive if string a is less than, equal to, or
greater than string b respectively. Must be consistent and transitive.
*/
CompareFunc :: #type proc "c" (user_arg: rawptr, len_a: c.int, a: rawptr, len_b: c.int, b: rawptr) -> c.int
/* Implementation of a scalar SQL function registered with create_function_v2(). Use result_* functions on ctx to return a value. */
ScalarFunc :: #type proc "c" (ctx: Context, n_args: c.int, args: [^]Value)
/*
Per-row accumulation callback for an aggregate or window function. Called once for
each input row in the group; use aggregate_context() to access shared accumulator
state across rows.
*/
StepFunc :: #type proc "c" (ctx: Context, n_args: c.int, args: [^]Value)
/* Finalization callback for an aggregate function. Called once per group after all StepFunc calls; use result_* to set the aggregate result. */
FinalFunc :: #type proc "c" (ctx: Context)
/* Window function current-value callback. Called to return the current aggregate value without resetting the accumulator. */
ValueFunc :: #type proc "c" (ctx: Context)
/* Window function inverse-step callback. Called to remove a row from the current window when the window frame slides forward. */
InverseFunc :: #type proc "c" (ctx: Context, n_args: c.int, args: [^]Value)