enlite

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 12 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.0

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 · Upstream backup and restore

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.

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 Option

type Option func(*config) error

Option configures the database opened by Open.

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 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
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