knex_dart_sqlite 0.5.0
knex_dart_sqlite: ^0.5.0 copied to clipboard
SQLite driver for knex_dart — connect and execute queries against a SQLite database using the knex_dart query builder.
0.5.0 #
Two breaking changes, split out of the six fixes in 0.4.2 so those — all
non-breaking — reach everyone pinned at ^0.4.x without waiting on a
constraint bump. Under pub's 0.x rules a minor bump is not picked up by
^0.4.x, so bundling these would have withheld the OPFS data-loss fix and the
rest until each user widened their constraint by hand.
-
rawSql()/rawQuery()now reject more than one statement. SQLite compiles only the first statement of a string, sorawSql('CREATE TABLE a (...); CREATE TABLE b (...)')createda, discardedband reported success. Passing several statements throwsArgumentErrorrather than applying part of the input silently.A trailing semicolon on a single statement is still accepted. For several statements, call
rawSql()once per statement, or useexecuteSchema(), which already sends them one at a time — everyschemaBuilderoperation emits single statements, so schema code is unaffected. -
Web: the default
storageModeis nowindexedDb, notmemory. CallingKnexSQLite.connect(filename: 'app.db')on web with nowebStorageModereturned an in-memory database that looked persistent and discarded everything on close — the same silent non-persistence as the OPFS bug fixed in 0.4.2, reached by omission rather than by a broken path. A filename is a request for storage that outlives the page, so the default now persists.indexedDbrather thanauto, despiteautopreferring the faster OPFS backend:autofalls back on any OPFS failure, and OPFS holds exclusiveFileSystemSyncAccessHandles. A second connection to the same name while the first still holds them doesn't fail — it quietly lands on IndexedDB instead, so two connections read and write two different stores, each believing it has the database. That is the same class of silent divergence this release removes elsewhere, so it does not belong on the default path. IndexedDB persists and works on a page as well as in a worker, where OPFS requires a dedicated worker.Neither backend is safe for more than one connection to the same database name, and this release does not change that. OPFS at least enforces it: the second connection cannot take the handles. IndexedDB does not enforce it at all — its
xLockdelegates to a per-connection in-memory mirror (sqlite3'sindexed_db.dart), and the class documents that "no guarantees on durability can be made... file changes are written at some point after the database is changed". Two connections on one name therefore interleave asynchronous block write-back into a single store, which is corruption rather than divergence, and silent either way. Earlier wording here said IndexedDB "has no exclusive-handle contention, so one name always resolves to one store" — true, and precisely the hazard: one store, two uncoordinated writers.So treat a single writer per database name as a precondition of web persistence, not something the driver provides. Where several contexts need one database, elect a single owner (a Web Lock over a dedicated worker is the established pattern) and proxy to it; where they only need their own scratch space, give each its own name or use
memory.autoandopfsremain available explicitly. The explicitopfsmode never falls back, andautono longer falls back on contention either — see the next entry.:memory:still means in-memory, matching the native driver. PasswebStorageMode: 'memory'explicitly to keep the old behavior for a named database. -
Web:
automode no longer silently switches backends on an OPFS lock conflict. OPFS sync access handles are exclusive, andautocaught every OPFS failure before falling back, so a second connection to a database another connection already held did not fail — it succeeded on IndexedDB. A different store. Both sides then read and wrote their own copy of the database, each invisible to the other and to any later OPFS reopen, with nothing raised anywhere.autonow distinguishes "OPFS is unusable in this context" — which still falls back to IndexedDB, then memory, and is the common case on a page's main thread wherecreateSyncAccessHandleis worker-only — from "OPFS is held by someone else", which now propagates. The lock conflict is recognised by theNoModificationAllowedErrorthe File System standard requires when a lock cannot be taken; the wording was read off a real Chrome run rather than assumed, and a worker test holds one connection open and asserts the second raises instead of landing elsewhere.Two limitations worth knowing, neither removed by this change:
The thrown value arrives as an opaque
JSObject, so this is a match on a DOM error name in the message text, verified against Chrome. A browser that reports lock contention differently would still fall back and could still diverge.More importantly,
autoremains unsafe for a database shared between a page and a dedicated worker. A page cannot take an OPFS sync access handle at all — the API is worker-only — soautoon a page falls back to IndexedDB even while a worker holds the same name open in OPFS, leaving two stores and no error. That is not a lock conflict and cannot be detected as one; it follows fromautoresolving per execution context. UseindexedDbwhen a page and a worker share one database. -
Concurrent nested transactions failed with
no such savepoint. Only outermost scopes were serialized, so two nested transactions started together under one parent interleaved theirSAVEPOINT/RELEASEpairs — and because SQLite savepoints form a stack, releasing the outer one discarded the inner.db.trx((t) => Future.wait([t.trx(...), t.trx(...)]))threw.Nested transactions now queue behind their parent's previous child, which is how knex.js has always handled it (
Transaction._lastChild,lib/execution/transaction.js). Each scope keeps the tail of its own children's chain; a nested transaction awaits that tail and then becomes it, so siblings run in sequence. The chain they queue on swallows errors, so one rolled-back sibling does not stall the rest, while the future handed to the caller keeps its error — the same two-chain split knex.js uses.Chaining is per scope rather than per client, so independent transaction trees do not block each other, and a transaction started inside another's body queues against that transaction's children (a fresh chain) rather than the sibling chain it is itself part of. An earlier note here claimed serializing this risked deadlocking a nested transaction that awaits another; that was wrong — correct parentage is what prevents it, and the Zone supplies it.
-
New:
SQLiteClient.cachedStatementCount. Exposes how many prepared statements the native client currently caches, because the cache's bound is otherwise unobservable from outside — a test could only assert that results stay correct, which an unbounded cache does equally well. The web client reports0; it keeps no cache, and the two are exported under the same name, so their surfaces have to match.
0.4.2 #
Six bugs found by an adversarial review of this driver. All six failed silently — wrong results or a hung stream, never an error — and each is covered by a regression test confirmed to fail before the fix.
-
Web/OPFS: a named database never persisted anything. Opening with
webStorageMode: 'opfs'acceptedCREATE TABLEandINSERTwithout complaint and had lost everything by the next open. The driver passed the caller's filename as both the OPFS directory and the sqlite path, butSimpleOpfsFileSystempersists exactly two paths —/databaseand/database-journal— and itsxOpenfalls through to an in-memory overlay for any other path, so every write went to memory and was dropped on close. The sqlite path is now fixed at/database, chosen from the filesystem actually in use rather than from the requested mode, soautomode is covered whenever it selects OPFS. Databases stay separated by the OPFS directory, which is still keyed by name. (#35) -
WITH ... SELECTqueries returned no rows. The statement kind was guessed from the SQL text —startsWith('SELECT'),startsWith('PRAGMA'),contains('RETURNING')— and a CTE matches none of them, so it took the no-rows branch and returned[]for a query that had rows. Reachable from the typed builder, not just raw SQL:.withQuery(...)was affected. SQL led by a comment (/* ... */ SELECT) was misread the same way. The kind is no longer inferred from the text at all; every statement goes throughselect(), which returns whatever result columns the statement declares and applies DDL/DML side effects exactly as before. -
One client's transaction made another client think it was nested. The "already inside a transaction" marker was a
staticfield, so it was shared by every client instance. A top-leveltrx()on client B, called from inside client A's transaction, saw A's marker, skipped B's own serialization queue and issuedSAVEPOINT/RELEASEwithout ever having runBEGIN— failing withno such savepoint. The marker and the savepoint counter are now per-instance, matching the fix already made inknex_dart_postgres. -
watch()never ended when the database closed. Its subscription had noonDone, so the stream stayed open afterclose():await forover a watch stream never returned and the subscription was never released. Stream completion is now forwarded, and so are errors. -
streamQuery()leaked its statement when the stream was cancelled early, locking the table. The stream wasStream.fromIterableover async*generator; cancelling abandons that iterator without running the generator'sfinally, so the prepared statement was never closed and its cursor kept a read lock. A laterDROP TABLEon that table then failed withdatabase table is locked(SqliteException(6)). It is now anasync*generator, which is terminated on cancel and does runfinally. The web client already usedasync*and was never affected. -
The prepared-statement cache was unbounded. It is keyed by SQL text, so SQL assembled per request — an
INlist whose length varies, a predicate built from user input — produced a new key every time, and neither the map nor the native statements behind it ever stopped growing. Now capped at 128 entries, evicting least-recently-used and closing what it evicts.
0.4.1 #
- Bumped
sqlite3to^3.0.0andsqlite3_webto^0.9.0; replaced deprecated.dispose()calls with.close()in the native and web clients. - Bumped
lintsto^6.1.0andtestto^1.31.0.
0.4.0 #
- Added
watch()reactive query streams for SQLite based onUPDATE_HOOK. - Added web/WASM storage mode selection via
webStorageMode/storageModewithmemory,indexedDb,opfs, andautomodes. - Serialized concurrent top-level transactions across native and web clients.
- Buffered web SQLite update notifications through transaction boundaries to
match native
watch()semantics. - Added coverage for concurrent transactions, reactive query behavior, and native/web storage mode handling.
0.3.0 #
- Added
QueryInterceptorpipeline support: attach OTel, logging, or custom interceptors via theinterceptorsparameter onKnexSQLite.connect(). - Fixed
destroyPool()idempotency — double close no longer throws. - Fixed
StateErroron query after close with a clear message. - Improved exception propagation in transaction rollback using
Error.throwWithStackTraceto preserve original stack traces. - Fixed savepoint ID generation to use a per-instance counter instead of timestamp-based IDs, avoiding collisions under concurrent transactions.
0.2.1 #
- Reduced wrapper overhead by reusing compiled SQL through the interceptor pipeline instead of compiling the same query twice.
- Removed redundant async wrappers in low-level query dispatch while preserving
public
Futuresemantics and error propagation. - Optimized native SQLite row mapping by reading
ResultSetcolumn names and rows directly. - No query result shape, binding behavior, or SQL execution semantics changed.
0.2.0 #
- Added web/WASM SQLite support with conditional web client loading.
- Added async web client initialization and configurable WASM URL support via
connection['wasmUri'], including fallback URI behavior. - Added prepared statement caching in native SQLite client execution path.
- Added stream query support in native SQLite client.
- Updated dependencies for web/WASM compatibility (
sqlite3update,sqlite3_web, anduniversal_io).
0.1.1 #
- Updated dependency to
knex_dart: ^1.1.0. - Uses core
runInTransaction(...)migration transaction path with SQLite-safe behavior.
0.1.0 #
- Initial release.
- SQLite driver for
knex_dartusing thesqlite3package. KnexSQLite.connect()factory supporting file-based and in-memory databases.- Full query execution: select, insert, update, delete.
- Transaction support via
trx(). - Schema execution via
executeSchema().