Documentation
¶
Overview ¶
Package dbconn centralizes how every pasture component opens a modernc SQLite handle on the shared pasture.db file, and is the only place the database-open path splices a file path into a file: URI. (It is not the only file: URI in the tree: internal/acceptance/snapshot.go builds one too, but it does so through url.URL, which applies the same escaping itself.) Putting the connection-string contract in one leaf package (no pasture deps beyond errors) lets the audit trail, the task tracker, and the durable engine open the file with the identical WAL/concurrency configuration without an import cycle, while the read-only and default-mode callers get the same URI escaping.
Index ¶
- func NewSharedDBWithProfile(path string, profile timeouts.Profile) (*sql.DB, error)
- func OpenDefaultDB(path string) (*sql.DB, error)
- func OpenReadOnlyDB(path string) (*sql.DB, error)
- func OpenSharedDB(path string) (*sql.DB, error)
- func OpenSharedDBContextWithProfile(ctx context.Context, path string, profile timeouts.Profile) (*sql.DB, error)
- func OpenSharedDBWithProfile(path string, profile timeouts.Profile) (*sql.DB, error)
- func ReadOnlyDSN(path string) string
- func ReadOnlyDSNWithProfile(path string, profile timeouts.Profile) string
- func SharedDSN(path string) string
- func SharedDSNWithProfile(path string, profile timeouts.Profile) string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewSharedDBWithProfile ¶ added in v0.0.17
NewSharedDBWithProfile creates a lazy owned pool whose setup SQL receives the context of each acquisition. Callers run their own context-aware first SQL.
func OpenDefaultDB ¶ added in v0.0.9
OpenDefaultDB opens a modernc *sql.DB at path with SQLite's default create/journal behaviour — no mode parameter and none of the shared WAL/timeout pragmas — after normalising a leading run of slashes and escaping path's URI delimiters.
It is for the version probes and the dry-run preview in internal/handlers, and for the v3 backfill test in internal/audit. Those may run against a database that does not exist yet (the first open creates it, so a read-only handle would refuse a path that is merely new), and a dry run must leave an existing database byte-identical, which the shared profile's journal_mode(WAL) pragma would rewrite. Callers that want the production configuration should use OpenSharedDB; callers that know the file already exists and must not write it should use OpenReadOnlyDB.
func OpenReadOnlyDB ¶
OpenReadOnlyDB opens a modernc *sql.DB on path in read-only mode (mode=ro). Unlike OpenSharedDB, it never creates the file: if path does not exist the call fails immediately with a CategoryConnection error. The returned handle must not be used for any write or DDL operation.
func OpenSharedDB ¶
OpenSharedDB opens a modernc *sql.DB on path using SharedDSN. Unlike the pre-DBOS handles, it does NOT pin MaxOpenConns(1): the WAL multi-writer model (busy_timeout + _txlock=immediate) serializes writers at the file level, and the DBOS notification poller needs a second connection to make progress while a workflow step holds one.
func OpenSharedDBContextWithProfile ¶ added in v0.0.17
func OpenSharedDBContextWithProfile(ctx context.Context, path string, profile timeouts.Profile) (*sql.DB, error)
OpenSharedDBContextWithProfile eagerly verifies the same pool used by audit, unified tasks and the durable engine, and closes it on initialization failure.
func OpenSharedDBWithProfile ¶
func ReadOnlyDSN ¶
ReadOnlyDSN builds a connection string that opens the file without creating it and without modifying any data. mode=ro prevents any write and prevents file creation (SQLite returns SQLITE_CANTOPEN if the file does not exist).
busy_timeout mirrors the writer DSN's auto-retry. WAL readers normally don't block on writers, but they can receive SQLITE_BUSY during wal-index recovery or a checkpoint restart. The primary use case — reading status while the daemon is actively writing — demands the same retry window as the shared path; without it, those rare contention windows surface as raw lock errors instead of a transparent retry.
func ReadOnlyDSNWithProfile ¶
func SharedDSN ¶
SharedDSN builds the connection string used for every modernc handle on the unified pasture.db file. It encodes the concurrency contract as DSN params rather than runtime PRAGMAs so a caller-supplied handle (the one passed to DBOS as SQLiteSystemDB, which skips DBOS's own PRAGMA setup) is configured identically to the audit and provenance handles:
- journal_mode(WAL) multi-reader / single-writer without reader stalls
- busy_timeout(N) auto-retry a locked write for the caller's SQLite lock budget. N is profile.SQLiteBusy() in milliseconds, 500 ms in the production profile. A caller that creates more overlap than production passes a wider profile instead of changing this default.
- synchronous(NORMAL) durable under WAL without an fsync per commit
- foreign_keys(ON) enforce FK constraints (provenance relies on them)
- _txlock=immediate BEGIN IMMEDIATE so a write txn holds the lock from its first statement (migration concurrency-safety)
Types ¶
This section is empty.
Source Files