enlite

package module
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 18 Imported by: 0

README

Enlite

Enlite connects Ent to the cgo-free SQLite driver from liustack/sqlite. Use it with Ent's generated client, schema migrations, queries, and transactions. Ent · liustack/sqlite

Install

go get github.com/lib-x/enlite@v0.1.1

Requires Go 1.26.6 through Go 1.27.x. The upstream driver supports Linux and macOS on amd64 and arm64, and Windows on amd64. Builds work with CGO_ENABLED=0.

Quickstart

Pass the Enlite driver to ent.NewClient after generating your client. Ent getting-started guide

import (
    "context"

    "example.com/your-app/ent"
    "github.com/lib-x/enlite"
)

func openClient(ctx context.Context) (*ent.Client, error) {
    drv, err := enlite.Open("app.db")
    if err != nil {
        return nil, err
    }
    client := ent.NewClient(ent.Driver(drv))
    if err := client.Schema.Create(ctx); err != nil {
        client.Close()
        return nil, err
    }
    return client, nil // Call client.Close() when finished.
}

Open validates the DSN and options. Use drv.DB().PingContext(ctx) to check the connection before the first query. Foreign keys are enabled by default on every new connection. Run client.Schema.Create(ctx) before serving queries and serialize migrations that use the same generated Ent schema in one process.

Run the quickstart from this repository to create a user with Ent and query SQLite using the upstream regexp extension. Quickstart source

CGO_ENABLED=0 go run ./examples/quickstart
# Ada matches ^A: true

File database options

drv, err := enlite.Open("file:app.db?mode=rwc",
    enlite.WithPragma("journal_mode(WAL)"),
    enlite.WithPragma("synchronous(NORMAL)"),
    enlite.WithBusyTimeout(5*time.Second),
    enlite.WithTxLock(enlite.TxImmediate),
    enlite.WithWALLimit(32<<20),
    enlite.WithPoolSize(4),
    enlite.WithSQLiteOptions(regexp.Option()),
)
Option Behavior
WithPragma(expr) Runs a trusted SQL PRAGMA expression on each connection. PRAGMAs run in order, starting with foreign_keys(1), then the DSN's _pragma entries, then the supplied options.
WithBusyTimeout(duration) Sets the lock wait limit in whole milliseconds. The upstream default is five seconds. Zero disables waiting on locks.
WithTxLock(mode) Sets _txlock to TxDeferred, TxImmediate, or TxExclusive. With TxImmediate, a read-then-write transaction acquires the writer lock at BEGIN. Read-only transactions begin deferred.
WithWALLimit(bytes) Sets the size at which the upstream driver attempts to restart the WAL. The default is 64 MiB. Zero disables the size-based restart.
WithPoolSize(n) Caps open and idle connections at the same positive value. Idle connections keep their page caches. File databases use database/sql defaults when this option is omitted.
WithSQLiteOptions(opts...) Adds upstream sqlite.Option values to this connector, including functions, aggregates, collations, virtual tables, and extensions. Import github.com/liustack/sqlite/ext/regexp for regexp.Option().

WAL lets readers proceed while a writer holds the write lock. SQLite still serializes writes. With synchronous(NORMAL) in WAL mode, a power loss can roll back a recently committed transaction. Upstream group commit

Back up to S3

OpenWithBackup takes an S3 DSN with a local parameter for the writable SQLite file. Ent reads and writes the local file. The replica uploads committed changes to the S3 prefix. Run one replica per prefix.

drv, err := enlite.OpenWithBackup(ctx,
    "s3://my-bucket/enlite-demo?local=backup-demo.db&region=us-east-1",
    enlite.WithRestoreOnMissing(),
)

Use ent.NewClient(ent.Driver(drv)) as with Open. Closing the client closes SQLite first and then flushes and closes the replica. drv.SyncBackup(ctx) waits for commits to reach S3. drv.BackupStatus() reports staging and upload progress. The replica manages WAL and checkpoints and stages committed changes every second by default before uploading them asynchronously. Leave wal_autocheckpoint and journal_mode at the replica's settings.

Use a local path or file URI with WithBackup to supply the URL and configure the upstream replica. The same option can tune an S3 DSN by leaving URL empty.

drv, err := enlite.OpenWithBackup(ctx, "app.db", enlite.WithBackup(replica.Config{
    URL:          "s3://my-bucket/my-app?region=us-east-1",
    SyncInterval: 2 * time.Second,
    Retention:    7 * 24 * time.Hour,
}))

Use WithRestoreOnMissing when starting with a missing database and an existing backup prefix. It restores the latest backup before opening SQLite and skips restore when the local file already exists. An empty backup prefix allows a fresh database in create mode. To use a filename containing ?, encode it as %3F in a file: URI first. Encode the nested SQLite URI as the local parameter with url.Values.

Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the environment. Set AWS_SESSION_TOKEN as well if you use temporary credentials. Run the example with a database file and S3 prefix dedicated to the demo. It creates the Ent schema, inserts a demo user if needed, and calls SyncBackup to wait for the upload. S3 backup example

go run ./examples/s3backup \
    -dsn 's3://my-bucket/enlite-demo?local=backup-demo.db&region=us-east-1'

For Cloudflare R2, include endpoint=https://<account>.r2.cloudflarestorage.com&region=auto in the S3 DSN. Upstream backup and restore

For a manual restore, pass a replica.Config with the backup URL and credentials to replica.Restore. An empty RestoreOptions restores the latest backup to a new path. Set At for a point-in-time restore.

txid, err := replica.Restore(ctx, "restored.db", cfg, replica.RestoreOptions{})

In-memory databases

private, err := enlite.Open(":memory:")
shared, err := enlite.Open("file:/my-app?vfs=memdb", enlite.WithPoolSize(4))

Open uses one open and idle connection for a private in-memory database. A slash-prefixed vfs=memdb name lets connections share one in-memory database in the same process. Its contents disappear after the last connection closes. The upstream driver rejects cache=shared.

Use ent.Open("sqlite3", dsn)

For the same registration style, import the optional sqlite3 package and enable foreign keys in the DSN. entsqlite

import _ "github.com/lib-x/enlite/sqlite3"

// Inside a function with your generated ent package in scope.
client, err := ent.Open("sqlite3", "file:app.db?_pragma=foreign_keys(1)")

Only one driver can register sqlite3. Use enlite.Open when you need per-pool options or when the process already registers that name. The upstream liustack/sqlite package also registers sqlite, so it conflicts with modernc.org/sqlite and github.com/glebarez/go-sqlite in the same binary.

Development

go generate ./examples/quickstart/ent
CGO_ENABLED=0 go test ./...
go test -race ./...

The Ent schema and generated client are checked in so the quickstart also runs from a fresh checkout.

Documentation

Overview

Package enlite connects Ent's SQLite dialect to the cgo-free github.com/liustack/sqlite driver.

S3-compatible backups

OpenWithBackup opens a local SQLite file and backs it up to S3-compatible storage. Use an S3 URI with a local parameter or supply WithBackup for a local DSN. The replica manages WAL and checkpoints and uploads commits asynchronously. Closing the Ent client closes the pool and then the replica. BackupDriver.SyncBackup waits for committed changes to reach the store. For a manual restore to a new local file, use replica.Restore. See examples/s3backup for a complete program.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Open

func Open(dsn string, opts ...Option) (*entsql.Driver, error)

Open creates an Ent driver backed by liustack/sqlite. Pass it to a generated client with ent.NewClient(ent.Driver(drv)). Closing the client closes the underlying database/sql pool. Use drv.DB() to access that pool directly.

Open parses the DSN and validates options. SQLite opens the first connection on demand. Use drv.DB().PingContext to check that the database can be opened. Foreign keys are enabled on each new connection by default. DSN PRAGMAs run after that default, and option PRAGMAs run last, in the order supplied.

A private in-memory or temporary database uses one open and idle connection because each connection otherwise gets a separate database. For a pooled in-memory database, use a URI such as file:/app?vfs=memdb.

Types

type BackupDriver added in v0.1.1

type BackupDriver struct {
	*entsql.Driver
	// contains filtered or unexported fields
}

BackupDriver is an Ent SQLite driver with an active S3-compatible backup. Close it through the Ent client or directly when you finish using it.

func OpenWithBackup added in v0.1.1

func OpenWithBackup(ctx context.Context, dsn string, opts ...Option) (*BackupDriver, error)

OpenWithBackup starts a replica for a writable local SQLite file and returns an Ent driver. A DSN such as s3://bucket/prefix?local=app.db&region=us-east-1 sets both the local path and the backup address. A local path or file: DSN can also be used with WithBackup. The context covers startup and any restore. The replica manages WAL and checkpoints. Use one writer per remote backup prefix, and close the driver or its Ent client to flush and stop the replica.

func (*BackupDriver) BackupStatus added in v0.1.1

func (d *BackupDriver) BackupStatus() replica.Status

BackupStatus reports staging and upload progress, including upload errors.

func (*BackupDriver) Close added in v0.1.1

func (d *BackupDriver) Close() error

Close closes the SQLite pool first, then stops and flushes the backup. Repeated calls return the result of the first close.

func (*BackupDriver) SyncBackup added in v0.1.1

func (d *BackupDriver) SyncBackup(ctx context.Context) error

SyncBackup waits until the changes committed before the call are uploaded.

type Option

type Option func(*config) error

Option configures the database opened by Open.

func WithBackup added in v0.1.1

func WithBackup(cfg replica.Config) Option

WithBackup configures the replica used by OpenWithBackup. Set URL when the DSN is a local path or file: URI. With an S3 DSN, omit URL and use cfg to set options such as credentials, sync interval, retention or error reporting.

func WithBusyTimeout

func WithBusyTimeout(timeout time.Duration) Option

WithBusyTimeout sets PRAGMA busy_timeout, including the upstream writer queue's wait limit. The duration must be a whole number of milliseconds between zero and 2147483647. Zero disables waiting on locks.

func WithPoolSize

func WithPoolSize(size int) Option

WithPoolSize sets both the maximum open connections and maximum idle connections. Connections retain their page cache while idle. Size must be positive and must be one for a private in-memory or temporary database.

func WithPragma

func WithPragma(expr string) Option

WithPragma appends a SQLite PRAGMA expression, such as "journal_mode(WAL)". The upstream driver runs it on every physical connection. Use trusted SQL because the upstream driver evaluates this expression as SQL.

func WithRestoreOnMissing added in v0.1.1

func WithRestoreOnMissing() Option

WithRestoreOnMissing restores the latest backup before opening if the local database file is absent. An empty backup prefix allows a fresh database. An existing database file is opened as is.

func WithSQLiteOptions

func WithSQLiteOptions(opts ...sqlite.Option) Option

WithSQLiteOptions passes upstream options to the connector for this pool. Use it to install SQL functions, collations, virtual tables or extensions such as regexp and uuid on every connection. Callbacks can run concurrently on different connections.

func WithTxLock

func WithTxLock(mode TxLockMode) Option

WithTxLock sets liustack/sqlite's _txlock, overriding the DSN value. Read-only transactions always begin deferred.

func WithWALLimit

func WithWALLimit(bytes int64) Option

WithWALLimit sets liustack/sqlite's _wal_limit in bytes, overriding the DSN value. Above this threshold the driver tries to restart the WAL. Zero turns off this size-based restart. It takes effect only in WAL mode.

type TxLockMode

type TxLockMode string

TxLockMode controls how SQLite begins write transactions.

const (
	// TxDeferred waits until the first write before acquiring a write lock.
	TxDeferred TxLockMode = "deferred"
	// TxImmediate acquires the write lock at BEGIN.
	TxImmediate TxLockMode = "immediate"
	// TxExclusive acquires the write lock at BEGIN and blocks readers outside WAL mode.
	TxExclusive TxLockMode = "exclusive"
)

Directories

Path Synopsis
examples
quickstart command
s3backup command
Package sqlite3 registers liustack/sqlite under the name Ent uses for the SQLite dialect.
Package sqlite3 registers liustack/sqlite under the name Ent uses for the SQLite dialect.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL