feat: ✨ Added Sqlite reader

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

@@ -0,0 +1,53 @@
+// 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.

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

@@ -0,0 +1,245 @@
+package vtab
+
+import (
+	"database/sql"
+	"database/sql/driver"
+	"errors"
+)
+
+// Value is the value type passed to and from virtual table cursors. It
+// aliases database/sql/driver.Value to avoid exposing low-level details to
+// module authors while remaining compatible with the driver.
+type Value = driver.Value
+
+// Context carries information that a Module may need when creating or
+// connecting a table instance. It intentionally does not expose *sql.DB to
+// avoid leaking database/sql internals into the vtab API. Additional fields
+// may be added in the future as needed.
+type Context struct {
+	declare func(string) error
+}
+
+// Declare must be called by a module from within Create or Connect to declare
+// the schema of the virtual table. The provided SQL must be a CREATE TABLE
+// statement describing the exposed columns.
+//
+// The engine installs this callback so that the declaration is executed in the
+// correct context. Calling Declare outside of Create/Connect may fail.
+func (c Context) Declare(schema string) error {
+	if c.declare == nil {
+		return errors.New("vtab: declare not available in this context")
+	}
+	return c.declare(schema)
+}
+
+// NewContext is used by the engine to create a Context bound to the current
+// xCreate/xConnect call. External modules should not need to call this.
+func NewContext(declare func(string) error) Context { return Context{declare: declare} }
+
+// Module represents a virtual table module, analogous to sqlite3_module in
+// the SQLite C API. Implementations are responsible for creating and
+// connecting table instances.
+type Module interface {
+	// Create is called to create a new virtual table. args corresponds to the
+	// argv array passed to xCreate in the SQLite C API: it contains the module
+	// name, the database name, the table name, and module arguments.
+	Create(ctx Context, args []string) (Table, error)
+
+	// Connect is called to connect to an existing virtual table. Its
+	// semantics mirror xConnect in the SQLite C API.
+	Connect(ctx Context, args []string) (Table, error)
+}
+
+// Table represents a single virtual table instance (the Go analogue of
+// sqlite3_vtab and its associated methods).
+type Table interface {
+	// BestIndex allows the virtual table to inform SQLite about which
+	// constraints and orderings it can efficiently support. The IndexInfo
+	// structure mirrors sqlite3_index_info.
+	BestIndex(info *IndexInfo) error
+
+	// Open creates a new cursor for scanning the table.
+	Open() (Cursor, error)
+
+	// Disconnect is called to disconnect from a table instance (xDisconnect).
+	Disconnect() error
+
+	// Destroy is called when a table is dropped (xDestroy).
+	Destroy() error
+}
+
+// Renamer can be implemented by a Table to handle xRename.
+type Renamer interface {
+	Rename(newName string) error
+}
+
+// Transactional can be implemented by a Table to handle transaction-related
+// callbacks. Methods are optional; unimplemented methods are treated as no-op.
+type Transactional interface {
+	Begin() error
+	Sync() error
+	Commit() error
+	Rollback() error
+	Savepoint(i int) error
+	Release(i int) error
+	RollbackTo(i int) error
+}
+
+// Cursor represents a cursor over a virtual table (sqlite3_vtab_cursor).
+type Cursor interface {
+	// Filter corresponds to xFilter. idxNum and idxStr are the chosen index
+	// number and string; vals are the constraint arguments.
+	Filter(idxNum int, idxStr string, vals []Value) error
+
+	// Next advances the cursor to the next row (xNext).
+	Next() error
+
+	// Eof reports whether the cursor is past the last row (xEof != 0).
+	Eof() bool
+
+	// Column returns the value of the specified column in the current row
+	// (xColumn).
+	Column(col int) (Value, error)
+
+	// Rowid returns the current rowid (xRowid).
+	Rowid() (int64, error)
+
+	// Close closes the cursor (xClose).
+	Close() error
+}
+
+// Updater can be implemented by a Table to support writes via xUpdate.
+//
+// Semantics follow SQLite's xUpdate:
+//   - Delete: Delete(oldRowid) is called.
+//   - Insert: Insert(cols, rowid) is called. *rowid may contain a desired rowid
+//     (if provided by SQL) and should be set to the final rowid of the new row.
+//   - Update: Update(oldRowid, cols, newRowid) is called. *newRowid may be set
+//     to the final rowid of the updated row when changed.
+type Updater interface {
+	Insert(cols []Value, rowid *int64) error
+	Update(oldRowid int64, cols []Value, newRowid *int64) error
+	Delete(oldRowid int64) error
+}
+
+// ConstraintOp describes the operator used in a constraint on a virtual
+// table column. It loosely mirrors the op field of sqlite3_index_constraint.
+type ConstraintOp int
+
+const (
+	// OpUnknown indicates an operator that is not recognized or not mapped.
+	// Modules should treat this conservatively.
+	OpUnknown ConstraintOp = iota
+	OpEQ
+	OpGT
+	OpLE
+	OpLT
+	OpGE
+	OpMATCH // "MATCH" operator (e.g. for FTS or KNN semantics)
+	OpNE
+	OpIS
+	OpISNOT
+	OpISNULL
+	OpISNOTNULL
+	OpLIKE
+	OpGLOB
+	OpREGEXP
+	OpFUNCTION
+	OpLIMIT
+	OpOFFSET
+)
+
+// Constraint describes a single WHERE-clause constraint that SQLite is
+// considering pushing down to the virtual table.
+type Constraint struct {
+	Column int
+	Op     ConstraintOp
+	Usable bool
+	// ArgIndex selects which position in argv[] (0-based) should contain the
+	// RHS value for this constraint when Filter is called. Set to -1 to ignore.
+	ArgIndex int
+	// Omit requests SQLite to omit the corresponding constraint from the
+	// parent query if the virtual table fully handles it.
+	Omit bool
+}
+
+// OrderBy describes a single ORDER BY term for a query involving a virtual
+// table.
+type OrderBy struct {
+	Column int
+	Desc   bool
+}
+
+// IndexInfo holds information about constraints and orderings for a virtual
+// table query. It is the Go analogue of sqlite3_index_info.
+type IndexInfo struct {
+	Constraints []Constraint
+	OrderBy     []OrderBy
+
+	// IdxNum selects the query plan chosen in BestIndex. This value is passed
+	// back to Cursor.Filter. Note: SQLite stores this as a 32-bit signed
+	// integer (int32). Implementations must ensure IdxNum fits within the
+	// int32 range; values outside of int32 will cause an error in the driver
+	// to avoid silent truncation.
+	IdxNum int64
+	IdxStr string
+	// IdxFlags provides extra information about the chosen plan.
+	// Set to IndexScanUnique to indicate the plan visits at most one row.
+	IdxFlags        int
+	OrderByConsumed bool
+	EstimatedCost   float64
+	EstimatedRows   int64
+	// ColUsed is a bitmask indicating which columns are used by the query.
+	// Bit N is set if column N is referenced.
+	ColUsed uint64
+}
+
+// Index flag values for IndexInfo.IdxFlags.
+const (
+	// IndexScanUnique mirrors SQLITE_INDEX_SCAN_UNIQUE and indicates that the
+	// chosen plan will visit at most one row.
+	IndexScanUnique = 1
+)
+
+// ErrNotImplemented is returned by RegisterModule when the underlying engine
+// has not yet installed a registration hook. External projects can depend on
+// the vtab API surface before the low-level bridge to sqlite3_create_module
+// is fully wired; once the engine sets the hook via SetRegisterFunc,
+// RegisterModule will forward calls to it.
+var ErrNotImplemented = errors.New("vtab: RegisterModule not wired into engine")
+
+// registerHook is installed by the engine package via SetRegisterFunc. It is
+// invoked by RegisterModule to perform the actual module registration.
+var registerHook func(name string, m Module) error
+
+// SetRegisterFunc is intended to be called by the engine package to provide
+// the concrete implementation of module registration. External callers
+// should use RegisterModule instead.
+func SetRegisterFunc(fn func(name string, m Module) error) { registerHook = fn }
+
+// RegisterModule registers a virtual table module with the provided *sql.DB.
+//
+// Registration applies to new connections only. Existing open connections will
+// not be updated to include newly registered modules.
+//
+// Registration is performed when opening a new connection. If the underlying
+// sqlite3_create_module_v2 call fails, opening the connection fails and returns
+// that error. This fail-fast behavior prevents partially-initialized
+// connections when a module cannot be installed.
+//
+// The db parameter is currently unused by the engine; it is available so
+// module implementations can capture it if they need a *sql.DB for their own
+// internal queries.
+func RegisterModule(db *sql.DB, name string, m Module) error {
+	_ = db
+	if registerHook == nil {
+		return ErrNotImplemented
+	}
+	if name == "" {
+		return errors.New("vtab: module name must be non-empty")
+	}
+	if m == nil {
+		return errors.New("vtab: module implementation is nil")
+	}
+	return registerHook(name, m)
+}