@bastani/atomic-storage-libsql 0.9.74-alpha.1 → 0.9.75-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,12 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.9.75-alpha.1] - 2026-11-10
6
+
7
+ ### Fixed
8
+
9
+ - A `file:` database no longer fails a write with `SQLITE_BUSY: database is locked` while other processes keep committing to the file. SQLite's busy handler polls for the lock with growing sleeps, so a writer behind others that took the lock in turn could miss every poll and fail after the 5-second busy timeout although the lock changed hands hundreds of times meanwhile. A statement outside a transaction, an `exec` of one statement such as a `CREATE TABLE IF NOT EXISTS`, a batch, or the start of a transaction that waited out the busy timeout now runs again, on new connections, as long as another connection committed during its wait; it fails only after a whole busy timeout in which nobody committed. Several statements in one `exec` do not run again.
10
+
5
11
  ## [0.9.72] - 2026-11-08
6
12
 
7
13
  ### Fixed
package/README.md CHANGED
@@ -35,7 +35,7 @@ chmod 600 ~/.atomic/turso-token
35
35
  | `authToken` | for remote databases | The database token. Pass it through `secrets` (`{ "file": ... }` or `{ "env": ... }`) so it stays out of settings. |
36
36
  | `namespace` | no | A self-hosted sqld namespace (`sqld --enable-namespaces`), sent as the `x-namespace` header. Needs a `libsql:`, `https:`, or `http:` URL. |
37
37
 
38
- A `file:` database is opened in write-ahead-log mode with a 5000 ms busy timeout, the way Atomic's own SQLite stores are, so several processes can read and write one file at once: a statement waits up to 5 seconds for a lock another process holds instead of failing with `SQLITE_BUSY`, and the wait blocks the calling thread. The first open changes the file to WAL mode, which is kept in the file and adds `-wal` and `-shm` files beside it. Open a file only through this adapter at a time: another SQLite library with the same file open in WAL mode was seen to read stale data.
38
+ A `file:` database is opened in write-ahead-log mode with a 5000 ms busy timeout, the way Atomic's own SQLite stores are, so several processes can read and write one file at once: a statement waits up to 5 seconds for a lock another process holds instead of failing with `SQLITE_BUSY`, and the wait blocks the calling thread. A statement outside a transaction, an `exec` of one statement, a batch, or the start of a transaction that waited out those 5 seconds runs again as long as another connection committed while it waited, so it fails only once a whole wait passes in which nobody committed. Several statements in one `exec` do not run again. The first open changes the file to WAL mode, which is kept in the file and adds `-wal` and `-shm` files beside it. Open a file only through this adapter at a time: another SQLite library with the same file open in WAL mode was seen to read stale data.
39
39
 
40
40
  The token is redacted from error messages and diagnostics. Add a `prefix` to the `storage` block to keep projects or teams apart in one database. See [Storage](../coding-agent/docs/storage.md) for selection precedence, per-process overrides, and the other storage options.
41
41
 
package/libsql.js CHANGED
@@ -79,16 +79,30 @@ function urlCredentials(url) {
79
79
  /**
80
80
  * @param {() => Promise<import("@libsql/client").Client | import("@libsql/client").Transaction>} connection
81
81
  * @param {<T>(operation: () => Promise<T>) => Promise<T>} watch
82
+ * @param {<T>(operation: () => Promise<T>) => Promise<T>} [single] runs one statement, which a failure may run again
82
83
  * @returns {import("@bastani/atomic/storage").SqliteDriverExecutor}
83
84
  */
84
- function statements(connection, watch) {
85
+ function statements(connection, watch, single = watch) {
85
86
  return {
86
87
  execute: (sql, params) =>
87
- watch(async () => driverResult(await (await connection()).execute({ sql, args: [...params] }))),
88
- executeMultiple: (sql) => watch(async () => (await connection()).executeMultiple(sql)),
88
+ single(async () => driverResult(await (await connection()).execute({ sql, args: [...params] }))),
89
+ // An `exec` of one statement wrote nothing when it fails, as one `execute` did; one of several statements may
90
+ // fail after the statements before it committed.
91
+ executeMultiple: (sql) =>
92
+ (isOneStatement(sql) ? single : watch)(async () => (await connection()).executeMultiple(sql)),
89
93
  };
90
94
  }
91
95
 
96
+ /**
97
+ * Whether `sql` is one statement: it has no `;` but at its end. A `;` in a literal or a comment also counts, so
98
+ * several statements are never taken for one.
99
+ * @param {string} sql
100
+ */
101
+ function isOneStatement(sql) {
102
+ const first = sql.indexOf(";");
103
+ return first === -1 || /^[\s;]*$/.test(sql.slice(first));
104
+ }
105
+
92
106
  /**
93
107
  * @param {import("@libsql/client").ResultSet} result
94
108
  * @returns {import("@bastani/atomic/storage").SqliteDriverResult}
@@ -104,6 +118,14 @@ function driverResult(result) {
104
118
  */
105
119
  const FILE_BUSY_TIMEOUT_MS = 5000;
106
120
 
121
+ /**
122
+ * Whether a driver call failed because another connection held a lock past the busy timeout.
123
+ * @param {unknown} error
124
+ */
125
+ function isBusy(error) {
126
+ return /** @type {{ readonly code?: unknown } | undefined} */ (error)?.code === "SQLITE_BUSY";
127
+ }
128
+
107
129
  /** V8's `gc`, taken from a context created while `--expose-gc` is set; the flag is off again for code that runs later. */
108
130
  function exposeGc() {
109
131
  setFlagsFromString("--expose-gc");
@@ -240,6 +262,35 @@ export async function openLibsqlDatabase({ url, authToken, namespace, headers })
240
262
  throw error;
241
263
  }
242
264
  };
265
+ // SQLite's busy handler polls for a lock with growing sleeps, so a writer behind others that take the lock in turn
266
+ // can miss every poll and fail after the busy timeout although the lock changed hands many times meanwhile. So a
267
+ // call that the busy timeout ended before it wrote anything runs again, on new connections, as long as another
268
+ // connection committed while it waited: it fails only after a whole busy timeout in which nobody committed, as
269
+ // Atomic's own SQLite stores fail only after their lock wait passes without a commit. `PRAGMA data_version`, read
270
+ // on a connection of its own, changes when another connection commits.
271
+ /** @type {import("@libsql/client").Client | undefined} */
272
+ let probe;
273
+ const dataVersion = async () => {
274
+ probe ??= create();
275
+ const version = (await probe.execute("PRAGMA data_version")).rows[0]?.data_version;
276
+ return typeof version === "bigint" || typeof version === "number" ? version : undefined;
277
+ };
278
+ /** @type {<T>(operation: () => Promise<T>) => Promise<T>} */
279
+ const waitForLock = async (operation) => {
280
+ /** @type {bigint | number | undefined} */
281
+ let version;
282
+ for (;;) {
283
+ try {
284
+ return await watch(operation);
285
+ } catch (error) {
286
+ if (!local || !isBusy(error)) throw error;
287
+ // The first wait's progress is unknown, so it runs again once whatever the version says.
288
+ const current = await dataVersion().catch(() => version);
289
+ if (current === undefined || current === version) throw error;
290
+ version = current;
291
+ }
292
+ }
293
+ };
243
294
  const connection = async () => {
244
295
  if (replace) {
245
296
  replace = false;
@@ -255,10 +306,14 @@ export async function openLibsqlDatabase({ url, authToken, namespace, headers })
255
306
  descriptor: { adapter: "libsql", location: url },
256
307
  redact: redactSecrets([authToken ?? "", ...urlCredentials(url), ...Object.values(headers ?? {})]),
257
308
  transientFailure,
258
- ...statements(connection, watch),
259
- // One request for the whole batch, in a write transaction: the journal sends a batch of appends this way.
309
+ // One statement outside a transaction, run alone or as an `exec` of one statement, that waited out the busy
310
+ // timeout wrote nothing and runs again. Several statements in one `exec` do not: the ones before the failed
311
+ // statement were committed.
312
+ ...statements(connection, watch, waitForLock),
313
+ // One request for the whole batch, in a write transaction: the journal sends a batch of appends this way. Only
314
+ // its `BEGIN IMMEDIATE` waits for the write lock, so a batch the busy timeout ended wrote nothing.
260
315
  batch: (batched) =>
261
- watch(async () => {
316
+ waitForLock(async () => {
262
317
  const results = await (await connection()).batch(
263
318
  batched.map(({ sql, params }) => ({ sql, args: [...params] })),
264
319
  "write",
@@ -266,7 +321,7 @@ export async function openLibsqlDatabase({ url, authToken, namespace, headers })
266
321
  return results.map(driverResult);
267
322
  }),
268
323
  async beginTransaction() {
269
- const transaction = await watch(async () => (await connection()).transaction("write"));
324
+ const transaction = await waitForLock(async () => (await connection()).transaction("write"));
270
325
  return {
271
326
  ...statements(async () => transaction, watch),
272
327
  commit: () => watch(() => transaction.commit()),
@@ -276,6 +331,7 @@ export async function openLibsqlDatabase({ url, authToken, namespace, headers })
276
331
  },
277
332
  async close() {
278
333
  client?.close();
334
+ probe?.close();
279
335
  if (local) await releaseClosedConnections();
280
336
  },
281
337
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bastani/atomic-storage-libsql",
3
- "version": "0.9.74-alpha.1",
3
+ "version": "0.9.75-alpha.1",
4
4
  "description": "libSQL / Turso storage adapter for Atomic sessions, workflow journals, and Intercom.",
5
5
  "contributors": [
6
6
  "Norin Lavaee",