sqlite

package
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 5, 2026 License: GPL-3.0 Imports: 40 Imported by: 0

Documentation

Overview

Package sqlite implements Golem's SQLite physical-schema provider. All SQL originates from validated physical descriptors; no API accepts caller SQL.

Index

Constants

View Source 
const (
	AnalyticsIntegerSumFunction     = "golem_analytics_integer_sum_v1"
	AnalyticsDecimalSumFunction     = "golem_analytics_decimal_sum_v1"
	AnalyticsDecimalAvgFunction     = "golem_analytics_decimal_avg_v1"
	AnalyticsNumericCompareFunction = "golem_analytics_numeric_compare_v1"
	AnalyticsNumericCollation       = "golem_analytics_numeric_v1"
)

These names are versioned because their exact arithmetic and canonical-text result contracts are part of the provider ABI, not application SQL.

View Source 
const (
	CapabilityJSON1             ir.CapabilityID = "sqlite.json1"
	CapabilityGeneratedColumns  ir.CapabilityID = "sqlite.generated_columns"
	CapabilityExpressionIndexes ir.CapabilityID = "sqlite.expression_indexes"
	CapabilityPartialIndexes    ir.CapabilityID = "sqlite.partial_indexes"
	CapabilityPolicyBinaryText  ir.CapabilityID = "policy.binary-text.v1"
	CapabilityPolicyASCIIText   ir.CapabilityID = "policy.ascii-insensitive-text.v1"
	CapabilityPolicyExactJSON   ir.CapabilityID = "policy.exact-json.v1"
	CapabilityPolicyScalarList  ir.CapabilityID = "scalar-list.json-array.v1"
	CapabilityPolicyRelation    ir.CapabilityID = "policy.relation-correlation.v1"
	CapabilityAnalyticsExact    ir.CapabilityID = "analytics.exact-arithmetic.v1"
	CapabilityVec0              ir.CapabilityID = "sqlite.vec0.v1"
)
View Source 
const VerifiedPoolWidth = 4

Variables

This section is empty.

Functions

func CaptureQueryPlan added in v0.1.0 

func CaptureQueryPlan(ctx context.Context, connection *sqlx.Conn, statement string, arguments []any, registry *schema.Registry, aliases queryplancapture.AliasMap) (queryplancapture.Plan, error)

CaptureQueryPlan owns and closes every EXPLAIN row before returning. The caller retains ownership of connection and must release it only after this function returns; this function never closes or returns provider authority.

Types

type CapabilityReport 

type CapabilityReport struct {
	Version          physical.Version
	ForeignKeys      bool
	JSON1            bool
	GeneratedColumns bool
	PolicyBinaryText bool
	PolicyASCIIText  bool
	PolicyExactJSON  bool
	PolicyScalarList bool
	PolicyRelation   bool
	AnalyticsExact   bool
	Vec0             bool
	VecVersion       string
}

type ColumnCopy 

type ColumnCopy struct {
	FieldID               ir.FieldID
	Source                physical.PhysicalName
	Destination           physical.PhysicalName
	InitializeConcurrency bool
}

ColumnCopy is one explicit, identity-preserving leg of a SQLite rebuild. Generated and newly defaulted columns are intentionally absent.

type IncrementalPlan 

type IncrementalPlan struct {
	MigrationID migration.MigrationID
	Rebuilds    []TableRebuild
	// contains filtered or unexported fields
}

IncrementalPlan is an immutable provider-generated execution plan. Rebuilds are exposed for auditability; executable statements cannot be supplied by a caller.

type PolicyDialect 

type PolicyDialect struct{}

PolicyDialect is SQLite's closed P2 leaf renderer. Traversal, aliases, relation correlation, and argument order remain owned by internal/policy/sql.

func NewPolicyDialect 

func NewPolicyDialect() PolicyDialect

func (PolicyDialect) Encode 

func (PolicyDialect) Encode(bound policysql.BoundValue) (any, error)

func (PolicyDialect) Placeholder 

func (PolicyDialect) Placeholder(position int) string

func (PolicyDialect) Provider 

func (PolicyDialect) Provider() ir.Provider

func (PolicyDialect) Quote 

func (PolicyDialect) Quote(name physical.PhysicalName) string

func (PolicyDialect) RenderJSON 

func (PolicyDialect) RenderJSON(leaf policysql.JSONLeaf, binder *policysql.Binder) (string, error)

func (PolicyDialect) RenderList 

func (PolicyDialect) RenderList(leaf policysql.ListLeaf, binder *policysql.Binder) (string, error)

func (PolicyDialect) RenderScalar 

func (PolicyDialect) RenderScalar(leaf policysql.ScalarLeaf, binder *policysql.Binder) (string, error)

func (PolicyDialect) Supports 

func (PolicyDialect) Supports(operator ir.OperatorID) bool

func (PolicyDialect) Table 

func (PolicyDialect) Table(model policysql.Model) string

type Provider 

type Provider struct{}

func New 

func New() *Provider

func (*Provider) ApplyInitial 

func (provider *Provider) ApplyInitial(ctx context.Context, database *sqlx.DB, schema physical.PhysicalSchema) error

func (*Provider) ApplyMigration 

func (provider *Provider) ApplyMigration(ctx context.Context, database *sqlx.DB, manifest migration.Manifest, files map[string][]byte) error

ApplyMigration verifies immutable history and applies exactly the next reviewed entry. A call never skips, rewrites, or batches ledger entries.

func (*Provider) CheckpointForBackup added in v0.1.0 

func (provider *Provider) CheckpointForBackup(ctx context.Context, dataSourceName string) error

CheckpointForBackup performs the bounded provider-owned WAL checkpoint that the supported backup procedure requires before the database file is copied. It is recovery/backup code, not runtime code: the caller must already have stopped application writes and closed the Golem provider handle. The checkpoint runs through a maintenance connection this call owns, requires the truncating checkpoint to leave no busy frames and no residual log, and never deletes or truncates a sidecar file itself. A busy reader fails the call so the operator does not copy an incomplete database.

func (*Provider) EventCoordinator 

func (*Provider) EventCoordinator(database *sqlx.DB) (eventprovider.Coordinator, error)

EventCoordinator binds the closed P7 delivery state machine to a live SQLite database. It accepts no physical names or caller-authored SQL.

func (*Provider) Introspect 

func (provider *Provider) Introspect(ctx context.Context, database *sqlx.DB, expected physical.PhysicalSchema) (physical.PhysicalSchema, error)

func (*Provider) Lower 

func (provider *Provider) Lower(ctx context.Context, model ir.ModelIR, options physical.LowerOptions) (physical.PhysicalSchema, error)

Lower implements physical.Lowerer.

func (*Provider) Manifest 

func (*Provider) Manifest() physical.ProviderManifest

func (*Provider) Open 

func (provider *Provider) Open(ctx context.Context, dataSourceName string) (*sqlx.DB, CapabilityReport, error)

Open opens the CGO-free sqlite-vec WASM database through sqlx and proves the provider floor and required connection capabilities before returning it.

func (*Provider) PlanIncremental 

func (provider *Provider) PlanIncremental(entry migration.ManifestEntry) (IncrementalPlan, error)

PlanIncremental lowers an already reviewed semantic migration entry. It accepts no casts, backfills, manual SQL, or caller-defined transforms.

func (*Provider) PolicyCapabilityProof 

func (provider *Provider) PolicyCapabilityProof(ctx context.Context, database *sqlx.DB, schemaFingerprint [32]byte) (policysql.CapabilityProof, error)

PolicyCapabilityProof measures the complete SQLite P2 policy function set on two distinct pooled connections, then binds that result to the caller's already-validated logical schema fingerprint.

func (*Provider) Probe 

func (provider *Provider) Probe(ctx context.Context, database *sqlx.DB) (CapabilityReport, error)

func (*Provider) QueueStore added in v0.3.0 

func (*Provider) QueueStore(database *sqlx.DB) (queueprovider.Store, error)

QueueStore binds the durable job state machine to a live SQLite database. The table is storage the provider owns rather than a managed physical object, so the store creates it idempotently and accepts no caller-authored SQL or physical names.

func (*Provider) ReadLedger 

func (*Provider) ReadLedger(ctx context.Context, database *sqlx.DB) ([]migration.LedgerEntry, error)

ReadLedger returns the exact ordered SQLite migration chain.

func (*Provider) ReadLedgerForSchema 

func (*Provider) ReadLedgerForSchema(ctx context.Context, database *sqlx.DB, system physical.SystemSchema) ([]migration.LedgerEntry, error)

ReadLedgerForSchema reads the ledger object named by the selected generated physical schema instead of assuming a hard-coded system object identity.

func (*Provider) RenderInitial 

func (provider *Provider) RenderInitial(schema physical.PhysicalSchema) (Script, error)

func (*Provider) RenderMigration 

func (provider *Provider) RenderMigration(entry migration.ManifestEntry) (Script, error)

RenderMigration returns the exact provider DDL reviewed for one typed entry. ApplyMigration independently reconstructs the same private plan from the checksummed snapshots; reviewed SQL is never accepted as executable input.

func (*Provider) VerifiedPoolPolicyCapabilityProof 

func (provider *Provider) VerifiedPoolPolicyCapabilityProof(ctx context.Context, database *sqlx.DB, schemaFingerprint [32]byte, width int) (policysql.CapabilityProof, error)

VerifiedPoolPolicyCapabilityProof binds a full sealed-pool verification to the logical schema fingerprint consumed by the runtime policy compiler.

func (*Provider) Verify 

func (provider *Provider) Verify(ctx context.Context, database *sqlx.DB, expected physical.PhysicalSchema) error

func (*Provider) VerifyPool 

func (*Provider) VerifyPool(ctx context.Context, database *sqlx.DB, width int) (CapabilityReport, error)

VerifyPool proves every sealed pool slot while holding all slots at once. A pre-existing borrower or acquisition wait invalidates startup because the complete connection state could not be observed atomically.

type Script 

type Script struct {
	// contains filtered or unexported fields
}

Script is immutable provider-generated DDL. It has no public constructor and cannot carry application-supplied statements.

func (Script) SQL 

func (script Script) SQL() string

type TableRebuild 

type TableRebuild struct {
	TableID         ir.ModelID
	SourceTableName physical.PhysicalName
	TemporaryName   physical.PhysicalName
	DesiredTable    physical.PhysicalTable
	OperationIDs    []migration.OperationID
	Columns         []ColumnCopy
}

TableRebuild is the reviewed semantic description lowered to SQLite's complete-table replacement algorithm. SQL remains provider-private.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.