README
¶
dalgo2sqlite
SQLite-specific DALgo driver. Wraps github.com/dal-go/dalgo2sql to provide the dal.DB surface, and adds SQLite-native implementations of:
dbschema.Adapter— schema introspection viasqlite_masterandpragma_table_infoddl.Applier— SQLite-flavoredCREATE TABLE/CREATE INDEX/DROP TABLEetc.dal.ConcurrencyAware— advertisesConcurrency() = 1for write paths (SQLite is single-writer)
Used by consumers (e.g. datatug-cli's db copy) that need schema-modification and concurrency hints through the unified DALgo abstraction without hand-rolling engine-specific SQL.
Our approach to development
We build with our own tooling:
- SpecScore — specify requirements as
SpecScore.mdartifacts - SpecStudio — author & manage specs across their lifecycle
- inGitDB — store structured data in Git where applicable
- DALgo — data access layer for Go
- cover100.dev — drive toward 100% test coverage
- DataTug — query & explore data
SQLite driver: modernc.org/sqlite (pure Go, CGO_ENABLED=0)
This package uses modernc.org/sqlite — a pure-Go transpilation of the
SQLite C library — instead of the former github.com/mattn/go-sqlite3 cgo
binding. The migration was done because:
- The cgo driver required a C toolchain in every build environment (CI, containers, cross-compilation targets).
- It prevented single static binaries for downstream consumers such as
datatug-cli. modernc.org/sqliteexposes the samedatabase/sqlinterface (driver name"sqlite"instead of"sqlite3"), sodalgo2sqlcontinues to work unchanged.- All existing SQLite features relied on here —
sqlite_masterintrospection,PRAGMAtable/index queries, transactional DDL — behave identically under the pure-Go driver.
The cgo_enabled: true flag can be removed from this repo's CI workflow and
from any downstream workflow that no longer needs cgo for other reasons.
Documentation
¶
Overview ¶
Package dalgo2sqlite is the SQLite-specific DALgo driver.
It composes github.com/dal-go/dalgo2sql for the dal.DB read/write surface (transactions, recordset reader, Get/Set/Insert/Delete) and adds SQLite-native implementations of:
- dbschema.SchemaReader for schema introspection via sqlite_master and PRAGMA queries
- ddl.SchemaModifier for SQLite-flavored CREATE / DROP / ALTER
- ddl.TransactionalDDL (always true — SQLite supports transactional DDL)
- dal.ConcurrencyAware returning false (SQLite serializes writers)
Index ¶
- Constants
- type Database
- func (d *Database) Adapter() dal.Adapter
- func (d *Database) AlterCollection(ctx context.Context, name string, ops ...ddl.AlterOp) error
- func (d *Database) Close() error
- func (d *Database) CreateCollection(ctx context.Context, c dbschema.CollectionDef, opts ...ddl.Option) error
- func (d *Database) Delete(ctx context.Context, key *dal.Key) error
- func (d *Database) DeleteMulti(ctx context.Context, keys []*dal.Key) error
- func (d *Database) DescribeCollection(ctx context.Context, ref *dal.CollectionRef) (*dbschema.CollectionDef, error)
- func (d *Database) DropCollection(ctx context.Context, name string, opts ...ddl.Option) error
- func (d *Database) ExecuteQueryToRecordsReader(ctx context.Context, query dal.Query) (dal.RecordsReader, error)
- func (d *Database) ExecuteQueryToRecordsetReader(ctx context.Context, query dal.Query, opts ...recordset.Option) (dal.RecordsetReader, error)
- func (d *Database) Exists(ctx context.Context, key *dal.Key) (bool, error)
- func (d *Database) Get(ctx context.Context, record dal.Record) error
- func (d *Database) GetMulti(ctx context.Context, records []dal.Record) error
- func (d *Database) ID() string
- func (d *Database) Insert(ctx context.Context, record dal.Record, opts ...dal.InsertOption) error
- func (d *Database) ListCollections(ctx context.Context, parent *dal.Key) ([]dal.CollectionRef, error)
- func (d *Database) ListConstraints(ctx context.Context, ref *dal.CollectionRef) ([]dbschema.ConstraintDef, error)
- func (d *Database) ListIndexes(ctx context.Context, ref *dal.CollectionRef) ([]dbschema.IndexDef, error)
- func (d *Database) ListReferrers(ctx context.Context, ref *dal.CollectionRef) ([]dbschema.Referrer, error)
- func (d *Database) RunReadonlyTransaction(ctx context.Context, f dal.ROTxWorker, opts ...dal.TransactionOption) error
- func (d *Database) RunReadwriteTransaction(ctx context.Context, f dal.RWTxWorker, opts ...dal.TransactionOption) error
- func (d *Database) Schema() dal.Schema
- func (d *Database) Set(ctx context.Context, record dal.Record) error
- func (d *Database) SetMulti(ctx context.Context, records []dal.Record) error
- func (d *Database) SupportsTransactionalDDL() bool
- func (d *Database) Update(ctx context.Context, key *dal.Key, updates []update.Update, ...) error
- func (d *Database) UpdateMulti(ctx context.Context, keys []*dal.Key, updates []update.Update, ...) error
- func (d *Database) UpdateRecord(ctx context.Context, record dal.Record, updates []update.Update, ...) error
- func (d *Database) Upsert(ctx context.Context, record dal.Record) error
Constants ¶
const Version = "0.1.0"
Version is the dalgo2sqlite package version. Updated by hand on each release; consumed by Adapter.Version().
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Database ¶
type Database struct {
dal.NoConcurrency // SupportsConcurrentConnections() = false
// contains filtered or unexported fields
}
Database is the dalgo2sqlite driver instance. It implements dal.DB by delegating to an inner dal.DB obtained from dalgo2sql.NewDatabase, and adds SQLite-specific dbschema, ddl, and concurrency surfaces.
Construct via NewDatabase. Database values are safe for concurrent use only insofar as SQLite itself is — readers can be concurrent under WAL mode; writers serialize.
func NewDatabase ¶
NewDatabase opens (or creates) the SQLite file at dbPath using modernc.org/sqlite (pure Go, CGO_ENABLED=0), pings to surface malformed-file errors at construction time, wraps the *sql.DB via dalgo2sql.NewDatabase for the dal.DB surface, and returns a *Database that satisfies dal.DB + dal.ConcurrencyAware.
Use NewDatabaseWithOptions when you need to supply per-collection primary-key metadata (required for Insert/Get/Delete with map[string]any data).
func NewDatabaseWithOptions ¶ added in v0.0.17
func NewDatabaseWithOptions(dbPath string, schema dal.Schema, opts dalgo2sql.DbOptions) (*Database, error)
NewDatabaseWithOptions is like NewDatabase but accepts a dal.Schema and dalgo2sql.DbOptions so callers can configure per-collection primary-key mappings required by Insert/Get/Delete operations.
Example — open a DB whose "widgets" table has "id" as its primary key:
db, err := dalgo2sqlite.NewDatabaseWithOptions(path, dal.NewSchema(nil, nil),
dalgo2sql.DbOptions{
Recordsets: map[string]*dalgo2sql.Recordset{
"widgets": dalgo2sql.NewRecordset("widgets", dalgo2sql.Table,
[]dal.FieldRef{dal.Field("id")}),
},
})
func (*Database) AlterCollection ¶
AlterCollection applies ops in order inside a single transaction. Partial failures roll back and leave the collection untouched.
func (*Database) Close ¶
Close closes the underlying *sql.DB. After Close the Database value is unusable; further method calls will fail with an error from database/sql.
func (*Database) CreateCollection ¶
func (d *Database) CreateCollection(ctx context.Context, c dbschema.CollectionDef, opts ...ddl.Option) error
CreateCollection creates a table and its inline indexes transactionally. On any error, the transaction rolls back and no schema state remains.
func (*Database) DeleteMulti ¶
func (*Database) DescribeCollection ¶
func (d *Database) DescribeCollection(ctx context.Context, ref *dal.CollectionRef) (*dbschema.CollectionDef, error)
DescribeCollection is implemented in T15.
func (*Database) DropCollection ¶
DropCollection drops the table; SQLite cascades to its indexes.
func (*Database) ExecuteQueryToRecordsReader ¶
func (*Database) ExecuteQueryToRecordsetReader ¶
func (*Database) ListCollections ¶
func (d *Database) ListCollections(ctx context.Context, parent *dal.Key) ([]dal.CollectionRef, error)
ListCollections returns the user-defined tables in alphabetical order. The parent *dal.Key is ignored — SQLite has no catalog/schema hierarchy.
func (*Database) ListConstraints ¶
func (d *Database) ListConstraints(ctx context.Context, ref *dal.CollectionRef) ([]dbschema.ConstraintDef, error)
ListConstraints returns a best-effort survey of constraints on the table:
- The primary-key constraint (one row if any PK columns exist)
- Foreign-key constraints from PRAGMA foreign_key_list
CHECK clauses and inline NOT NULL constraints are NOT enumerated (SQLite doesn't expose CHECK source portably). Callers read those from DescribeCollection.Fields.
func (*Database) ListIndexes ¶
func (d *Database) ListIndexes(ctx context.Context, ref *dal.CollectionRef) ([]dbschema.IndexDef, error)
ListIndexes is implemented in T16.
func (*Database) ListReferrers ¶
func (d *Database) ListReferrers(ctx context.Context, ref *dal.CollectionRef) ([]dbschema.Referrer, error)
ListReferrers performs an O(N) scan: for each other user-defined table, query PRAGMA foreign_key_list and check whether any row references ref.Name.
func (*Database) RunReadonlyTransaction ¶
func (d *Database) RunReadonlyTransaction(ctx context.Context, f dal.ROTxWorker, opts ...dal.TransactionOption) error
func (*Database) RunReadwriteTransaction ¶
func (d *Database) RunReadwriteTransaction(ctx context.Context, f dal.RWTxWorker, opts ...dal.TransactionOption) error
func (*Database) SupportsTransactionalDDL ¶
SupportsTransactionalDDL reports that SQLite supports transactional DDL — every CREATE / DROP / ALTER statement can be wrapped in a BEGIN/COMMIT and is rolled back atomically on commit failure.
func (*Database) UpdateMulti ¶
func (*Database) UpdateRecord ¶
func (d *Database) UpdateRecord(ctx context.Context, record dal.Record, updates []update.Update, preconditions ...dal.Precondition) error
UpdateRecord is not supported at the database level by dalgo2sql; use Update with an explicit key instead, or call UpdateRecord inside a RunReadwriteTransaction where the transaction object does support it.
Source Files