vendor

vendor/modernc.org/sqlite/vtab/doc.go

@@ -0,0 +1,59 @@
+// Package vtab defines a Go-facing API for implementing SQLite virtual table
+// modules on top of the modernc.org/sqlite driver.
+//
+// It is intentionally small and generic so that external projects can
+// implement virtual tables without depending on the translated C internals.
+package vtab
+
+// API notes
+//
+// - Schema declaration: Modules must call Context.Declare from within Create
+//   or Connect to declare the virtual table schema (a CREATE TABLE statement).
+//   The driver no longer auto-declares based on USING(...) args to support
+//   dynamic schemas (e.g., CSV headers).
+//
+// - Constraint support: Modules that want MATCH/other constraints must call
+//   Context.EnableConstraintSupport from within Create or Connect.
+//
+// - Vtab config: Modules can call Context.Config to pass sqlite3_vtab_config
+//   options (e.g., INNOCUOUS, DIRECTONLY) from within Create or Connect.
+//
+// - Constraint operators: ConstraintOp includes OpUnknown for operators that
+//   are not recognized. The driver maps common SQLite operators including EQ,
+//   NE, GT, GE, LT, LE, MATCH, IS/ISNOT, ISNULL/ISNOTNULL, LIKE, GLOB, REGEXP,
+//   FUNCTION, LIMIT, and OFFSET.
+//
+// - ArgIndex: Set as 0-based in Go to indicate which position in argv[] should
+//   receive a constraint value. The driver adds +1 when communicating with
+//   SQLite (which is 1-based). Use -1 (default) to ignore.
+//
+// - Omit: Set Constraint.Omit to ask SQLite to not re-evaluate that constraint
+//   in the parent query if the virtual table fully handles it.
+//
+// - ColUsed: IndexInfo.ColUsed provides a bitmask of columns referenced by the
+//   query. Bit N indicates column N is used.
+//
+// - IdxFlags: IndexInfo.IdxFlags allows modules to set planning flags.
+//   Currently, IndexScanUnique (mirrors SQLITE_INDEX_SCAN_UNIQUE) indicates
+//   the plan will visit at most one row. This can help the optimizer.
+//
+// Optional interfaces
+//
+// - Updater: Implement on your Table to support writes via xUpdate.
+//   Insert(cols, *rowid), Update(oldRowid, cols, *newRowid), Delete(oldRowid).
+//   The trampoline maps SQLite xUpdate’s calling convention to these methods.
+//
+// - Renamer: Implement Rename(newName string) on your Table to handle xRename.
+//   If unimplemented, rename is treated as a no-op.
+//
+// - Transactional: Implement Begin/Sync/Commit/Rollback/Savepoint/Release/
+//   RollbackTo as needed. Unimplemented methods are treated as no-ops.
+//   These callbacks let writable or advanced modules coordinate with SQLite
+//   transaction boundaries.
+//
+// Re-entrancy cautions
+// - Avoid executing SQL on the same connection from within vtab methods
+//   (Create/Connect/BestIndex/Filter/etc.). SQLite virtual table callbacks run
+//   inside the engine and issuing re-entrant SQL on the same connection can
+//   lead to deadlocks or undefined behavior. If a module requires issuing SQL,
+//   consider using a separate connection and document the concurrency model.