Commit cfb97341 authored by cznic's avatar cznic
Browse files

CHANGELOG.md: document the DSN validation-order change 

Adds a v1.55.0 entry for validating every DSN parameter before applying any
of them. It gets its own bullet rather than folding into the !134 paragraph
because it changes behavior for parameters that have shipped for years -
_txlock, _timezone, _time_format, _time_integer_format, _inttotime and
_texttotime - so it concerns readers who never touch the new mattn-compatible
keys.

The alias-selection fix is folded into the !134 paragraph instead. v1.55.0 is
not tagged, so no release ever shipped the fallback behavior and describing it
as a fix would document a bug nobody could have hit.

Also corrects that paragraph's closing claim that "all other existing
parameters are unchanged", which the validation-order change made false: those
parameters are affected in when they are validated, though not in what they
accept or what they mean.

Co-Authored-By: default avatarClaude Opus 4.8 <noreply@anthropic.com>
parent 0895392f

CHANGELOG.md

+2 −1
Original line number Diff line number Diff line 
# Changelog



 - 2026-07-20 v1.55.0:

     - Add `github.com/mattn/go-sqlite3`-compatible shorthand DSN query parameters to ease migration from that driver: `_busy_timeout`/`_timeout`, `_foreign_keys`/`_fk`, `_journal_mode`/`_journal`, `_synchronous`/`_sync`, `_auto_vacuum`/`_vacuum`, and `_query_only`, each setting the correspondingly named PRAGMA. Values are validated against the same set `mattn/go-sqlite3` accepts (case-insensitive) and an unrecognized value fails the connection with an error, so a typo such as `_synchronous=fu1l` or `_foreign_keys=yes_please` is reported rather than silently downgrading durability or dropping foreign-key enforcement. The keys are applied in a fixed order independent of their order in the DSN — `_busy_timeout` and `_auto_vacuum` before any `_pragma` values (`auto_vacuum` must be set before the database is first written), the rest after, and `_query_only` last — and where a key and its alias are both supplied the alias wins, matching `mattn/go-sqlite3`. Behavior change to note: prior releases ignored these keys entirely, so a DSN carried over from a `mattn/go-sqlite3` setup changes in two ways. A recognized key that previously did nothing now takes effect — `_foreign_keys=on` begins enforcing constraints against data that may already violate them, `_journal_mode=wal` persistently converts the database file, and `_query_only=1` makes the connection read-only. And a value outside the accepted set now fails the connection with an error where the same DSN previously opened successfully — for example a duration-style `_busy_timeout=5s` or `_timeout=5000ms`, neither of which is the integer that key requires. Review such DSNs before upgrading. `_pragma` and all other existing parameters are unchanged.

     - Add `github.com/mattn/go-sqlite3`-compatible shorthand DSN query parameters to ease migration from that driver: `_busy_timeout`/`_timeout`, `_foreign_keys`/`_fk`, `_journal_mode`/`_journal`, `_synchronous`/`_sync`, `_auto_vacuum`/`_vacuum`, and `_query_only`, each setting the correspondingly named PRAGMA. Values are validated against the same set `mattn/go-sqlite3` accepts (case-insensitive) and an unrecognized value fails the connection with an error, so a typo such as `_synchronous=fu1l` or `_foreign_keys=yes_please` is reported rather than silently downgrading durability or dropping foreign-key enforcement. The keys are applied in a fixed order independent of their order in the DSN — `_busy_timeout` and `_auto_vacuum` before any `_pragma` values (`auto_vacuum` must be set before the database is first written), the rest after, and `_query_only` last — and where a key and its alias are both supplied the alias wins, matching `mattn/go-sqlite3`; selection is by presence rather than by value, so supplying the alias empty (`_foreign_keys=on&_fk=`) suppresses the PRAGMA rather than deferring to the primary key, again matching that driver. Behavior change to note: prior releases ignored these keys entirely, so a DSN carried over from a `mattn/go-sqlite3` setup changes in two ways. A recognized key that previously did nothing now takes effect — `_foreign_keys=on` begins enforcing constraints against data that may already violate them, `_journal_mode=wal` persistently converts the database file, and `_query_only=1` makes the connection read-only. And a value outside the accepted set now fails the connection with an error where the same DSN previously opened successfully — for example a duration-style `_busy_timeout=5s` or `_timeout=5000ms`, neither of which is the integer that key requires. Review such DSNs before upgrading. `_pragma` is unchanged and no pre-existing parameter changes meaning, though see the following entry for a change in when all of them are validated.

     - See [GitLab merge request #134](https://gitlab.com/cznic/sqlite/-/merge_requests/134), thanks Toni Spets (@beeper-hifi) and Ian Chechin!

     - Validate every DSN query parameter before applying any of them. Parameters were previously checked as each was reached, so a DSN whose later parameter was rejected had already executed the PRAGMAs ahead of it. Because `PRAGMA journal_mode` and `PRAGMA auto_vacuum` are persistent changes to the database file, a DSN such as `file:x.db?_journal_mode=wal&_synchronous=bogus` failed the connection and yet left `x.db` converted to WAL. A failed `Open` now leaves the database as it found it. This covers the pre-existing `_txlock`, `_timezone`, `_time_format`, `_time_integer_format`, `_inttotime` and `_texttotime` parameters as well as the shorthand keys above: all of them were validated only after the `_pragma` list had already run, so the same DSN shape — a valid `_pragma=journal_mode=wal` alongside a misspelled `_txlock` — converted the file before reporting the error. Only the values accepted for each parameter are unchanged; a DSN that opened successfully before still opens, and one that failed still fails with the same error. `_pragma` remains the sole exception, since its values are executed verbatim and cannot be checked in advance: a malformed `_pragma` is still rejected by SQLite as it runs, after any earlier `_pragma` in the list has taken effect.



 - 2026-07-15 v1.54.0:

     - Upgrade to [SQLite 3.53.3](https://sqlite.org/releaselog/3_53_3.html). This also bumps the pinned `modernc.org/libc` to v1.74.1; as always, downstream modules must pin the exact same `modernc.org/libc` version this module's `go.mod` pins (see [GitLab issue #177](https://gitlab.com/cznic/sqlite/-/issues/177)).