Skip to content

Commit cd04eb7

Browse files
committed
fix(driver-sqlite-wasm): refuse a file sql.js cannot read at connect instead of renaming it
WasmSqliteConnection.open() throws SQLITE_NOTADB / SQLITE_CORRUPT naming the file, with a prescription to move it aside; quarantineCorruptFile retires. resolveSqliteDriver re-throws a wasm file refusal instead of stepping down to the in-memory rung. Claude-Session: https://claude.ai/code/session_015pbbff7SHh7EEEWiasBdDe Co-authored-by: Claude <noreply@anthropic.com>
1 parent f7d7403 commit cd04eb7

4 files changed

Lines changed: 278 additions & 63 deletions

File tree

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* A file wasm SQLite cannot read is refused at connect, naming the file, with
5+
* the code the native driver answers for the same file, and is left exactly as
6+
* it was found (#25019): nothing renamed, nothing written beside it, no empty
7+
* database in its place.
8+
*
9+
* Before, `WasmSqliteConnection.open()` moved such a file to
10+
* `<file>.corrupt-<timestamp>` and started an empty database, so a declared
11+
* `sqlite-wasm` datasource over an operator's file read as connected, in
12+
* development and production alike.
13+
*
14+
* Real sql.js and real files in a scratch directory.
15+
*/
16+
17+
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
18+
import { mkdtempSync, readdirSync, readFileSync, rmSync, truncateSync, writeFileSync, statSync, existsSync } from 'node:fs';
19+
import { tmpdir } from 'node:os';
20+
import { join } from 'node:path';
21+
22+
import { SqliteWasmDriver, WasmSqliteConnection } from './index.js';
23+
24+
let dir: string;
25+
const drivers: SqliteWasmDriver[] = [];
26+
27+
beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'wasm-25019-')); });
28+
29+
afterEach(async () => {
30+
await Promise.all(drivers.splice(0).map((d) => d.disconnect().catch(() => {})));
31+
rmSync(dir, { recursive: true, force: true });
32+
});
33+
34+
function driverFor(filename: string): SqliteWasmDriver {
35+
const driver = new SqliteWasmDriver({ filename, persist: 'on-write', logger: { warn: () => {} } });
36+
drivers.push(driver);
37+
return driver;
38+
}
39+
40+
/** A real database written by this driver, holding one row in `t`. Its size in bytes. */
41+
async function seedDatabase(filename: string): Promise<number> {
42+
const seed = new SqliteWasmDriver({ filename, persist: 'on-disconnect' });
43+
await seed.connect();
44+
await seed.execute('CREATE TABLE t (a INTEGER)');
45+
await seed.execute('INSERT INTO t (a) VALUES (7)');
46+
await seed.disconnect();
47+
return statSync(filename).size;
48+
}
49+
50+
/** `connect()`'s rejection; a failure when it resolves instead. */
51+
async function connectRefusal(driver: SqliteWasmDriver): Promise<any> {
52+
try {
53+
await driver.connect();
54+
} catch (error) {
55+
return error;
56+
}
57+
throw new Error('connect() resolved over a file wasm SQLite cannot read');
58+
}
59+
60+
/** The driver's refusal: the native driver's class and code, the file named, and how to move it aside. */
61+
function expectFileRefusal(error: any, filename: string, code: 'SQLITE_NOTADB' | 'SQLITE_CORRUPT'): void {
62+
expect(error?.name).toBe('SqliteDatabaseFileError');
63+
expect(error?.code).toBe(code);
64+
expect(error?.filename).toBe(filename);
65+
expect(String(error?.message)).toContain(`SQLite database file '${filename}'`);
66+
expect(String(error?.message)).toContain(
67+
`To start from an empty database, move the file aside yourself (mv '${filename}' '${filename}.unreadable') and start again; to keep its data, restore a copy that opens.`,
68+
);
69+
}
70+
71+
describe('a file wasm SQLite cannot read is refused at connect and left as it was found (#25019)', () => {
72+
it('plain text: SQLITE_NOTADB, naming the file', async () => {
73+
const filename = join(dir, 'archive.db');
74+
const bytes = Buffer.from('id,name\n1,not a database\n'.repeat(20));
75+
writeFileSync(filename, bytes);
76+
77+
const refusal = await connectRefusal(driverFor(filename));
78+
expectFileRefusal(refusal, filename, 'SQLITE_NOTADB');
79+
expect(String(refusal.message)).toContain('was left as it is');
80+
81+
expect(readdirSync(dir)).toEqual(['archive.db']);
82+
expect(readFileSync(filename).equals(bytes)).toBe(true);
83+
});
84+
85+
it('a database truncated inside its 100-byte header: SQLITE_CORRUPT, naming the file', async () => {
86+
const filename = join(dir, 'archive.db');
87+
await seedDatabase(filename);
88+
truncateSync(filename, 50);
89+
const bytes = readFileSync(filename);
90+
91+
expectFileRefusal(await connectRefusal(driverFor(filename)), filename, 'SQLITE_CORRUPT');
92+
93+
expect(readdirSync(dir)).toEqual(['archive.db']);
94+
expect(readFileSync(filename).equals(bytes)).toBe(true);
95+
});
96+
97+
it('a database short of the pages its schema names: SQLITE_CORRUPT, naming the file', async () => {
98+
const filename = join(dir, 'archive.db');
99+
const size = await seedDatabase(filename);
100+
truncateSync(filename, Math.floor(size / 2));
101+
const bytes = readFileSync(filename);
102+
103+
expectFileRefusal(await connectRefusal(driverFor(filename)), filename, 'SQLITE_CORRUPT');
104+
105+
expect(readdirSync(dir)).toEqual(['archive.db']);
106+
expect(readFileSync(filename).equals(bytes)).toBe(true);
107+
});
108+
109+
it('a refused file keeps the write-ahead log beside it: nothing is parked', async () => {
110+
const filename = join(dir, 'archive.db');
111+
writeFileSync(filename, 'not a database');
112+
const wal = Buffer.from('a stale write-ahead log');
113+
writeFileSync(`${filename}-wal`, wal);
114+
115+
expectFileRefusal(await connectRefusal(driverFor(filename)), filename, 'SQLITE_NOTADB');
116+
117+
expect(readdirSync(dir).sort()).toEqual(['archive.db', 'archive.db-wal']);
118+
expect(readFileSync(`${filename}-wal`).equals(wal)).toBe(true);
119+
});
120+
121+
it('WasmSqliteConnection.open() itself rejects with the code and the file, and writes nothing', async () => {
122+
const filename = join(dir, 'archive.db');
123+
writeFileSync(filename, 'not a database');
124+
125+
const conn = new WasmSqliteConnection({ filename, logger: { warn: () => {} } });
126+
let refusal: any;
127+
await conn.open().catch((e: unknown) => { refusal = e; });
128+
expect(refusal?.code).toBe('SQLITE_NOTADB');
129+
expect(refusal?.filename).toBe(filename);
130+
expect(String(refusal?.message)).toContain(`mv '${filename}' '${filename}.unreadable'`);
131+
expect(String((refusal?.cause as Error)?.message)).toBe('file is not a database');
132+
133+
expect(readdirSync(dir)).toEqual(['archive.db']);
134+
expect(readFileSync(filename, 'utf8')).toBe('not a database');
135+
});
136+
});
137+
138+
describe('CONTROLS: what keeps today\'s behaviour (#25019)', () => {
139+
it('a real database opens and answers', async () => {
140+
const filename = join(dir, 'archive.db');
141+
await seedDatabase(filename);
142+
const driver = driverFor(filename);
143+
await driver.connect();
144+
expect(await driver.execute('SELECT a FROM t')).toEqual([{ a: 7 }]);
145+
});
146+
147+
it('an absent file is created', async () => {
148+
const filename = join(dir, 'new', 'archive.db');
149+
const driver = driverFor(filename);
150+
await driver.connect();
151+
await driver.execute('CREATE TABLE t (a INTEGER)');
152+
await driver.flush();
153+
expect(existsSync(filename)).toBe(true);
154+
});
155+
156+
it('an empty file opens as an empty database', async () => {
157+
const filename = join(dir, 'archive.db');
158+
writeFileSync(filename, '');
159+
const driver = driverFor(filename);
160+
await driver.connect();
161+
expect(await driver.execute('SELECT 1 AS one')).toEqual([{ one: 1 }]);
162+
expect(readdirSync(dir).filter((name) => name.includes('.corrupt-'))).toEqual([]);
163+
});
164+
});

‎packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-driver-durability.test.ts‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,10 @@ import { SqliteWasmDriver } from '../src/index.js';
2121
*
2222
* 1. Flushes must be ATOMIC. A non-atomic overwrite torn by a mid-write kill
2323
* left "database disk image is malformed" on the next boot.
24-
* 2. An already-corrupt on-disk image must SELF-HEAL: quarantine the bad file
25-
* and boot on a fresh database instead of failing every query forever.
24+
* 2. An already-corrupt on-disk image is REFUSED at connect, naming the file,
25+
* and left exactly as it was found (#25019). It used to self-heal: the open
26+
* renamed it to `<file>.corrupt-<timestamp>` and booted on an empty
27+
* database, which read as connected over an operator's file it replaced.
2628
* 3. `undefined` bindings must persist as SQL NULL rather than throwing sql.js's
2729
* raw-string "Wrong API use : tried to bind a value of an unknown type".
2830
*/
@@ -70,11 +72,11 @@ describe('SqliteWasmDriver durability & resilience', () => {
7072
expect(rows[0].name).toBe('A');
7173
});
7274

73-
it('self-heals a corrupt database image by quarantining it and booting fresh', async () => {
75+
it('refuses a corrupt database image at connect, naming the file, and leaves it as it was found', async () => {
7476
const dir = newDir();
7577
const file = join(dir, 'corrupt.db');
7678
// A file that starts with the SQLite magic header but is otherwise garbage:
77-
// sql.js opens it, then blows up on the first page read ("malformed").
79+
// sql.js opens it, then fails the first page read.
7880
const junk = Buffer.concat([
7981
Buffer.from('SQLite format 3\0', 'binary'),
8082
Buffer.alloc(4096, 0xab),
@@ -90,18 +92,21 @@ describe('SqliteWasmDriver durability & resilience', () => {
9092
}),
9193
);
9294

93-
// Boot must succeed and queries must work on the fresh database.
94-
await driver.initObjects([{ name: 'acct', fields: { name: { type: 'string' } } }]);
95-
await (driver as any).knex('acct').insert({ id: 'a1', name: 'healed' });
96-
const rows = await (driver as any).knex('acct');
97-
expect(rows.length).toBe(1);
95+
let refusal: any;
96+
await driver.connect().catch((e: unknown) => { refusal = e; });
97+
expect(refusal?.name).toBe('SqliteDatabaseFileError');
98+
expect(refusal?.code).toBe('SQLITE_NOTADB');
99+
expect(refusal?.filename).toBe(file);
100+
expect(String(refusal?.message)).toContain(`'${file}'`);
101+
// The prescription: the operator moves the file aside, since the open no longer does.
102+
expect(String(refusal?.message)).toContain(
103+
`move the file aside yourself (mv '${file}' '${file}.unreadable')`,
104+
);
98105

99-
// The corrupt bytes were preserved in a sibling quarantine file, and a
100-
// warning was surfaced.
101-
const quarantined = readdirSync(dir).filter((f) => f.includes('.corrupt-'));
102-
expect(quarantined.length).toBe(1);
103-
expect(readFileSync(join(dir, quarantined[0]))).toEqual(junk);
104-
expect(warnings.some((w) => w.includes('corrupt'))).toBe(true);
106+
// Nothing renamed, nothing written beside it, the bytes untouched.
107+
expect(readdirSync(dir)).toEqual(['corrupt.db']);
108+
expect(readFileSync(file)).toEqual(junk);
109+
expect(warnings.some((w) => w.includes('Quarantined'))).toBe(false);
105110
});
106111

107112
it('persists an undefined binding as SQL NULL instead of throwing', async () => {

‎packages/drivers/driver-sqlite-wasm/src/wasm-connection.ts‎

Lines changed: 73 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,52 @@ async function loadSqlJs(
8686
return cachedSqlJs;
8787
}
8888

89+
/**
90+
* SQLite's own text for `SQLITE_NOTADB` (`sqlite3_errstr(26)`). sql.js throws
91+
* a bare `Error` carrying SQLite's message and no result code, so this text is
92+
* the only form the code reaches this file in.
93+
*/
94+
const SQLITE_NOTADB_ERRSTR = 'file is not a database';
95+
96+
/**
97+
* The refusal {@link WasmSqliteConnection.open} throws for a file sql.js cannot
98+
* read (#25019), with the SQLite code the native driver answers for the same
99+
* file: `SQLITE_NOTADB` when SQLite says the bytes are not a database, and
100+
* `SQLITE_CORRUPT` for every other reason a read of the image failed ("database
101+
* disk image is malformed", a `quick_check` that does not answer `ok`).
102+
*
103+
* The code is what makes it one refusal with the native driver's:
104+
* `SqlDriver.connect()` names the file with its own words for that code, and
105+
* `resolveSqliteDriver` (`@objectstack/service-datasource`) re-throws it rather
106+
* than step down. The message is the rest of the answer, and the one thing only
107+
* this engine can say: it no longer moves the file aside for the operator, so
108+
* it says how to do that.
109+
*/
110+
function unreadableDatabaseFileRefusal(
111+
filename: string,
112+
cause: unknown,
113+
): UnreadableDatabaseFileRefusal {
114+
const reason =
115+
typeof cause === 'string' ? cause : (cause as Error | undefined)?.message ?? String(cause);
116+
// `cause` is attached by hand: the `ErrorOptions` overload is ES2022 and this
117+
// package compiles against ES2020's lib.
118+
const refusal = new Error(
119+
`wasm SQLite cannot read it (${reason}). To start from an empty database, move the ` +
120+
`file aside yourself (mv '${filename}' '${filename}.unreadable') and start again; ` +
121+
`to keep its data, restore a copy that opens.`,
122+
) as UnreadableDatabaseFileRefusal;
123+
refusal.code = reason === SQLITE_NOTADB_ERRSTR ? 'SQLITE_NOTADB' : 'SQLITE_CORRUPT';
124+
refusal.filename = filename;
125+
refusal.cause = cause;
126+
return refusal;
127+
}
128+
129+
type UnreadableDatabaseFileRefusal = Error & {
130+
code: 'SQLITE_NOTADB' | 'SQLITE_CORRUPT';
131+
filename: string;
132+
cause: unknown;
133+
};
134+
89135
/**
90136
* A sql.js-backed connection that exposes the `prepare`/`exec`/`close`
91137
* subset used by Knex's SQLite dialect. Mutations are queued through a
@@ -198,24 +244,37 @@ export class WasmSqliteConnection {
198244
return;
199245
}
200246

201-
await this.quarantineOrphanedWal();
202-
203-
// Open the on-disk bytes, but guard against a corrupt image. A torn write
204-
// (process killed mid-flush before atomic writes existed) or otherwise
205-
// damaged file makes `new SQL.Database(bytes)` either throw ("file is not a
206-
// database") or open a handle whose every query fails with "database disk
207-
// image is malformed" — which, for a background dispatcher on a tick loop,
208-
// means the same error spammed forever with no path to recovery. Detect it
209-
// once at open, quarantine the bad file, and start fresh so the dev server
210-
// becomes usable again instead of wedging.
247+
// Open the on-disk bytes, and refuse a file sql.js cannot read (#25019).
248+
// A file that is not a database makes the first read throw "file is not a
249+
// database"; a damaged one throws "database disk image is malformed" or
250+
// fails `quick_check`. Either way every later query would answer the same,
251+
// so the open fails here, naming the file, with the code the native driver
252+
// answers for the same file (see `unreadableDatabaseFileRefusal`).
253+
//
254+
// The file is left exactly as it was found. This open used to move it to
255+
// `<file>.corrupt-<timestamp>` and start an empty database in its place: a
256+
// self-heal written for torn wasm images, which `atomicWriteFile` has since
257+
// closed. What still reached it was an operator's file on a declared
258+
// datasource — an explicit `sqlite-wasm` one in any mode, and the
259+
// development step-down from a native addon that cannot load — which then
260+
// read as connected over an empty database.
261+
let candidate: Database | undefined;
211262
try {
212-
const candidate = new SQL.Database(bytes);
263+
candidate = new SQL.Database(bytes);
213264
this.assertReadable(candidate);
214-
this.db = candidate;
215265
} catch (err) {
216-
await this.quarantineCorruptFile(err);
217-
this.db = new SQL.Database();
266+
try {
267+
candidate?.close();
268+
} catch {
269+
/* the refusal below is the answer */
270+
}
271+
throw unreadableDatabaseFileRefusal(this.filename, err);
218272
}
273+
274+
// Only a file this open accepts gets its stale log parked: a refused file
275+
// keeps everything beside it as well.
276+
await this.quarantineOrphanedWal();
277+
this.db = candidate;
219278
}
220279

221280
/**
@@ -233,35 +292,6 @@ export class WasmSqliteConnection {
233292
}
234293
}
235294

236-
/**
237-
* Move a corrupt database file aside so its bytes are preserved for
238-
* post-mortem while a fresh, empty database takes its place. Best-effort:
239-
* failures here must not prevent the server from booting on a clean DB.
240-
*/
241-
private async quarantineCorruptFile(cause: unknown): Promise<void> {
242-
if (!this.fs) return;
243-
const reason =
244-
typeof cause === 'string' ? cause : (cause as Error)?.message ?? String(cause);
245-
const backup = `${this.filename}.corrupt-${Date.now()}`;
246-
try {
247-
await this.fs.rename(this.filename, backup);
248-
this.logger.warn(
249-
`[driver-sqlite-wasm] Database image at ${this.filename} is corrupt ` +
250-
`(${reason}). Quarantined to ${backup} and starting from an empty ` +
251-
`database so the server can boot.`,
252-
);
253-
} catch (renameErr) {
254-
// Could not move it aside (e.g. permissions) — overwrite is still better
255-
// than looping forever on a malformed image. Warn loudly and continue.
256-
this.logger.warn(
257-
`[driver-sqlite-wasm] Database image at ${this.filename} is corrupt ` +
258-
`(${reason}) and could not be quarantined (${String(renameErr)}). ` +
259-
`Starting from an empty database; the corrupt file will be overwritten ` +
260-
`on the next flush.`,
261-
);
262-
}
263-
}
264-
265295
/**
266296
* Move a write-ahead log left behind by a *real* SQLite aside (#3941).
267297
*

0 commit comments

Comments
 (0)