Documentation
¶
Overview ¶
Package dataset implements txco://dataset: stack-bundled, immutable SQLite artifacts queried at runtime through named, apply-time-validated queries. A stack ships a pair of files under the reserved DATASETS/ subtree:
DATASETS/<name>.sqlite the artifact — content-addressed in filecas,
fingerprint-only in stack_files (never inline)
DATASETS/<name>.yaml the manifest — the named queries the runtime
may execute against that artifact
This file (paths.go) is the leaf layer: just the reserved-path vocabulary, with no dependency on SQLite or the stores. It is imported by the CLI (to collect the pair into the bundle), the admin producer (to CAS-back artifact bytes like FILES/), and the control-event applier (to keep artifact bytes out of the in-memory runtime DB).
Index ¶
- Constants
- func DSN(path string) string
- func IntegrityCheck(path string) error
- func IsArtifactPath(p string) bool
- func IsDatasetPath(p string) bool
- func IsManifestPath(p string) bool
- func Name(p string) string
- func ValidateArtifact(ctx context.Context, path string, m *Manifest) error
- type Cache
- type Manifest
- type Query
Constants ¶
const ( Dir = "DATASETS" ArtifactExt = ".sqlite" ManifestExt = ".yaml" )
Reserved top-level directory (sibling to FILES/, VECTORS/, KV/) and the two member extensions. The pairing is strict: an artifact without a manifest (or vice versa) is a deploy error, not a warning — see Validate.
const DriverName = "sqlite3_dataset"
DriverName is the database/sql driver datasets open through.
Variables ¶
This section is empty.
Functions ¶
func DSN ¶
DSN renders the canonical read-only immutable connection string for a materialised artifact file. immutable=1 promises SQLite the file cannot change (true: it is content-addressed), which drops all locking and journal handling; query_only is belt over the authorizer's braces.
func IntegrityCheck ¶
IntegrityCheck opens the SQLite file at path read-only and runs the full `PRAGMA integrity_check`. Slow on multi-GB artifacts by design — callers run it once per new artifact (the CLI before first upload), not per deploy. A non-SQLite file fails here with "file is not a database".
The plain sqlite3 driver would work too, but going through the dataset driver keeps every dataset file open in this codebase on the same restricted path.
func IsArtifactPath ¶
IsArtifactPath reports whether p is a dataset artifact ("DATASETS/<name>.sqlite").
func IsDatasetPath ¶
IsDatasetPath reports whether a stack_files path lives under DATASETS/. Used by the producer / applier to give artifacts the same CAS-backed, out-of-runtime-DB treatment as FILES/ static assets.
func IsManifestPath ¶
IsManifestPath reports whether p is a dataset manifest ("DATASETS/<name>.yaml").
func Name ¶
Name returns the dataset name a member path belongs to: "DATASETS/books.sqlite" → "books", "DATASETS/books.yaml" → "books". It returns "" when the path is not under DATASETS/, is nested (no slashes allowed in the name), or has neither member extension — the same shape validateStackFilePath enforces at upload.
func ValidateArtifact ¶
ValidateArtifact opens the artifact at path and prepares every query the manifest declares. This is the activation gate: it proves the SQL compiles against the ACTUAL shipped schema (missing tables/columns fail here, before the version goes live) and — because preparation runs under the read-only authorizer — that no declared query is anything but a read. Returns the first failure, named for the deploy error.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache materialises + opens dataset artifacts by content hash.
func NewCache ¶
NewCache returns a Cache rooted at dir (created if absent), resolving misses from fcas. maxBytes bounds the materialised tier; zero-copy opens are free.
func (*Cache) Close ¶
func (c *Cache) Close()
Close closes every open handle (shutdown path). Materialised files stay on disk for the next boot.
func (*Cache) Handle ¶
Handle returns the shared read-only DB for the artifact with the given content hash, materialising it from the CAS on first use. filecas.ErrNotFound propagates when the blob isn't in the store.
func (*Cache) LocalPath ¶
LocalPath resolves the artifact to a readable local file — the CAS blob itself when the backend is local (zero-copy), else the materialised cache copy, fetched on first use. Exposed for apply-time validation, which opens its own short-lived handle rather than warming the shared one.
type Manifest ¶
Manifest is the author-declared query surface of one dataset — the ONLY SQL the runtime will ever execute against the artifact. Parsed strictly: an unknown key is a deploy error, not a silent ignore, so a typo'd `querys:` can't ship a dataset with no queries.
queries:
lookup_title:
sql: |
SELECT title, author FROM books_fts WHERE books_fts MATCH ? LIMIT 10
lookup_isbn:
sql: SELECT * FROM books WHERE isbn13 = ? LIMIT 1
max_rows: 1
func ParseManifest ¶
ParseManifest strictly decodes + validates a DATASETS/<name>.yaml body.
func (*Manifest) QueryNames ¶
QueryNames returns the declared names, sorted — for error hints ("unknown query X, have [a b c]") and deterministic validation order.
Source Files