Documentation
¶
Overview ¶
Package sqlitevec is the default CKV VectorStore implementation — SQLite + the sqlite-vec extension's vec0 virtual table.
Why SQLite? Life-cycle and idiom parity with CKG. Why CGO? vec0 ships as a C amalgamation; the cgo binding embeds it so there is no separate shared library to install on the user's machine.
Index ¶
- Constants
- Variables
- func BackupPath(dbPath string, ts time.Time) string
- func MigrationsDir() string
- type Migration
- type MigrationOption
- type MigrationRunner
- type MigrationStatus
- type Store
- func (s *Store) AllFiles(ctx context.Context) ([]string, error)
- func (s *Store) Close() error
- func (s *Store) DeleteByFile(ctx context.Context, path string) error
- func (s *Store) Dim() int
- func (s *Store) FindConventions(ctx context.Context, packagePrefix string) ([]types.Chunk, error)
- func (s *Store) FindInvariants(ctx context.Context, file, category string) ([]types.Chunk, error)
- func (s *Store) LookupByFileOrdered(ctx context.Context, file string) ([]types.Chunk, error)
- func (s *Store) LookupByIDs(ctx context.Context, ids []string) ([]types.Chunk, error)
- func (s *Store) LookupPRsByFile(ctx context.Context, file string) ([]types.PRRef, error)
- func (s *Store) Search(ctx context.Context, query []float32, k int, filter types.Filter) ([]types.Hit, error)
- func (s *Store) SetManifest(_ context.Context, kv map[string]string) error
- func (s *Store) Stats(ctx context.Context) (types.Stats, error)
- func (s *Store) UpdateRecentPRs(ctx context.Context, filePRs map[string][]types.PRRef) (int, error)
- func (s *Store) Upsert(ctx context.Context, chunks []types.Chunk, embeddings [][]float32) error
Constants ¶
const SchemaVersion = "1.0"
SchemaVersion is stamped into the manifest table on first init. Bump when the SQL schema changes in a way old binaries cannot read.
Variables ¶
var ErrMigrationRequired = errors.New("sqlitevec: pending schema migrations (run `ckv migrate --out PATH`)")
ErrMigrationRequired is returned by Open when the DB has pending migrations. Callers can offer the user an actionable hint.
var ErrMigrationTampered = errors.New("sqlitevec: applied migration content has changed (file edited after apply)")
ErrMigrationTampered indicates an applied migration's source SQL has changed since it was first applied. Refuse to continue: silently re-running a different SQL would corrupt the DB invisibly.
Functions ¶
func BackupPath ¶
BackupPath returns the conventional backup filename for the given DB path + timestamp. Useful for tests and CLI hint messages.
func MigrationsDir ¶
func MigrationsDir() string
MigrationsDir returns the absolute path to the embedded migrations directory relative to the running binary. Used for `ckv migrate --help` to display where migrations live for inspection.
Returns empty string when running from binary (embedded only).
Types ¶
type Migration ¶
type Migration struct {
Version string // "000", "001", ...
Name string // "baseline", "add_category_guidance", ...
File string // "000_baseline.sql"
SQL string // file content
SHA256 string // hex sha256 of SQL
}
Migration is one applied or pending schema change.
type MigrationOption ¶
type MigrationOption func(*MigrationRunner)
MigrationOption configures a MigrationRunner.
func WithBackup ¶
func WithBackup(enabled bool) MigrationOption
WithBackup enables (default) or disables auto-backup before Apply.
func WithSource ¶
func WithSource(source fs.FS, dir string) MigrationOption
WithSource overrides the embedded migration FS. Useful for tests. dir is the subdirectory containing *.sql files (e.g. "migrations").
type MigrationRunner ¶
type MigrationRunner struct {
// contains filtered or unexported fields
}
MigrationRunner applies SQL migrations from an fs.FS to a database and tracks the applied versions in the schema_migrations table.
func NewMigrationRunner ¶
func NewMigrationRunner(db *sql.DB, dbPath string, opts ...MigrationOption) *MigrationRunner
NewMigrationRunner constructs a runner. dbPath is used for auto-backup (pass "" to disable backup regardless of WithBackup).
func (*MigrationRunner) Apply ¶
func (r *MigrationRunner) Apply(ctx context.Context) error
Apply runs all pending migrations in version order. Each migration runs in its own transaction. On the first failure, the runner stops (later migrations are not attempted).
If backup is enabled and dbPath is set, a copy of the DB file is written to "<dbPath>.bak.<unix-ts>" before any migration runs.
func (*MigrationRunner) DryRun ¶
func (r *MigrationRunner) DryRun(ctx context.Context) ([]Migration, error)
DryRun returns the SQL that Apply would execute, without touching the DB.
func (*MigrationRunner) Status ¶
func (r *MigrationRunner) Status(ctx context.Context) (*MigrationStatus, error)
Status reports which migrations are applied vs pending. Read-only.
type MigrationStatus ¶
type MigrationStatus struct {
Current string // latest applied version, "" if none
Applied []Migration // already applied, in order
Pending []Migration // yet to apply, in order
Tampered []Migration // applied versions whose SQL changed (block)
}
MigrationStatus is what `ckv migrate --dry-run` (or Status()) prints.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements types.VectorStore over SQLite + vec0.
func Open ¶
Open opens (or creates) the DB at path. dim must match the stored dimension if the DB already has data. Pass dim from the Embedder's Dimension() — that gives us a single source of truth for what the embeddings look like.
After schema init, pending migrations from the embedded migrations FS are applied automatically. Set CKV_DISABLE_AUTO_MIGRATE=1 to refuse rather than apply (Open then returns ErrMigrationRequired so callers can surface the recommended `ckv migrate` hint).
func (*Store) AllFiles ¶
AllFiles returns every distinct file path indexed in the store. Used by the keyword index builder to enumerate the corpus without holding the whole result set in memory at once.
func (*Store) DeleteByFile ¶
DeleteByFile removes every chunk + vector belonging to the given path. Used by the incremental indexer and the rename safety path.
func (*Store) FindConventions ¶
FindConventions returns ChunkConvention rows for the given package prefix. Empty prefix returns every convention chunk in the index. The prefix is matched against the chunk's File field using SQLite's LIKE ('prefix%') so subdirectories are included.
func (*Store) FindInvariants ¶
FindInvariants returns ChunkInvariant rows matching the file or category filter. Both filters are optional; passing both ANDs them. Empty file + empty category returns every invariant in the index.
The returned chunks are the invariant rows themselves (ChunkKind == ChunkInvariant). To navigate back to a source chunk, callers walk the source chunk's Invariants field — invariants register their refs by ChunkID on the source side.
func (*Store) LookupByFileOrdered ¶
LookupByFileOrdered returns every chunk in file ordered by start_line. Used by expand_in_file to fetch the neighbour set for a given hit.
func (*Store) LookupByIDs ¶
LookupByIDs returns the chunks with the given IDs in arbitrary order. IDs that do not exist are silently skipped. The input slice is processed in groups of 900 to respect SQLite's parameter limit (999).
func (*Store) LookupPRsByFile ¶
LookupPRsByFile returns the merged PRRef lists for all chunks matching the given file path. Deduplicates by PR number.
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, query []float32, k int, filter types.Filter) ([]types.Hit, error)
Search runs a vec0 KNN over query, then JOINs to chunks for metadata and applies the Filter as a post-step. We over-fetch by 3x when a filter is set so the post-filter has enough candidates to satisfy k.
func (*Store) SetManifest ¶
SetManifest persists arbitrary identity keys (embedding_model, etc). Called by the indexer after a successful build so the DB carries its own copy of the manifest in addition to the JSON sidecar.
func (*Store) Stats ¶
Stats returns aggregate index counts + manifest identity. The manifest fields come from the in-DB manifest table written by SetManifest at build time.
func (*Store) UpdateRecentPRs ¶
UpdateRecentPRs sets the recent_prs JSON column for source chunks whose file matches entries in filePRs. Only updates rows where recent_prs is currently empty (avoids overwriting prior tagging). Returns the total number of rows updated.
Source Files