driver

Overview ¶

Binding parameters into SQL text, and rendering a driver.Value as a literal.

The connection and its lifecycle in the pool.

database/sql only knows about transactions started through BeginTx. A transaction started by Exec("BEGIN") is invisible to the pool, so ResetSession and Close roll back an abandoned one: otherwise the connection stays inside it and silently discards every later write.

Driver and connector: one sql.Open creates one connector, which lazily opens one server. Every physical connection from that *sql.DB shares it, so transactions and prepared statements are the only per-connection state.

Package driver provides a lightweight database/sql driver for tinySQL.

The driver exposes tinySQL through the standard `database/sql` API and supports both in-memory and file-backed databases. Key features:

• DSN formats: `mem://` and `file:/path/to/db.gob?options` (see `parseDSN`).
• Optional Write-Ahead Log (WAL) and autosave for durability.
• `mode=` selects any storage.StorageMode (disk, json, hybrid, wal, ...) via storage.OpenDB instead of the default GOB-snapshot behavior.
• Reader/writer pools and simple MVCC-style snapshots for transactions.
• Simple, safe placeholder binding: sequential `?` and numbered `$1`/`:1`.

Use `sql.Open("tinysql", dsn)` to create a connection. Each sql.Open call creates one Connector which owns one lazily opened server/storage.DB. The physical connections subsequently created by database/sql share that server, while transactions and prepared statements remain connection-local. Separate sql.Open calls never share a DSN-backed database instance implicitly.

See applyDSNOption and applyQueryOptions for available DSN options and defaults.

The DSN: what a connection string can say and how it is parsed. Unknown or malformed options are errors rather than silently ignored defaults, so a typo in a durability setting cannot quietly downgrade it.

Applying one DSN option, and the parsers for the value forms options use.

Executing statements on a connection, and the parsed-statement cache that avoids re-parsing repeated query text. Also the SQL-level transaction control (BEGIN/COMMIT/ROLLBACK issued as statements rather than through BeginTx).

Queries: turning a statement into driver.Rows.

Result rows handed back to database/sql, and the column metadata it can ask for.

The server: the one *storage.DB behind a sql.Open, the reader/writer gating that serialises access to it, and persistence.

persist reports failure and its callers propagate it. Acknowledging a write whose durable store rejected it loses data with no way for the caller to find out.

Prepared statements. A prepared query pre-parses its SQL once and rebinds only the parameter literals per execution, which is why the AST is reused under a pool rather than rebuilt.

Transactions. A transaction runs against a private shadow database and is merged into the live one at COMMIT: table changes through ApplyWALChanges, the catalog separately, both guarded by conflict detection against the state the transaction started from.