Towards virtual tables.

vtab.go

@@ -1,16 +1,26 @@
 package sqlite3
 
-// https://sqlite.org/vtab.html#xconnect
+// A Module defines the implementation of a virtual table.
+// Modules that don't also implement [ModuleCreator] provide
+// eponymous-only virtual tables or table-valued functions.
+//
+// https://sqlite.org/c3ref/module.html
 type Module interface {
+	// https://sqlite.org/vtab.html#xconnect
 	Connect(db *Conn, arg ...string) (VTab, error)
 }
 
-// https://sqlite.org/vtab.html#xcreate
+// A ModuleCreator extends Module for
+// non-eponymous virtual tables.
 type ModuleCreator interface {
 	Module
+	// https://sqlite.org/vtab.html#xcreate
 	Create(db *Conn, arg ...string) (VTabDestroyer, error)
 }
 
+// A VTab describes a particular instance of the virtual table.
+//
+// https://sqlite.org/c3ref/vtab.html
 type VTab interface {
 	// https://sqlite.org/vtab.html#xbestindex
 	BestIndex(*IndexInfo) error
@@ -20,36 +30,45 @@ type VTab interface {
 	Open() (VTabCursor, error)
 }
 
-// https://sqlite.org/vtab.html#sqlite3_module.xDestroy
+// A VTabDestroyer allows a virtual table to be destroyed.
 type VTabDestroyer interface {
 	VTab
+	// https://sqlite.org/vtab.html#sqlite3_module.xDestroy
 	Destroy() error
 }
 
-// https://sqlite.org/vtab.html#xupdate
+// A VTabUpdater allows a virtual table to be updated.
 type VTabUpdater interface {
 	VTab
+	// https://sqlite.org/vtab.html#xupdate
 	Update(arg ...Value) (rowid int64, err error)
 }
 
-// https://sqlite.org/vtab.html#xrename
+// A VTabRenamer allows a virtual table to be renamed.
 type VTabRenamer interface {
 	VTab
+	// https://sqlite.org/vtab.html#xrename
 	Rename(new string) error
 }
 
-// https://sqlite.org/vtab.html#xfindfunction
+// A VTabOverloader allows a virtual table to overload
+// SQL functions.
 type VTabOverloader interface {
 	VTab
-	FindFunction(arg int, name string) (func(ctx Context, arg ...Value), IndexConstraint)
+	// https://sqlite.org/vtab.html#xfindfunction
+	FindFunction(arg int, name string) (func(ctx Context, arg ...Value), IndexConstraintOp)
 }
 
-// https://sqlite.org/vtab.html#xintegrity
+// A VTabChecker allows a virtual table to report errors
+// to the PRAGMA integrity_check PRAGMA quick_check commands.
 type VTabChecker interface {
 	VTab
+	// https://sqlite.org/vtab.html#xintegrity
 	Integrity(schema, table string, flags int) error
 }
 
+// A VTabTx allows a virtual table to implement
+// transactions with two-phase commit.
 type VTabTx interface {
 	VTab
 	// https://sqlite.org/vtab.html#xBegin
@@ -62,6 +81,9 @@ type VTabTx interface {
 	Rollback() error
 }
 
+// A VTabSavepointer allows a virtual table to implement
+// nested transactions.
+//
 // https://sqlite.org/vtab.html#xsavepoint
 type VTabSavepointer interface {
 	VTabTx
@@ -70,6 +92,11 @@ type VTabSavepointer interface {
 	RollbackTo(id int) error
 }
 
+// A VTabCursor describes cursors that point
+// into the virtual table and are used
+// to loop through the virtual table.
+//
+// http://sqlite.org/c3ref/vtab_cursor.html
 type VTabCursor interface {
 	// https://sqlite.org/vtab.html#xclose
 	Close() error
@@ -85,6 +112,64 @@ type VTabCursor interface {
 	RowID() (int64, error)
 }
 
-type IndexInfo struct{}
+// An IndexInfo describes virtual table indexing information.
+//
+// https://sqlite.org/c3ref/index_info.html
+type IndexInfo struct {
+	/* Inputs */
+	Constraint []struct {
+		Column int
+		Op     IndexConstraintOp
+		Usable bool
+	}
+	OrderBy []struct {
+		Column int
+		Desc   bool
+	}
+	/* Outputs */
+	ConstraintUsage []struct {
+		ArgvIndex int
+		Omit      bool
+	}
+	IdxNum          int
+	IdxStr          string
+	IdxFlags        IndexScanFlag
+	OrderByConsumed bool
+	EstimatedCost   float64
+	EstimatedRows   int64
+	ColumnsUsed     int64
+}
 
-type IndexConstraint uint8
+// IndexConstraintOp is a virtual table constraint operator code.
+//
+// https://sqlite.org/c3ref/c_index_constraint_eq.html
+type IndexConstraintOp uint8
+
+const (
+	Eq        IndexConstraintOp = 2
+	Gt        IndexConstraintOp = 4
+	Le        IndexConstraintOp = 8
+	Lt        IndexConstraintOp = 16
+	Ge        IndexConstraintOp = 32
+	Match     IndexConstraintOp = 64
+	Like      IndexConstraintOp = 65  /* 3.10.0 and later */
+	Glob      IndexConstraintOp = 66  /* 3.10.0 and later */
+	Regexp    IndexConstraintOp = 67  /* 3.10.0 and later */
+	Ne        IndexConstraintOp = 68  /* 3.21.0 and later */
+	IsNot     IndexConstraintOp = 69  /* 3.21.0 and later */
+	IsNotNull IndexConstraintOp = 70  /* 3.21.0 and later */
+	IsNull    IndexConstraintOp = 71  /* 3.21.0 and later */
+	Is        IndexConstraintOp = 72  /* 3.21.0 and later */
+	Limit     IndexConstraintOp = 73  /* 3.38.0 and later */
+	Offset    IndexConstraintOp = 74  /* 3.38.0 and later */
+	Function  IndexConstraintOp = 150 /* 3.25.0 and later */
+)
+
+// IndexScanFlag is a virtual table scan flag.
+//
+// https://www.sqlite.org/c3ref/c_index_scan_unique.html
+type IndexScanFlag uint8
+
+const (
+	Unique IndexScanFlag = 1
+)