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 ¶
- func Open(dsn string, opts ...Option) (*entsql.Driver, error)
- type BackupDriver
- type Option
- func WithBackup(cfg replica.Config) Option
- func WithBusyTimeout(timeout time.Duration) Option
- func WithPoolSize(size int) Option
- func WithPragma(expr string) Option
- func WithRestoreOnMissing() Option
- func WithSQLiteOptions(opts ...sqlite.Option) Option
- func WithTxLock(mode TxLockMode) Option
- func WithWALLimit(bytes int64) Option
- type TxLockMode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Open ¶
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
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
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®ion=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
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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. |