54 lines
2.6 KiB
Go
54 lines
2.6 KiB
Go
// 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 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.
|