@@ -0,0 +1,12 @@
+---
+"@objectstack/driver-sql": patch
+---
+
+A connect to a SQLite file that is already `auto_vacuum=INCREMENTAL` no longer writes to it. `SqlDriver.connect()` now reads `PRAGMA auto_vacuum` first and runs `PRAGMA auto_vacuum = INCREMENTAL` only when the file answers something else.
+
+Clause-②: no
+
+- **What changed on disk.** On a file that already answered INCREMENTAL, the setter changed no mode, but it still stamped two header counters: the file change counter (bytes 24–27) and the version-valid-for number (bytes 92–95). So a read-only command such as `os migrate duplicates`, which the CLI docs say writes nothing at all, changed the file's md5 on every run. Reading the pragma changes no bytes, so such a file now comes through a connect, and a whole `os migrate duplicates` run, byte-identical.
+- **Unchanged.** A fresh file and `:memory:` still come out INCREMENTAL. A legacy NONE file that already holds tables still gets the setter, which leaves it NONE until a `VACUUM` (`os db clean`), exactly as before. The journal-mode step already read first and set only on a difference, and it is untouched. Postgres and MySQL issue no PRAGMA.
+- **The WASM SQLite driver** inherits the rule. A connect and disconnect no longer rewrites an already-INCREMENTAL image file, because the setter was what marked the image dirty.
+- ⛔ No config key, export, error code or accepted input changes.
@@ -38,10 +38,12 @@
  * Both classes are asserted, separately, over one run.
  */
 
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { SqlDriver } from '@objectstack/driver-sql';
 import {
   resolveSeedTenancyExec,
@@ -53,7 +55,12 @@ import {
   SEQUENCES_TABLE,
 } from '@objectstack/metadata-protocol';
 import { bootSchemaStack } from '../../utils/schema-migrate.js';
-import { collectDuplicateIdentifierReport } from './duplicates.js';
+import { isExitSignal } from '../../utils/format.js';
+import MigrateDuplicates, { collectDuplicateIdentifierReport } from './duplicates.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** This package's root, where oclif reads its own manifest from. */
+const CLI_ROOT = resolve(HERE, '..', '..', '..');
 
 let dir: string;
 let dbFile: string;
@@ -63,12 +70,15 @@ const savedEnv: Record<string, string | undefined> = {};
  * The fixture's LOGICAL state — the schema plus every row of every table,
  * ordered — read with a connection of our own, never the booted stack's.
  *
- * ⚠️ Deliberately not a hash of the database FILE. SQLite rewrites header
- * bytes (the change counter, the version-valid-for cookie) on any read-write
- * open, so a file hash reports a difference after a run that only SELECTed and
- * would accuse this command of mutating the install it exists to describe —
- * measured, and very nearly filed as a defect. What must not change is the
- * schema and the rows.
+ * ⚠️ Deliberately not a hash of the database FILE — not on THIS fixture. It is
+ * written by a driver that never connected, so it is still on a rollback
+ * journal, and the boot's first connect converts it to WAL: a persistent
+ * header change (bytes 18–19, plus the change counter at 24–27 and the
+ * version-valid-for number at 92–95) that any first connect makes, measured.
+ * A plain open is byte-neutral, and a file a serving boot already configured
+ * comes through a whole run byte-identical — the second describe below pins
+ * that on its own fixture (#21734). What must not change HERE is the schema
+ * and the rows.
  */
 async function readState(): Promise<unknown> {
   const probe = new SqlDriver({
@@ -283,3 +293,103 @@ describe('#8928 os migrate duplicates — against a really booted stack', () =>
     expect(await readState()).toEqual(before);
   }, 120_000);
 });
+
+/**
+ * #21734 — the database FILE, not only its rows, comes out of a run unchanged.
+ *
+ * `SqlDriver.connect()` used to run `PRAGMA auto_vacuum = INCREMENTAL` on every
+ * connect. On a file a serving boot had already configured the setter changes
+ * no mode, but it stamps two header counters (bytes 24–27 and 92–95), so the
+ * whole-file md5 moved under a command that only SELECTed. The driver now reads
+ * the pragma first and sets it only when the file answers differently.
+ *
+ * Measured on a fixture shaped the way an install is: a driver CONNECTED to a
+ * fresh file first — so it is `auto_vacuum=INCREMENTAL` and in WAL, as `os dev`
+ * leaves it — and the rows written after. The command is the real one, run
+ * in-process (oclif parse, the read-only boot, the probes, the JSON payload,
+ * the shutdown) rather than spawned: one spawn of the source entry costs a tsx
+ * compile of the whole CLI for an answer that lies entirely inside `run()`.
+ */
+describe('#21734 os migrate duplicates — an already-configured database file is byte-identical after a run', () => {
+  const OVERRIDING_ENV = ['OS_DATABASE_URL', 'DATABASE_URL', 'TURSO_DATABASE_URL', 'OS_DATABASE_DRIVER', 'OS_HOME'] as const;
+  let booted: string;
+
+  const md5 = (file: string): string => createHash('md5').update(readFileSync(file)).digest('hex');
+
+  /** The command's one JSON document and its exit code, from an in-process run. */
+  async function runDuplicates(argv: string[]): Promise<{ payload: any; exitCode: number }> {
+    const savedExit = process.exitCode;
+    const savedCwd = process.cwd();
+    const saved: Record<string, string | undefined> = {};
+    for (const key of OVERRIDING_ENV) saved[key] = process.env[key];
+    const swallow = ((_chunk: unknown, ...rest: unknown[]) => {
+      const cb = rest.find((a) => typeof a === 'function') as (() => void) | undefined;
+      if (cb) cb();
+      return true;
+    }) as typeof process.stdout.write;
+    const stdout = vi.spyOn(process.stdout, 'write').mockImplementation(swallow);
+    vi.spyOn(process.stderr, 'write').mockImplementation(swallow);
+    let thrownExit: number | undefined;
+    try {
+      for (const key of OVERRIDING_ENV) delete process.env[key];
+      // The command has no project-root flag: it boots from the current directory.
+      process.chdir(dir);
+      try {
+        await MigrateDuplicates.run(argv, { root: CLI_ROOT });
+      } catch (error) {
+        if (!isExitSignal(error)) throw error;
+        thrownExit = (error as { oclif?: { exit?: number } }).oclif?.exit;
+      }
+      const out = stdout.mock.calls.map((c) => String(c[0])).join('').trim();
+      return { payload: JSON.parse(out), exitCode: thrownExit ?? (process.exitCode as number | undefined) ?? 0 };
+    } finally {
+      process.chdir(savedCwd);
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+      process.exitCode = savedExit;
+      vi.restoreAllMocks();
+    }
+  }
+
+  beforeAll(async () => {
+    booted = join(dir, 'data', 'booted.db');
+    const d = new SqlDriver({ client: 'better-sqlite3', connection: { filename: booted }, useNullAsDefault: true });
+    await d.connect();
+    const k = (d as any).knex;
+    await k.schema.createTable('crm_case', (t: any) => {
+      t.string('id').primary();
+      t.timestamp('created_at');
+      t.timestamp('updated_at');
+      t.string('organization_id');
+      t.string('subject');
+      t.string('case_number');
+    });
+    await k('crm_case').insert([
+      { id: 's1', created_at: '2026-01-01T00:00:00.000Z', organization_id: null, subject: 'seeded', case_number: 'CASE-00001' },
+      { id: 'a1', created_at: '2026-02-01T00:00:00.000Z', organization_id: 'org_x', subject: 'api', case_number: 'CASE-00001' },
+    ]);
+    await d.disconnect();
+  }, 120_000);
+
+  it('`os migrate duplicates` leaves the md5 of an auto_vacuum=INCREMENTAL WAL file unchanged', async () => {
+    // The precondition, read on a connection of our own (a read is byte-neutral).
+    const probe = new SqlDriver({ client: 'better-sqlite3', connection: { filename: booted }, useNullAsDefault: true });
+    try {
+      const k = (probe as any).knex;
+      expect((await k.raw('PRAGMA auto_vacuum'))[0].auto_vacuum).toBe(2);
+      expect(String((await k.raw('PRAGMA journal_mode'))[0].journal_mode).toLowerCase()).toBe('wal');
+    } finally {
+      await probe.disconnect();
+    }
+    const before = md5(booted);
+
+    const { payload, exitCode } = await runDuplicates(['--database-url', `file:${booted}`]);
+
+    expect(exitCode).toBe(0);
+    // It really did look — a run that read nothing would leave the file alone trivially.
+    expect(payload.duplicates.map((entry: { value: string }) => entry.value)).toEqual(['CASE-00001']);
+    expect(md5(booted)).toBe(before);
+  }, 120_000);
+});
@@ -0,0 +1,155 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #21734: `SqlDriver.connect()` used to run `PRAGMA auto_vacuum = INCREMENTAL`
+// on every connect. On a file that already answers INCREMENTAL the setter
+// changes no mode, but it still runs a write transaction that stamps two header
+// counters — the file change counter (bytes 24–27) and the version-valid-for
+// number (bytes 92–95) — so a connect made only to READ (`os migrate
+// duplicates`) left the file's md5 different from how it found it. The driver
+// now reads `PRAGMA auto_vacuum` first (byte-neutral) and sets it only when the
+// file does not answer INCREMENTAL, on every connect alike.
+//
+// What is pinned:
+//   1. an already-INCREMENTAL WAL file comes out of connect + disconnect
+//      byte-identical — with a control proving the md5 instrument sees the
+//      setter's header stamp on the same file;
+//   2. a fresh file and `:memory:` still come out INCREMENTAL (ADR-0057);
+//   3. a legacy NONE file that already holds tables still gets the setter it
+//      always got, and stays NONE — this driver runs no VACUUM, before or after;
+//   4. the non-SQLite dialects issue no PRAGMA at all.
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SqlDriver } from './sql-driver.js';
+
+const dirs: string[] = [];
+const drivers: SqlDriver[] = [];
+
+function tempDb(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'os-21734-'));
+  dirs.push(dir);
+  return join(dir, 'app.db');
+}
+
+function make(cfg: Record<string, unknown>): SqlDriver & { knex: any } {
+  const d = new SqlDriver({ useNullAsDefault: true, ...cfg } as any);
+  drivers.push(d);
+  return d as any;
+}
+
+function sqlite(filename: string): SqlDriver & { knex: any } {
+  return make({ client: 'better-sqlite3', connection: { filename } });
+}
+
+/** Every statement the driver sends, in order — knex's own `query` event. */
+function trace(driver: any): string[] {
+  const seen: string[] = [];
+  driver.knex.on('query', (q: { sql?: unknown }) => seen.push(String(q.sql)));
+  return seen;
+}
+
+const md5 = (file: string): string => createHash('md5').update(readFileSync(file)).digest('hex');
+
+/** Byte offsets at which two images differ. */
+function differingOffsets(a: Buffer, b: Buffer): number[] {
+  const out: number[] = [];
+  for (let i = 0; i < Math.max(a.length, b.length); i++) if (a[i] !== b[i]) out.push(i);
+  return out;
+}
+
+/** `PRAGMA auto_vacuum` / `journal_mode` as a fresh connection of our own reads them. */
+async function fileModes(file: string): Promise<{ autoVacuum: number; journalMode: string }> {
+  const probe = sqlite(file);
+  try {
+    const av = await probe.knex.raw('PRAGMA auto_vacuum');
+    const jm = await probe.knex.raw('PRAGMA journal_mode');
+    return { autoVacuum: Number(av[0].auto_vacuum), journalMode: String(jm[0].journal_mode).toLowerCase() };
+  } finally {
+    await probe.disconnect();
+  }
+}
+
+/** An install as a serving boot leaves it: connected once on a fresh file, then holding rows. */
+async function bootedOnce(file: string): Promise<void> {
+  const d = sqlite(file);
+  await d.connect();
+  await d.knex.raw('CREATE TABLE t (id integer primary key, v text)');
+  for (let i = 0; i < 50; i++) await d.knex.raw('INSERT INTO t (v) VALUES (?)', [`row-${i}`]);
+  await d.disconnect();
+}
+
+afterEach(async () => {
+  await Promise.all(drivers.splice(0).map((d) => d.disconnect().catch(() => {})));
+  dirs.splice(0).forEach((d) => rmSync(d, { recursive: true, force: true }));
+});
+
+describe('SqlDriver — auto_vacuum is read first and set only when different (#21734)', () => {
+  it('a connect to an already-INCREMENTAL file leaves the file byte-identical', async () => {
+    const file = tempDb();
+    await bootedOnce(file);
+    expect(await fileModes(file)).toEqual({ autoVacuum: 2, journalMode: 'wal' });
+    const before = md5(file);
+
+    const d = sqlite(file);
+    await d.connect();
+    await d.disconnect();
+
+    expect(md5(file)).toBe(before);
+  });
+
+  it('control: the md5 instrument does see the setter stamp the header of that same file', async () => {
+    const file = tempDb();
+    await bootedOnce(file);
+    const image = readFileSync(file);
+
+    const d = sqlite(file);
+    await d.knex.raw('PRAGMA auto_vacuum = INCREMENTAL');
+    await d.disconnect();
+
+    const offsets = differingOffsets(image, readFileSync(file));
+    // A pin 1 that could not fail would read green here too; it must not.
+    expect(offsets.length).toBeGreaterThan(0);
+    // The two header counters, and nothing else: the mode itself did not move.
+    for (const at of offsets) expect((at >= 24 && at <= 27) || (at >= 92 && at <= 95)).toBe(true);
+    expect((await fileModes(file)).autoVacuum).toBe(2);
+  });
+
+  it('a fresh file still comes out INCREMENTAL', async () => {
+    const file = tempDb();
+    const d = sqlite(file);
+    await d.connect();
+    await d.knex.raw('CREATE TABLE t (a integer)');
+    await d.disconnect();
+
+    expect((await fileModes(file)).autoVacuum).toBe(2);
+  });
+
+  it('`:memory:` still comes out INCREMENTAL', async () => {
+    const d = sqlite(':memory:');
+    await d.connect();
+    const av = await d.knex.raw('PRAGMA auto_vacuum');
+    expect(Number(av[0].auto_vacuum)).toBe(2);
+  });
+
+  it('a legacy NONE file that holds tables still gets the setter, and stays NONE (no VACUUM is run)', async () => {
+    const file = tempDb();
+    // Written without ever connecting, so nothing set its mode: NONE, with a table.
+    const legacy = sqlite(file);
+    await legacy.knex.raw('CREATE TABLE t (a integer)');
+    await legacy.knex.raw('INSERT INTO t VALUES (1)');
+    await legacy.disconnect();
+    expect((await fileModes(file)).autoVacuum).toBe(0);
+
+    const d = sqlite(file);
+    const seen = trace(d);
+    await d.connect();
+    await d.disconnect();
+
+    expect(seen).toContain('PRAGMA auto_vacuum = INCREMENTAL');
+    expect(seen.some((sql) => /^\s*VACUUM\b/i.test(sql))).toBe(false);
+    expect((await fileModes(file)).autoVacuum).toBe(0);
+  });
+});
@@ -291,7 +291,9 @@ describe('SqlDriver — SQLite journal mode (#3941)', () => {
 
       await expect(d.connect()).resolves.toBeUndefined();
 
-      expect(attempted).toEqual(['PRAGMA auto_vacuum = INCREMENTAL']);
+      // The first statement is the auto_vacuum READ (#21734); it fails, so not
+      // even the setter is attempted.
+      expect(attempted).toEqual(['PRAGMA auto_vacuum']);
       expect(warnings).toHaveLength(1);
       expect(warnings[0]).toMatch(/native better-sqlite3 unavailable/);
     });