Help us shape the future of Go! Take the 2026 Go Developer Survey

sqlite

package
v0.2.4 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultNodeMatchLimit = 25

DefaultNodeMatchLimit bounds the candidate list MatchNodes returns when a caller does not ask for a different size. Totals are never bounded by it.

View Source 
const TargetPageSize = 16384

TargetPageSize is the page size every index is expected to carry. Larger pages hold more index entries per read and turn the random b-tree traffic above into fewer, larger I/O operations. SQLite only honors the pragma while the database is empty and not yet in WAL mode, so a newly created index adopts it directly; one created by an earlier version carries its own page size until compaction rewrites it.

Variables

This section is empty.

Functions

func CheckpointIndex 

func CheckpointIndex(ctx context.Context, path string, expected IndexMetadata) (resultErr error)

CheckpointIndex verifies that an existing compatible database still carries the expected identity evidence, then truncates its WAL. It never creates or migrates an index.

func CopyIndex added in v0.2.0 

func CopyIndex(ctx context.Context, source, destination string) error

CopyIndex writes a transactionally consistent copy of an existing index database to destination.

SQLite's VACUUM INTO is used rather than a filesystem copy because the source may be an index another Grafo process is writing: VACUUM INTO reads one snapshot under a read transaction, so the destination can never contain a torn page or a partially applied batch. It also rewrites the file without free pages, which matters because a long-lived branch index accumulates enough of them to carry hundreds of megabytes of reclaimable space.

destination must not already exist; SQLite refuses to overwrite it, and that refusal is deliberately not worked around so a publish can never clobber an index another worktree is using.

func ReplacementIndexPath added in v0.2.4 

func ReplacementIndexPath(path string) string

ReplacementIndexPath names the sibling a page size upgrade rewrites an index into. An interrupted upgrade can leave the file behind, so index lifecycle orchestration has to know about it as well.

func SetIndexMeta added in v0.2.0 

func SetIndexMeta(ctx context.Context, path string, values map[string]string) error

SetIndexMeta writes meta values into an existing index database without migrating it or granting graph write capabilities. Keys are applied in sorted order so a failure part way through leaves a reproducible state.

This is the narrow write counterpart to InspectIndex: it exists for callers that must correct an index's own description of itself, and it deliberately cannot reach any graph table.

Types

type CompactionResult 

type CompactionResult struct {
	Before StorageMetrics `json:"before"`
	After  StorageMetrics `json:"after"`
	Counts graph.Counts   `json:"counts"`
}

CompactionResult is the adapter-owned logical preservation evidence for one successful in-place VACUUM.

type IndexCompatibility 

type IndexCompatibility string

IndexCompatibility is the bounded compatibility state used by branch-index inventory. Inspection never migrates or otherwise repairs a database. 

const (
	CompatibilityCompatible   IndexCompatibility = "compatible"
	CompatibilityIncompatible IndexCompatibility = "incompatible"
	CompatibilityCorrupt      IndexCompatibility = "corrupt"
	CompatibilityUnverified   IndexCompatibility = "unverified"
)

type IndexInspection 

type IndexInspection struct {
	Metadata             IndexMetadata      `json:"metadata"`
	Metrics              *StorageMetrics    `json:"metrics,omitempty"`
	Compatibility        IndexCompatibility `json:"compatibility"`
	Diagnostic           string             `json:"diagnostic,omitempty"`
	CompactionDiagnostic string             `json:"compaction_diagnostic,omitempty"`
}

IndexInspection reports metadata and compatibility without granting graph query or write capabilities.

func InspectIndex 

func InspectIndex(ctx context.Context, path string) (IndexInspection, error)

InspectIndex opens an existing regular database in SQLite read-only mode and reports bounded evidence. Compatibility failures are data in the report; cancellation remains an operation error.

type IndexMetadata 

type IndexMetadata struct {
	Root         string `json:"root,omitempty"`
	RepositoryID string `json:"repository_id,omitempty"`
	Branch       string `json:"branch,omitempty"`
	Commit       string `json:"commit,omitempty"`
	IndexedAt    string `json:"indexed_at,omitempty"`
}

IndexMetadata is the identity and freshness evidence persisted only after a successful indexing pass.

type MaintenanceRepository 

type MaintenanceRepository interface {
	Compact(context.Context) (CompactionResult, error)
	Close() error
}

MaintenanceRepository is the narrow writable capability required by current index lifecycle orchestration.

func OpenMaintenance 

func OpenMaintenance(ctx context.Context, path string) (MaintenanceRepository, error)

OpenMaintenance opens an existing compatible index for bounded maintenance. It never creates the file, runs migrations, or changes compatibility metadata.

type MetadataEntry 

type MetadataEntry struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

MetadataEntry is one deterministic opaque metadata key/value pair.

type ReadRepository 

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

ReadRepository is the capability-safe SQLite adapter for existing indexes. It forwards only read methods from the shared adapter and therefore cannot satisfy graph.IndexRepository.

func OpenReadOnly 

func OpenReadOnly(ctx context.Context, path string) (*ReadRepository, error)

OpenReadOnly opens an existing, fully compatible index without creating, migrating, preparing writer statements, or mutating it.

func (*ReadRepository) CandidateNodes 

func (r *ReadRepository) CandidateNodes(ctx context.Context) ([]graph.Node, error)

func (*ReadRepository) CanonicalMessages 

func (r *ReadRepository) CanonicalMessages(ctx context.Context, request graph.CanonicalMessageQuery) (graph.CanonicalMessagePage, error)

func (*ReadRepository) Close 

func (r *ReadRepository) Close() error

func (*ReadRepository) Counts 

func (r *ReadRepository) Counts(ctx context.Context) (graph.Counts, error)

func (*ReadRepository) EdgesFrom 

func (r *ReadRepository) EdgesFrom(ctx context.Context, id string) ([]graph.Edge, error)

func (*ReadRepository) EdgesTo 

func (r *ReadRepository) EdgesTo(ctx context.Context, id string) ([]graph.Edge, error)

func (*ReadRepository) ExternalEdgesTo 

func (r *ReadRepository) ExternalEdgesTo(ctx context.Context, node graph.Node) ([]graph.Edge, error)

func (*ReadRepository) ExternalNodesMatching 

func (r *ReadRepository) ExternalNodesMatching(ctx context.Context, node graph.Node) ([]graph.Node, error)

func (*ReadRepository) ExternalRequestEdges 

func (r *ReadRepository) ExternalRequestEdges(ctx context.Context, after string, limit int) (graph.ExternalRequestEdgePage, error)

func (*ReadRepository) Files 

func (r *ReadRepository) Files(ctx context.Context) (map[string]graph.FileRecord, error)

func (*ReadRepository) ListNodesByKind 

func (r *ReadRepository) ListNodesByKind(ctx context.Context, request graph.NodeListQuery) ([]graph.ScopedNode, error)

func (*ReadRepository) MatchNodes 

func (r *ReadRepository) MatchNodes(ctx context.Context, request graph.NodeMatchQuery) (graph.NodeMatchGroup, error)

func (*ReadRepository) Meta 

func (r *ReadRepository) Meta(ctx context.Context, key string) (string, error)

func (*ReadRepository) Node 

func (r *ReadRepository) Node(ctx context.Context, id string) (graph.Node, error)

func (*ReadRepository) Path 

func (r *ReadRepository) Path() string

func (*ReadRepository) RelationEdges 

func (r *ReadRepository) RelationEdges(ctx context.Context, request graph.RelationEdgeQuery) (graph.RelationEdgePage, error)

func (*ReadRepository) Repositories 

func (r *ReadRepository) Repositories(ctx context.Context) ([]string, error)

func (*ReadRepository) SearchNodes 

func (r *ReadRepository) SearchNodes(ctx context.Context, term string, limit int) ([]graph.Node, error)

type Repository 

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

Repository is the SQLite adapter for graph.Repository.

func Open 

func Open(ctx context.Context, path string) (*Repository, error)

func (*Repository) BeginBulkLoad added in v0.2.2 

func (r *Repository) BeginBulkLoad(ctx context.Context) error

BeginBulkLoad drops the deferrable secondary indexes when the graph is empty, which is the only state in which the whole index is about to be written from nothing. A graph that already holds evidence is left exactly as it is, so the call is safe for any caller that cannot tell the difference.

func (*Repository) CandidateNodes 

func (r *Repository) CandidateNodes(ctx context.Context) ([]graph.Node, error)

func (*Repository) CanonicalMessages 

func (r *Repository) CanonicalMessages(ctx context.Context, request graph.CanonicalMessageQuery) (graph.CanonicalMessagePage, error)

CanonicalMessages enumerates authoritative protocol-message declarations. Filtering happens in SQLite before the deterministic order and bound, so unrelated type declarations cannot hide or truncate message coverage.

func (*Repository) Close 

func (r *Repository) Close() error

func (*Repository) Compact 

func (r *Repository) Compact(ctx context.Context) (CompactionResult, error)

Compact rewrites the index at TargetPageSize and proves compatibility, metadata, graph counts, integrity, and connection settings are unchanged. An index already at that page size is compacted by a strict in-place VACUUM.

func (*Repository) Counts 

func (r *Repository) Counts(ctx context.Context) (graph.Counts, error)

func (*Repository) EdgesFrom 

func (r *Repository) EdgesFrom(ctx context.Context, id string) ([]graph.Edge, error)

func (*Repository) EdgesTo 

func (r *Repository) EdgesTo(ctx context.Context, id string) ([]graph.Edge, error)

func (*Repository) EndBulkLoad added in v0.2.2 

func (r *Repository) EndBulkLoad(ctx context.Context) error

EndBulkLoad rebuilds everything BeginBulkLoad dropped and still holds. It is idempotent: reconciliation rebuilds in two steps of its own as it reaches the points where it needs each group, so by the end of a normal run there is usually nothing left to do here.

func (*Repository) ExternalEdgesTo 

func (r *Repository) ExternalEdgesTo(ctx context.Context, node graph.Node) ([]graph.Edge, error)

func (*Repository) ExternalNodesMatching 

func (r *Repository) ExternalNodesMatching(ctx context.Context, node graph.Node) ([]graph.Node, error)

func (*Repository) ExternalRequestEdges 

func (r *Repository) ExternalRequestEdges(ctx context.Context, after string, limit int) (graph.ExternalRequestEdgePage, error)

ExternalRequestEdges returns unresolved HTTP request boundaries in stable, bounded pages. Both endpoint and source nodes are hydrated by the same query so federation can build its reverse projection without N+1 adjacency loads.

func (*Repository) Files 

func (r *Repository) Files(ctx context.Context) (map[string]graph.FileRecord, error)

func (*Repository) ListNodesByKind 

func (r *Repository) ListNodesByKind(ctx context.Context, request graph.NodeListQuery) ([]graph.ScopedNode, error)

ListNodesByKind enumerates nodes of the requested kinds. It only enumerates: kind membership, name matching, and bounds are storage concerns, while usage direction and orphan classification stay in the query use cases.

func (*Repository) MatchNodes 

func (r *Repository) MatchNodes(ctx context.Context, request graph.NodeMatchQuery) (graph.NodeMatchGroup, error)

MatchNodes resolves a selector against the narrow, index-backed match queries in nodes.sql. Scopes are tried strongest first and the first one holding a case-sensitive match wins, so a substring match never competes with an exact name match, an unresolved boundary node never competes with a real declaration, and a case-insensitive-only hit at a strong level never outranks a case-sensitive match at a weaker one. A scope with only case-insensitive matches is kept as the fallback for selectors that match nothing case-sensitively. The count query runs before the row query so the reported totals cover the whole graph even when the row list is truncated.

func (*Repository) Meta 

func (r *Repository) Meta(ctx context.Context, key string) (string, error)

func (*Repository) Metadata 

func (r *Repository) Metadata(ctx context.Context) ([]MetadataEntry, error)

Metadata lists every metadata key deterministically with a defensive bound.

func (*Repository) Metrics 

func (r *Repository) Metrics(ctx context.Context) (StorageMetrics, error)

Metrics returns checked SQLite page and freelist metrics.

func (*Repository) Node 

func (r *Repository) Node(ctx context.Context, id string) (graph.Node, error)

func (*Repository) Path 

func (r *Repository) Path() string

func (*Repository) Reconcile 

func (r *Repository) Reconcile(ctx context.Context) error

func (*Repository) ReconcileWithStats 

func (r *Repository) ReconcileWithStats(ctx context.Context, observer graph.ReconciliationObserver) (graph.ReconciliationStats, error)

func (*Repository) ReconciliationPending 

func (r *Repository) ReconciliationPending(ctx context.Context) (bool, error)

ReconciliationPending reports whether any durable resolver queue contains work. The indexer uses this adapter-owned proof to skip reconciliation; it never reaches into SQLite-specific tables itself.

func (*Repository) RelationEdges 

func (r *Repository) RelationEdges(ctx context.Context, request graph.RelationEdgeQuery) (graph.RelationEdgePage, error)

RelationEdges loads at most Limit+1 rows for each exact relation and joins the node opposite the subject in the same query. Catalog callers therefore pay only for requested evidence and never perform per-edge node lookups.

func (*Repository) RemoveFiles 

func (r *Repository) RemoveFiles(ctx context.Context, paths []string) error

func (*Repository) ReplaceFile 

func (r *Repository) ReplaceFile(ctx context.Context, file graph.FileRecord, parsed graph.ParseResult) error

func (*Repository) ReplaceFiles added in v0.2.2 

func (r *Repository) ReplaceFiles(ctx context.Context, replacements []graph.FileReplacement) error

ReplaceFiles applies several file replacements in one transaction. A cold run replaces every file in the repository, and one transaction per file meant one commit, one WAL header, and one freshly prepared statement set per file.

func (*Repository) ReplaceOwner 

func (r *Repository) ReplaceOwner(ctx context.Context, owner string, parsed graph.ParseResult) error

func (*Repository) Repositories 

func (r *Repository) Repositories(ctx context.Context) ([]string, error)

Repositories reports the indexed repository this database stores, derived from the root recorded at index time.

func (*Repository) SearchNodes 

func (r *Repository) SearchNodes(ctx context.Context, term string, limit int) ([]graph.Node, error)

func (*Repository) SetMeta 

func (r *Repository) SetMeta(ctx context.Context, key, value string) error

func (*Repository) UpdateFileRecord added in v0.2.3 

func (r *Repository) UpdateFileRecord(ctx context.Context, file graph.FileRecord) error

UpdateFileRecord records a file's inputs without touching the evidence it already contributed. It exists for a file that was reparsed and produced the evidence the index already holds: the inputs that selected it did change and must be recorded, or the file is reselected and reparsed on every later run, while its rows and its reconciliation fan-out are left alone.

It deliberately does not call markOwnerDirty. The caller has established that this file's evidence is unchanged, so there is nothing for the reconciler to resolve on its behalf.

func (*Repository) WriteStats 

func (r *Repository) WriteStats() graph.WriteStats

type StorageMetrics 

type StorageMetrics struct {
	PageSize           int64   `json:"page_size"`
	PageCount          int64   `json:"page_count"`
	FreelistCount      int64   `json:"freelist_count"`
	LiveAllocatedBytes int64   `json:"live_allocated_bytes"`
	ReclaimableBytes   int64   `json:"reclaimable_bytes"`
	ReclaimablePercent float64 `json:"reclaimable_percent"`
}

StorageMetrics reports SQLite page allocation. ReclaimableBytes is an estimate based on freelist pages; WAL and SHM bytes are intentionally absent.

Source Files

View all Source files

Directories

Path Synopsis

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.