@bastani/atomic-storage-libsql 0.9.71 → 0.9.72
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 +18 -0
- package/libsql.js +154 -23
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,24 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.9.72] - 2026-11-08
|
|
6
|
+
|
|
7
|
+
### Fixed
|
|
8
|
+
|
|
9
|
+
- A `file:` database stays usable after a statement fails. A statement that gave up part way, for example a write that waited out the busy timeout while another process held the lock, stayed active on its connection until garbage collection. After that, every transaction on the database failed with `SQLITE_BUSY: cannot commit transaction - SQL statements in progress`, and a write outside a transaction reported success but was never committed. The adapter now replaces its local connections after any failed statement, before the next call, and turns foreign keys on again on the new one.
|
|
10
|
+
- Closing a `file:` database now releases its files before `close()` resolves, so they can be deleted or moved right away, including on Windows. libsql 0.5 keeps a closed connection open until its statements are garbage-collected; the adapter now runs two full garbage collections, shared by closes that arrive together, and waits for the driver to release its handles ([#4433](https://github.com/bastani-inc/atomic/issues/4433))
|
|
11
|
+
- When opening a database fails and closing it afterwards fails too, the close failure is attached to the open error as `cleanupCause` instead of being discarded ([#4433](https://github.com/bastani-inc/atomic/issues/4433))
|
|
12
|
+
- A remote database no longer fails a write because the process stalled in the middle of it. When a process was stopped (by a signal, starved of CPU, or asleep) longer than the server keeps an idle stream, its next statement failed with `STREAM_EXPIRED` and the write was lost to a `StorageUnavailableError`. The adapter now recognizes an expired stream, a transaction the server timed out, a refused connection and a broken connection by their codes and reports them as `StorageTransientError`; a statement, batch, or workflow journal or session write that they ended before it wrote anything runs again, up to five times over about four seconds. A write whose connection broke after the server may have applied it is not sent again and fails with `outcome: "unknown"` ([#4383](https://github.com/bastani-inc/atomic/issues/4383))
|
|
13
|
+
|
|
14
|
+
## [0.9.72-alpha.1] - 2026-11-08
|
|
15
|
+
|
|
16
|
+
### Fixed
|
|
17
|
+
|
|
18
|
+
- A `file:` database stays usable after a statement fails. A statement that gave up part way, for example a write that waited out the busy timeout while another process held the lock, stayed active on its connection until garbage collection. After that, every transaction on the database failed with `SQLITE_BUSY: cannot commit transaction - SQL statements in progress`, and a write outside a transaction reported success but was never committed. The adapter now replaces its local connections after any failed statement, before the next call, and turns foreign keys on again on the new one.
|
|
19
|
+
- Closing a `file:` database now releases its files before `close()` resolves, so they can be deleted or moved right away, including on Windows. libsql 0.5 keeps a closed connection open until its statements are garbage-collected; the adapter now runs two full garbage collections, shared by closes that arrive together, and waits for the driver to release its handles ([#4433](https://github.com/bastani-inc/atomic/issues/4433))
|
|
20
|
+
- When opening a database fails and closing it afterwards fails too, the close failure is attached to the open error as `cleanupCause` instead of being discarded ([#4433](https://github.com/bastani-inc/atomic/issues/4433))
|
|
21
|
+
- A remote database no longer fails a write because the process stalled in the middle of it. When a process was stopped (by a signal, starved of CPU, or asleep) longer than the server keeps an idle stream, its next statement failed with `STREAM_EXPIRED` and the write was lost to a `StorageUnavailableError`. The adapter now recognizes an expired stream, a transaction the server timed out, a refused connection and a broken connection by their codes and reports them as `StorageTransientError`; a statement, batch, or workflow journal or session write that they ended before it wrote anything runs again, up to five times over about four seconds. A write whose connection broke after the server may have applied it is not sent again and fails with `outcome: "unknown"` ([#4383](https://github.com/bastani-inc/atomic/issues/4383))
|
|
22
|
+
|
|
5
23
|
## [0.9.71] - 2026-11-03
|
|
6
24
|
|
|
7
25
|
### Fixed
|
package/libsql.js
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
// @ts-check
|
|
2
|
+
import { setFlagsFromString } from "node:v8";
|
|
3
|
+
import { runInNewContext } from "node:vm";
|
|
2
4
|
import { createSqliteDatabase, redactSecrets, StorageAdapterLoadError, switchToWriteAheadLog } from "@bastani/atomic/storage";
|
|
3
5
|
|
|
4
6
|
/**
|
|
@@ -75,15 +77,15 @@ function urlCredentials(url) {
|
|
|
75
77
|
}
|
|
76
78
|
|
|
77
79
|
/**
|
|
78
|
-
* @param {() => import("@libsql/client").Client | import("@libsql/client").Transaction} connection
|
|
80
|
+
* @param {() => Promise<import("@libsql/client").Client | import("@libsql/client").Transaction>} connection
|
|
81
|
+
* @param {<T>(operation: () => Promise<T>) => Promise<T>} watch
|
|
79
82
|
* @returns {import("@bastani/atomic/storage").SqliteDriverExecutor}
|
|
80
83
|
*/
|
|
81
|
-
function statements(connection) {
|
|
84
|
+
function statements(connection, watch) {
|
|
82
85
|
return {
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
executeMultiple: (sql) => connection().executeMultiple(sql),
|
|
86
|
+
execute: (sql, params) =>
|
|
87
|
+
watch(async () => driverResult(await (await connection()).execute({ sql, args: [...params] }))),
|
|
88
|
+
executeMultiple: (sql) => watch(async () => (await connection()).executeMultiple(sql)),
|
|
87
89
|
};
|
|
88
90
|
}
|
|
89
91
|
|
|
@@ -102,6 +104,100 @@ function driverResult(result) {
|
|
|
102
104
|
*/
|
|
103
105
|
const FILE_BUSY_TIMEOUT_MS = 5000;
|
|
104
106
|
|
|
107
|
+
/** V8's `gc`, taken from a context created while `--expose-gc` is set; the flag is off again for code that runs later. */
|
|
108
|
+
function exposeGc() {
|
|
109
|
+
setFlagsFromString("--expose-gc");
|
|
110
|
+
try {
|
|
111
|
+
return /** @type {() => void} */ (runInNewContext("gc"));
|
|
112
|
+
} finally {
|
|
113
|
+
setFlagsFromString("--no-expose-gc");
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
function collectGarbage() {
|
|
118
|
+
if (globalThis.gc) globalThis.gc();
|
|
119
|
+
else if (typeof Bun !== "undefined") Bun.gc(true);
|
|
120
|
+
else exposeGc()();
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Consecutive full collections one close runs. One forced collection occasionally leaves a statement uncollected, about
|
|
125
|
+
* once in several thousand closes in a loop that opens, uses and closes a file database, and a further event-loop turn
|
|
126
|
+
* does not collect it; a second collection does.
|
|
127
|
+
*/
|
|
128
|
+
const COLLECTION_PASSES = 2;
|
|
129
|
+
|
|
130
|
+
/** @type {Promise<void>} */
|
|
131
|
+
let collection = Promise.resolve();
|
|
132
|
+
/** @type {Promise<void> | undefined} */
|
|
133
|
+
let pendingCollection;
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* libsql 0.5 finalizes a statement only when the statement is garbage-collected, and a connection stays open until
|
|
137
|
+
* its last statement is finalized, so the client's `close()` leaves a `file:` database's files open and Windows
|
|
138
|
+
* refuses to delete them. This resolves after `COLLECTION_PASSES` full collections that started after the call, each
|
|
139
|
+
* followed by the event-loop turn in which the runtime runs the native finalizers it queued. Calls made before those
|
|
140
|
+
* collections start share them.
|
|
141
|
+
* @returns {Promise<void>}
|
|
142
|
+
*/
|
|
143
|
+
function releaseClosedConnections() {
|
|
144
|
+
if (!pendingCollection) {
|
|
145
|
+
pendingCollection = collection.then(collectAndFinalize, collectAndFinalize);
|
|
146
|
+
collection = pendingCollection;
|
|
147
|
+
}
|
|
148
|
+
return pendingCollection;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
async function collectAndFinalize() {
|
|
152
|
+
pendingCollection = undefined;
|
|
153
|
+
for (let pass = 0; pass < COLLECTION_PASSES; pass++) {
|
|
154
|
+
collectGarbage();
|
|
155
|
+
await new Promise((resolve) => setImmediate(resolve));
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** How far `transientFailure` follows `cause`: a driver error wraps the network error that fetch wraps. */
|
|
160
|
+
const MAX_CAUSE_DEPTH = 8;
|
|
161
|
+
/**
|
|
162
|
+
* Codes sqld answers for a stream or transaction it ended and rolled back: nothing of it was written.
|
|
163
|
+
* @type {ReadonlyMap<unknown, import("@bastani/atomic/storage").StorageTransientErrorCode>}
|
|
164
|
+
*/
|
|
165
|
+
const ENDED_BY_SERVER = new Map([
|
|
166
|
+
["STREAM_EXPIRED", "stream-expired"],
|
|
167
|
+
["TRANSACTION_TIMEOUT", "transaction-timeout"],
|
|
168
|
+
]);
|
|
169
|
+
/**
|
|
170
|
+
* Network codes of a request that never reached the server, from Node's fetch and from Bun's.
|
|
171
|
+
* @type {ReadonlySet<unknown>}
|
|
172
|
+
*/
|
|
173
|
+
const NOT_SENT = new Set(["ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT"]);
|
|
174
|
+
/**
|
|
175
|
+
* Network codes of a connection that broke after a request may have reached the server.
|
|
176
|
+
* @type {ReadonlySet<unknown>}
|
|
177
|
+
*/
|
|
178
|
+
const CONNECTION_LOST = new Set(["ECONNRESET", "EPIPE", "ETIMEDOUT", "UND_ERR_SOCKET"]);
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* The failure, as one that passes, when the server ended the stream or transaction of a process that stalled, or the
|
|
182
|
+
* connection to the server could not be made or broke; read from each error's `code` along the cause chain, never
|
|
183
|
+
* from its message.
|
|
184
|
+
* @param {import("@bastani/atomic/storage").StorageFailureCause} failure
|
|
185
|
+
* @returns {import("@bastani/atomic/storage").SqliteDriverTransientFailure | undefined}
|
|
186
|
+
*/
|
|
187
|
+
function transientFailure(failure) {
|
|
188
|
+
/** @type {unknown} */
|
|
189
|
+
let current = failure;
|
|
190
|
+
for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof current === "object" && current !== null; depth++) {
|
|
191
|
+
const { code, cause } = /** @type {{ readonly code?: unknown, readonly cause?: unknown }} */ (current);
|
|
192
|
+
const ended = ENDED_BY_SERVER.get(code);
|
|
193
|
+
if (ended !== undefined) return { code: ended, outcome: "not-applied" };
|
|
194
|
+
if (NOT_SENT.has(code)) return { code: "connection-refused", outcome: "not-applied" };
|
|
195
|
+
if (CONNECTION_LOST.has(code)) return { code: "connection-lost", outcome: "unknown" };
|
|
196
|
+
current = cause;
|
|
197
|
+
}
|
|
198
|
+
return undefined;
|
|
199
|
+
}
|
|
200
|
+
|
|
105
201
|
/**
|
|
106
202
|
* @param {LibsqlDatabaseOptions} options
|
|
107
203
|
* @returns {Promise<import("@bastani/atomic/storage").SqliteDatabase>}
|
|
@@ -121,36 +217,67 @@ export async function openLibsqlDatabase({ url, authToken, namespace, headers })
|
|
|
121
217
|
// Create the client inside a driver call, so the facade redacts credentials from its failures. The busy timeout is a
|
|
122
218
|
// client option, not a PRAGMA, because the client opens more connections than the one that ran the PRAGMA, and
|
|
123
219
|
// each needs it; a connection waits for a lock on the calling thread.
|
|
124
|
-
const
|
|
125
|
-
|
|
220
|
+
const create = () =>
|
|
221
|
+
createClient({
|
|
126
222
|
url,
|
|
127
223
|
authToken,
|
|
128
224
|
intMode: "bigint",
|
|
129
225
|
...(local ? { timeout: FILE_BUSY_TIMEOUT_MS } : {}),
|
|
130
226
|
...(added.length > 0 ? { fetch: fetchWith(added) } : {}),
|
|
131
|
-
})
|
|
227
|
+
});
|
|
228
|
+
// A local statement that fails part way, as a write does when another process holds the lock past the busy timeout,
|
|
229
|
+
// stays active on its connection: the driver resets and finalizes a statement only when it is garbage collected.
|
|
230
|
+
// Until then that connection commits nothing ("cannot commit transaction - SQL statements in progress"), and a
|
|
231
|
+
// write outside a transaction reports success but is never committed. So after a local failure the next call gets
|
|
232
|
+
// new connections. The facade runs one call at a time, so no call is still using the old ones.
|
|
233
|
+
let replace = false;
|
|
234
|
+
/** @type {<T>(operation: () => Promise<T>) => Promise<T>} */
|
|
235
|
+
const watch = async (operation) => {
|
|
236
|
+
try {
|
|
237
|
+
return await operation();
|
|
238
|
+
} catch (error) {
|
|
239
|
+
if (local) replace = true;
|
|
240
|
+
throw error;
|
|
241
|
+
}
|
|
242
|
+
};
|
|
243
|
+
const connection = async () => {
|
|
244
|
+
if (replace) {
|
|
245
|
+
replace = false;
|
|
246
|
+
client?.close();
|
|
247
|
+
const fresh = create();
|
|
248
|
+
client = fresh;
|
|
249
|
+
// A new connection does not have the PRAGMA the open ran on the one it replaces.
|
|
250
|
+
await watch(() => fresh.execute("PRAGMA foreign_keys = ON"));
|
|
251
|
+
}
|
|
252
|
+
return (client ??= create());
|
|
253
|
+
};
|
|
132
254
|
const database = createSqliteDatabase({
|
|
133
255
|
descriptor: { adapter: "libsql", location: url },
|
|
134
256
|
redact: redactSecrets([authToken ?? "", ...urlCredentials(url), ...Object.values(headers ?? {})]),
|
|
135
|
-
|
|
257
|
+
transientFailure,
|
|
258
|
+
...statements(connection, watch),
|
|
136
259
|
// One request for the whole batch, in a write transaction: the journal sends a batch of appends this way.
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
260
|
+
batch: (batched) =>
|
|
261
|
+
watch(async () => {
|
|
262
|
+
const results = await (await connection()).batch(
|
|
263
|
+
batched.map(({ sql, params }) => ({ sql, args: [...params] })),
|
|
264
|
+
"write",
|
|
265
|
+
);
|
|
266
|
+
return results.map(driverResult);
|
|
267
|
+
}),
|
|
144
268
|
async beginTransaction() {
|
|
145
|
-
const transaction = await connection().transaction("write");
|
|
269
|
+
const transaction = await watch(async () => (await connection()).transaction("write"));
|
|
146
270
|
return {
|
|
147
|
-
...statements(() => transaction),
|
|
148
|
-
commit: () => transaction.commit(),
|
|
149
|
-
rollback: () => transaction.rollback(),
|
|
271
|
+
...statements(async () => transaction, watch),
|
|
272
|
+
commit: () => watch(() => transaction.commit()),
|
|
273
|
+
rollback: () => watch(() => transaction.rollback()),
|
|
150
274
|
close: () => transaction.close(),
|
|
151
275
|
};
|
|
152
276
|
},
|
|
153
|
-
close
|
|
277
|
+
async close() {
|
|
278
|
+
client?.close();
|
|
279
|
+
if (local) await releaseClosedConnections();
|
|
280
|
+
},
|
|
154
281
|
});
|
|
155
282
|
try {
|
|
156
283
|
await database.exec("PRAGMA foreign_keys = ON");
|
|
@@ -162,7 +289,11 @@ export async function openLibsqlDatabase({ url, authToken, namespace, headers })
|
|
|
162
289
|
if (local) await switchToWriteAheadLog((sql) => database.exec(sql), FILE_BUSY_TIMEOUT_MS);
|
|
163
290
|
return database;
|
|
164
291
|
} catch (error) {
|
|
165
|
-
await database
|
|
292
|
+
await database
|
|
293
|
+
.close()
|
|
294
|
+
.catch((cleanupCause) =>
|
|
295
|
+
Object.defineProperty(/** @type {Error} */ (error), "cleanupCause", { value: cleanupCause, configurable: true }),
|
|
296
|
+
);
|
|
166
297
|
throw error;
|
|
167
298
|
}
|
|
168
299
|
}
|