database

package
v1.33.0 Latest Latest
Warning

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

Go to latest
Published: Sep 25, 2026 License: BSD-3-Clause Imports: 12 Imported by: 0

Documentation

Overview

Package database provides SQLite database setup for the ent ORM client. Uses modernc.org/sqlite (CGo-free) with WAL mode and FK constraints.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Open

func Open(dbPath string, traceSQL bool) (*ent.Client, *sql.DB, error)

Open creates an ent client connected to the SQLite database at dbPath. The database is configured with WAL journal mode, foreign key enforcement, a 5-second busy timeout, and bulk-write-tuned pragmas. It returns both the ent client and the underlying *sql.DB for raw SQL operations (e.g., sync_status table).

DSN pragma rationale:

  • synchronous(NORMAL): safe under LiteFS-replicated WAL — LiteFS provides durability via streaming replication so per-commit local fsync is redundant overhead. Halves the per-commit syscall cost on the bulk- upsert tx; the Fly primary's local WAL is replayed on replicas regardless of the local fsync mode.
  • cache_size(-8000): 8 MB page cache PER CONNECTION (negative value = KiB; SQLite's default is ~2 MB). The page cache multiplies by the pool: with MaxOpenConns=10 the worst case is 10 x cache_size, and MaxIdleConns=5 retains up to 5 x cache_size for ConnMaxLifetime after a read burst. The earlier -32000 (32 MB) was sized for the primary's single-connection bulk-upsert burst but capped at 320 MB pooled — more than an entire 256 MB replica VM serving the read-heavy full-dump traffic that actually fills caches. 8 MB bounds the pool at 80 MB worst-case while still quadrupling the default for the upsert tx's page reuse.
  • temp_store(MEMORY): keeps sorter and temp tables in RAM. modernc.org/ sqlite's default is FILE which on Fly hits the rootfs overlay (NOT tmpfs — verified via /proc/mounts).

When traceSQL is true the underlying *sql.DB is opened through XSAM/otelsql, so every query — ent's and the raw sync_status statements that share this handle — emits an OpenTelemetry span beneath the active request span. Controlled by PDBPLUS_OTEL_SQL (default on; set false to disable). Span volume is bounded by the trace sampler: a DB span follows the decision of its parent span. A sync cycle emits no DB spans (see pdbotel.WithoutDBSpans). The low-signal sql.rows and sql.conn.reset_session span types are suppressed (see otelOptions): they roughly halve the span count per request trace and remove the orphan single-span traces that pool-lifecycle and boot-time schema-migration DB operations otherwise emit with no request root. The DataVersionProbe query emits no span either (see keepQuerySpan).

Types

type DataVersionProbe added in v1.28.3

type DataVersionProbe struct {
	// contains filtered or unexported fields
}

DataVersionProbe reports a key that changes each time another connection commits a change to the database. It is the change signal for nodes that run without LiteFS, where no "-pos" file exists.

SQLite's PRAGMA data_version is a property of one connection: its value changes when a different connection commits, and it ignores commits made through the same connection. The probe therefore pins one connection from the pool and runs only the pragma on it. It never writes, so every commit in the process or in another process shows up as a change.

The pinned connection holds 1 of the pool's 10 slots for the life of the probe. database/sql does not close a held connection when ConnMaxLifetime passes, so the pin stays stable. When a query fails, the probe releases the connection and pins a new one on the next call; the key then includes a new epoch, because data_version values from two connections cannot be compared.

A caller polls the probe outside any request, so on a traced handle each query would start its own root trace. Open's span filter drops the span of the probe query; otelsql still records the query in its metrics.

A DataVersionProbe is not safe for concurrent use. Call Version and Close from one goroutine.

func NewDataVersionProbe added in v1.28.3

func NewDataVersionProbe(db *sql.DB) *DataVersionProbe

NewDataVersionProbe returns a probe for db. It pins no connection until the first call to Version.

func (*DataVersionProbe) Close added in v1.28.3

func (p *DataVersionProbe) Close() error

Close releases the pinned connection. A later call to Version pins a new connection and returns a key that differs from every earlier key.

func (*DataVersionProbe) Version added in v1.28.3

func (p *DataVersionProbe) Version(ctx context.Context) (string, error)

Version returns the current change key. Two calls return the same key only if no other connection committed a change between them. The boot time and the epoch keep keys unique across restarts and re-pins.

Jump to

Keyboard shortcuts

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