More APIs.

README.md

@@ -93,7 +93,7 @@ This project aims for [high test coverage](https://github.com/ncruces/go-sqlite3
 It also benefits greatly from [SQLite's](https://sqlite.org/testing.html) and
 [wazero's](https://tetrate.io/blog/introducing-wazero-from-tetrate/#:~:text=Rock%2Dsolid%20test%20approach) thorough testing.
 
-Every commit is [tested](.github/workflows/test.yml) on
+Every commit is [tested](https://github.com/ncruces/go-sqlite3/wiki/Test-matrix) on
 Linux (amd64/arm64/386/riscv64/s390x), macOS (amd64/arm64),
 Windows (amd64), FreeBSD (amd64), OpenBSD (amd64), NetBSD (amd64),
 illumos (amd64), and Solaris (amd64).

config.go

@@ -162,7 +162,7 @@ func (c *Conn) Limit(id LimitCategory, value int) int {
 // SetAuthorizer registers an authorizer callback with the database connection.
 //
 // https://sqlite.org/c3ref/set_authorizer.html
-func (c *Conn) SetAuthorizer(cb func(action AuthorizerActionCode, name3rd, name4th, schema, nameInner string) AuthorizerReturnCode) error {
+func (c *Conn) SetAuthorizer(cb func(action AuthorizerActionCode, name3rd, name4th, schema, inner string) AuthorizerReturnCode) error {
 	var enable uint64
 	if cb != nil {
 		enable = 1
@@ -176,9 +176,9 @@ func (c *Conn) SetAuthorizer(cb func(action AuthorizerActionCode, name3rd, name4
 
 }
 
-func authorizerCallback(ctx context.Context, mod api.Module, pDB uint32, action AuthorizerActionCode, zName3rd, zName4th, zSchema, zNameInner uint32) (rc AuthorizerReturnCode) {
+func authorizerCallback(ctx context.Context, mod api.Module, pDB uint32, action AuthorizerActionCode, zName3rd, zName4th, zSchema, zInner uint32) (rc AuthorizerReturnCode) {
 	if c, ok := ctx.Value(connKey{}).(*Conn); ok && c.handle == pDB && c.authorizer != nil {
-		var name3rd, name4th, schema, nameInner string
+		var name3rd, name4th, schema, inner string
 		if zName3rd != 0 {
 			name3rd = util.ReadString(mod, zName3rd, _MAX_NAME)
 		}
@@ -188,10 +188,48 @@ func authorizerCallback(ctx context.Context, mod api.Module, pDB uint32, action
 		if zSchema != 0 {
 			schema = util.ReadString(mod, zSchema, _MAX_NAME)
 		}
-		if zNameInner != 0 {
-			nameInner = util.ReadString(mod, zNameInner, _MAX_NAME)
+		if zInner != 0 {
+			inner = util.ReadString(mod, zInner, _MAX_NAME)
+		}
+		rc = c.authorizer(action, name3rd, name4th, schema, inner)
+	}
+	return rc
+}
+
+// Trace registers a trace callback function against the database connection.
+//
+// https://sqlite.org/c3ref/trace_v2.html
+func (c *Conn) Trace(mask TraceEvent, cb func(evt TraceEvent, arg1 any, arg2 any) error) error {
+	r := c.call("sqlite3_trace_go", uint64(c.handle), uint64(mask))
+	if err := c.error(r); err != nil {
+		return err
+	}
+	c.trace = cb
+	return nil
+}
+
+func traceCallback(ctx context.Context, mod api.Module, evt TraceEvent, pDB, pArg1, pArg2 uint32) (rc uint32) {
+	if c, ok := ctx.Value(connKey{}).(*Conn); ok && c.handle == pDB && c.trace != nil {
+		var arg1, arg2 any
+		if evt == TRACE_CLOSE {
+			arg1 = c
+		} else {
+			for _, s := range c.stmts {
+				if pArg1 == s.handle {
+					arg1 = s
+					switch evt {
+					case TRACE_STMT:
+						arg2 = s.SQL()
+					case TRACE_PROFILE:
+						arg2 = int64(util.ReadUint64(mod, pArg2))
+					}
+					break
+				}
+			}
+		}
+		if arg1 != nil {
+			_, rc = errorCode(c.trace(evt, arg1, arg2), ERROR)
 		}
-		rc = c.authorizer(action, name3rd, name4th, schema, nameInner)
 	}
 	return rc
 }

conn.go

@@ -22,14 +22,16 @@ type Conn struct {
 
 	interrupt  context.Context
 	pending    *Stmt
+	stmts      []*Stmt
 	busy       func(int) bool
 	log        func(xErrorCode, string)
 	collation  func(*Conn, string)
+	wal        func(*Conn, string, int) error
+	trace      func(TraceEvent, any, any) error
 	authorizer func(AuthorizerActionCode, string, string, string, string) AuthorizerReturnCode
 	update     func(AuthorizerActionCode, string, string, int64)
 	commit     func() bool
 	rollback   func()
-	wal        func(*Conn, string, int) error
 	arena      arena
 
 	handle uint32
@@ -202,6 +204,7 @@ func (c *Conn) PrepareFlags(sql string, flags PrepareFlag) (stmt *Stmt, tail str
 	if stmt.handle == 0 {
 		return nil, "", nil
 	}
+	c.stmts = append(c.stmts, stmt)
 	return stmt, tail, nil
 }
 
@@ -326,7 +329,12 @@ func (c *Conn) SetInterrupt(ctx context.Context) (old context.Context) {
 	// A busy SQL statement prevents SQLite from ignoring an interrupt
 	// that comes before any other statements are started.
 	if c.pending == nil {
-		c.pending, _, _ = c.Prepare(`WITH RECURSIVE c(x) AS (VALUES(0) UNION ALL SELECT x FROM c) SELECT x FROM c`)
+		defer c.arena.mark()()
+		stmtPtr := c.arena.new(ptrlen)
+		loopPtr := c.arena.string(`WITH RECURSIVE c(x) AS (VALUES(0) UNION ALL SELECT x FROM c) SELECT x FROM c`)
+		c.call("sqlite3_prepare_v3", uint64(c.handle), uint64(loopPtr), math.MaxUint64, 0, uint64(stmtPtr), 0)
+		c.pending = &Stmt{c: c}
+		c.pending.handle = util.ReadUint32(c.mod, stmtPtr)
 	}
 
 	old = c.interrupt
@@ -414,6 +422,62 @@ func busyCallback(ctx context.Context, mod api.Module, pDB uint32, count int32)
 	return retry
 }
 
+// Status retrieves runtime status information about a database connection.
+//
+// https://sqlite.org/c3ref/db_status.html
+func (c *Conn) Status(op DBStatus, reset bool) (current, highwater int, err error) {
+	defer c.arena.mark()()
+	hiPtr := c.arena.new(4)
+	curPtr := c.arena.new(4)
+
+	var i uint64
+	if reset {
+		i = 1
+	}
+
+	r := c.call("sqlite3_db_status", uint64(c.handle),
+		uint64(op), uint64(curPtr), uint64(hiPtr), i)
+	if err = c.error(r); err == nil {
+		current = int(util.ReadUint32(c.mod, curPtr))
+		highwater = int(util.ReadUint32(c.mod, hiPtr))
+	}
+	return
+}
+
+// TableColumnMetadata extracts metadata about a column of a table.
+//
+// https://sqlite.org/c3ref/table_column_metadata.html
+func (c *Conn) TableColumnMetadata(schema, table, column string) (declType, collSeq string, notNull, primaryKey, autoInc bool, err error) {
+	defer c.arena.mark()()
+
+	var schemaPtr, columnPtr uint32
+	declTypePtr := c.arena.new(ptrlen)
+	collSeqPtr := c.arena.new(ptrlen)
+	notNullPtr := c.arena.new(ptrlen)
+	primaryKeyPtr := c.arena.new(ptrlen)
+	autoIncPtr := c.arena.new(ptrlen)
+	if schema != "" {
+		schemaPtr = c.arena.string(schema)
+	}
+	tablePtr := c.arena.string(table)
+	if column != "" {
+		columnPtr = c.arena.string(column)
+	}
+
+	r := c.call("sqlite3_table_column_metadata", uint64(c.handle),
+		uint64(schemaPtr), uint64(tablePtr), uint64(columnPtr),
+		uint64(declTypePtr), uint64(collSeqPtr),
+		uint64(notNullPtr), uint64(primaryKeyPtr), uint64(autoIncPtr))
+	if err = c.error(r); err == nil && column != "" {
+		declType = util.ReadString(c.mod, util.ReadUint32(c.mod, declTypePtr), _MAX_NAME)
+		collSeq = util.ReadString(c.mod, util.ReadUint32(c.mod, collSeqPtr), _MAX_NAME)
+		notNull = util.ReadUint32(c.mod, notNullPtr) != 0
+		autoInc = util.ReadUint32(c.mod, autoIncPtr) != 0
+		primaryKey = util.ReadUint32(c.mod, primaryKeyPtr) != 0
+	}
+	return
+}
+
 func (c *Conn) error(rc uint64, sql ...string) error {
 	return c.sqlite.error(rc, c.handle, sql...)
 }

const.go

@@ -109,7 +109,7 @@ const (
 	CANTOPEN_ISDIR          ExtendedErrorCode = xErrorCode(CANTOPEN) | (2 << 8)
 	CANTOPEN_FULLPATH       ExtendedErrorCode = xErrorCode(CANTOPEN) | (3 << 8)
 	CANTOPEN_CONVPATH       ExtendedErrorCode = xErrorCode(CANTOPEN) | (4 << 8)
-	CANTOPEN_DIRTYWAL       ExtendedErrorCode = xErrorCode(CANTOPEN) | (5 << 8) /* Not Used */
+	// CANTOPEN_DIRTYWAL    ExtendedErrorCode = xErrorCode(CANTOPEN) | (5 << 8) /* Not Used */
 	CANTOPEN_SYMLINK        ExtendedErrorCode = xErrorCode(CANTOPEN) | (6 << 8)
 	CORRUPT_VTAB            ExtendedErrorCode = xErrorCode(CORRUPT) | (1 << 8)
 	CORRUPT_SEQUENCE        ExtendedErrorCode = xErrorCode(CORRUPT) | (2 << 8)
@@ -177,11 +177,11 @@ const (
 type FunctionFlag uint32
 
 const (
-	DETERMINISTIC  FunctionFlag = 0x000000800
-	DIRECTONLY     FunctionFlag = 0x000080000
-	SUBTYPE        FunctionFlag = 0x000100000
-	INNOCUOUS      FunctionFlag = 0x000200000
-	RESULT_SUBTYPE FunctionFlag = 0x001000000
+	DETERMINISTIC FunctionFlag = 0x000000800
+	DIRECTONLY    FunctionFlag = 0x000080000
+	INNOCUOUS     FunctionFlag = 0x000200000
+	// SUBTYPE        FunctionFlag = 0x000100000
+	// RESULT_SUBTYPE FunctionFlag = 0x001000000
 )
 
 // StmtStatus name counter values associated with the [Stmt.Status] method.
@@ -201,6 +201,27 @@ const (
 	STMTSTATUS_MEMUSED       StmtStatus = 99
 )
 
+// DBStatus are the available "verbs" that can be passed to the [Conn.Status] method.
+//
+// https://sqlite.org/c3ref/c_dbstatus_options.html
+type DBStatus uint32
+
+const (
+	DBSTATUS_LOOKASIDE_USED      DBStatus = 0
+	DBSTATUS_CACHE_USED          DBStatus = 1
+	DBSTATUS_SCHEMA_USED         DBStatus = 2
+	DBSTATUS_STMT_USED           DBStatus = 3
+	DBSTATUS_LOOKASIDE_HIT       DBStatus = 4
+	DBSTATUS_LOOKASIDE_MISS_SIZE DBStatus = 5
+	DBSTATUS_LOOKASIDE_MISS_FULL DBStatus = 6
+	DBSTATUS_CACHE_HIT           DBStatus = 7
+	DBSTATUS_CACHE_MISS          DBStatus = 8
+	DBSTATUS_CACHE_WRITE         DBStatus = 9
+	DBSTATUS_DEFERRED_FKS        DBStatus = 10
+	DBSTATUS_CACHE_USED_SHARED   DBStatus = 11
+	DBSTATUS_CACHE_SPILL         DBStatus = 12
+)
+
 // DBConfig are the available database connection configuration options.
 //
 // https://sqlite.org/c3ref/c_dbconfig_defensive.html
@@ -307,8 +328,8 @@ const (
 	AUTH_DROP_VTABLE         AuthorizerActionCode = 30 /* Table Name      Module Name     */
 	AUTH_FUNCTION            AuthorizerActionCode = 31 /* NULL            Function Name   */
 	AUTH_SAVEPOINT           AuthorizerActionCode = 32 /* Operation       Savepoint Name  */
-	AUTH_COPY                AuthorizerActionCode = 0  /* No longer used */
 	AUTH_RECURSIVE           AuthorizerActionCode = 33 /* NULL            NULL            */
+	// AUTH_COPY             AuthorizerActionCode = 0  /* No longer used */
 )
 
 // AuthorizerReturnCode are the integer codes
@@ -346,6 +367,18 @@ const (
 	TXN_WRITE TxnState = 2
 )
 
+// TraceEvent identify classes of events that can be monitored with [Conn.Trace].
+//
+// https://sqlite.org/c3ref/c_trace.html
+type TraceEvent uint32
+
+const (
+	TRACE_STMT    TraceEvent = 0x01
+	TRACE_PROFILE TraceEvent = 0x02
+	TRACE_ROW     TraceEvent = 0x04
+	TRACE_CLOSE   TraceEvent = 0x08
+)
+
 // Datatype is a fundamental datatype of SQLite.
 //
 // https://sqlite.org/c3ref/c_blob.html

embed/exports.txt

@@ -55,17 +55,20 @@ sqlite3_create_function_go
 sqlite3_create_module_go
 sqlite3_create_window_function_go
 sqlite3_database_file_object
+sqlite3_db_cacheflush
 sqlite3_db_config
 sqlite3_db_filename
 sqlite3_db_name
 sqlite3_db_readonly
 sqlite3_db_release_memory
+sqlite3_db_status
 sqlite3_declare_vtab
 sqlite3_errcode
 sqlite3_errmsg
 sqlite3_error_offset
 sqlite3_errstr
 sqlite3_exec
+sqlite3_expanded_sql
 sqlite3_file_control
 sqlite3_filename_database
 sqlite3_filename_journal
@@ -101,16 +104,18 @@ sqlite3_step
 sqlite3_stmt_busy
 sqlite3_stmt_readonly
 sqlite3_stmt_status
+sqlite3_table_column_metadata
 sqlite3_total_changes64
+sqlite3_trace_go
 sqlite3_txn_state
 sqlite3_update_hook_go
 sqlite3_uri_key
-sqlite3_uri_parameter
 sqlite3_value_blob
 sqlite3_value_bytes
 sqlite3_value_double
 sqlite3_value_dup
 sqlite3_value_free
+sqlite3_value_frombind
 sqlite3_value_int64
 sqlite3_value_nochange
 sqlite3_value_numeric_type

internal/util/mmap.go

@@ -32,7 +32,7 @@ func (s *mmapState) new(ctx context.Context, mod api.Module, size int32) *Mapped
 
 	// Allocate page aligned memmory.
 	alloc := mod.ExportedFunction("aligned_alloc")
-	stack := [2]uint64{
+	stack := [...]uint64{
 		uint64(unix.Getpagesize()),
 		uint64(size),
 	}

sqlite.go

@@ -85,7 +85,7 @@ type sqlite struct {
 		id   [32]*byte
 		mask uint32
 	}
-	stack [8]uint64
+	stack [9]uint64
 	freer uint32
 }
 
@@ -306,6 +306,7 @@ func exportCallbacks(env wazero.HostModuleBuilder) wazero.HostModuleBuilder {
 	util.ExportFuncVI(env, "go_rollback_hook", rollbackCallback)
 	util.ExportFuncVIIIIJ(env, "go_update_hook", updateCallback)
 	util.ExportFuncIIIII(env, "go_wal_hook", walCallback)
+	util.ExportFuncIIIII(env, "go_trace", traceCallback)
 	util.ExportFuncIIIIII(env, "go_autovacuum_pages", autoVacuumCallback)
 	util.ExportFuncIIIIIII(env, "go_authorizer", authorizerCallback)
 	util.ExportFuncVIII(env, "go_log", logCallback)

sqlite3/hooks.c

@@ -10,7 +10,7 @@ int go_commit_hook(void *);
 void go_rollback_hook(void *);
 void go_update_hook(void *, int, char const *, char const *, sqlite3_int64);
 int go_wal_hook(void *, sqlite3 *, const char *, int);
-
+int go_trace(unsigned, void *, void *, void *);
 int go_authorizer(void *, int, const char *, const char *, const char *,
                   const char *);
 
@@ -47,6 +47,10 @@ int sqlite3_set_authorizer_go(sqlite3 *db, bool enable) {
   return sqlite3_set_authorizer(db, enable ? go_authorizer : NULL, /*arg=*/db);
 }
 
+int sqlite3_trace_go(sqlite3 *db, unsigned mask) {
+  return sqlite3_trace_v2(db, mask, go_trace, /*arg=*/db);
+}
+
 int sqlite3_config_log_go(bool enable) {
   return sqlite3_config(SQLITE_CONFIG_LOG, enable ? go_log : NULL,
                         /*arg=*/NULL);