zerobucket 0.1.0 → 0.4.0

package/dist/index.js

@@ -15,8 +15,80 @@ import { createHash } from "crypto";
 import { readFile, stat } from "fs/promises";
 import { basename } from "path";
 
-// src/adapters/postgres.ts
+// src/adapters/shared.ts
 var DEFAULT_STREAM_CHUNK_SIZE = 1024 * 1024;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isValidId(id) {
+  return typeof id === "string" && UUID_RE.test(id);
+}
+function msg(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+function wrap(prefix, exc) {
+  return exc instanceof StorageError ? exc : new StorageError(`${prefix}: ${msg(exc)}`, { cause: exc });
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, async () => {
+      while (next < items.length) {
+        const i = next++;
+        out[i] = await fn(items[i]);
+      }
+    })
+  );
+  return out;
+}
+function tieredWithoutStorage(id, key) {
+  return new StorageError(
+    `Image ${JSON.stringify(id)} is stored in object storage (key=${JSON.stringify(key)}) but this ZeroBucket was constructed without \`objectStorage\`. Configure it with the same bucket and credentials that were used to tier this image.`
+  );
+}
+async function hydrateRow(row, id, os) {
+  let data;
+  if (row.storage_backend === "object_storage") {
+    if (!os) throw tieredWithoutStorage(id, row.object_storage_key);
+    data = await os.download(row.object_storage_key);
+    if (data.length !== row.size_bytes) {
+      throw new StorageError(
+        `Object ${JSON.stringify(row.object_storage_key)} for image ${JSON.stringify(id)} has ${data.length} bytes but the database records ${row.size_bytes}. The stored object is corrupted or was replaced.`
+      );
+    }
+  } else {
+    data = row.data;
+  }
+  return {
+    id: String(row.id),
+    data,
+    mimeType: row.mime_type,
+    originalFilename: row.original_filename,
+    sizeBytes: row.size_bytes,
+    width: row.width,
+    height: row.height,
+    checksumSha256: row.checksum_sha256
+  };
+}
+async function* streamFromObjectStorage(os, id, key, start, end, chunkSize) {
+  let offset = start;
+  while (offset <= end) {
+    const last = Math.min(offset + chunkSize - 1, end);
+    const expected = last - offset + 1;
+    const chunk = await os.downloadRange(key, offset, last);
+    if (chunk.length !== expected) {
+      throw new StorageError(
+        `Object ${JSON.stringify(key)} for image ${JSON.stringify(id)} returned ${chunk.length} bytes for a ${expected}-byte range; the stored object is shorter than the database records.`
+      );
+    }
+    yield chunk;
+    offset = last + 1;
+  }
+}
+
+// src/adapters/postgres.ts
 var SCHEMA = `
 CREATE TABLE IF NOT EXISTS zerobucket_images (
     id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -82,10 +154,59 @@ var SELECT_STREAM_INFO = `SELECT size_bytes, storage_backend, object_storage_key
 var DELETE_RETURNING = `DELETE FROM zerobucket_images WHERE id = $1 RETURNING storage_backend, object_storage_key;`;
 var DELETE_MANY = `DELETE FROM zerobucket_images WHERE id = ANY($1::uuid[]) RETURNING id, storage_backend, object_storage_key;`;
 var EXISTS = `SELECT 1 FROM zerobucket_images WHERE id = $1;`;
-var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-function isValidId(id) {
-  return typeof id === "string" && UUID_RE.test(id);
-}
+var SELECT_FOR_TIERING = `SELECT data, mime_type, size_bytes, storage_backend FROM zerobucket_images WHERE id = $1 FOR UPDATE;`;
+var UPDATE_AFTER_TIERING = `UPDATE zerobucket_images SET data = NULL, storage_backend = 'object_storage', object_storage_bucket = $1, object_storage_key = $2, updated_at = now() WHERE id = $3;`;
+var DEDUP_SCHEMA = `
+CREATE TABLE IF NOT EXISTS zerobucket_blobs (
+    checksum_sha256     CHAR(64) PRIMARY KEY,
+    data                BYTEA NOT NULL,
+    mime_type           TEXT NOT NULL,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    ref_count           INTEGER NOT NULL DEFAULT 0,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS zerobucket_image_refs (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    checksum_sha256     CHAR(64) NOT NULL REFERENCES zerobucket_blobs(checksum_sha256),
+    original_filename   TEXT,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_checksum ON zerobucket_image_refs (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_created_at ON zerobucket_image_refs (created_at);
+`;
+var D_UPSERT_BLOB = `
+INSERT INTO zerobucket_blobs (checksum_sha256, data, mime_type, size_bytes, width, height, ref_count)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
+ON CONFLICT (checksum_sha256) DO UPDATE SET ref_count = zerobucket_blobs.ref_count + EXCLUDED.ref_count;`;
+var D_INSERT_REF = `INSERT INTO zerobucket_image_refs (checksum_sha256, original_filename) VALUES ($1, $2) RETURNING id;`;
+var D_COLS = `r.id, b.data, b.mime_type, r.original_filename, b.size_bytes, b.width, b.height, r.checksum_sha256,
+       'postgres'::text AS storage_backend, NULL::text AS object_storage_bucket, NULL::text AS object_storage_key`;
+var D_FROM = `FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256`;
+var D_DELETE_REF = `DELETE FROM zerobucket_image_refs WHERE id = $1 RETURNING checksum_sha256;`;
+var D_DELETE_REFS = `DELETE FROM zerobucket_image_refs WHERE id = ANY($1::uuid[]) RETURNING id, checksum_sha256;`;
+var D_DECREMENT = `UPDATE zerobucket_blobs SET ref_count = ref_count - $1 WHERE checksum_sha256 = $2 RETURNING ref_count;`;
+var D_DELETE_EMPTY = `DELETE FROM zerobucket_blobs WHERE checksum_sha256 = ANY($1::text[]) AND ref_count <= 0;`;
+var CLASSIC_SQL = {
+  schema: SCHEMA,
+  selectFull: SELECT_FULL,
+  selectMany: SELECT_MANY,
+  selectMetadata: SELECT_METADATA,
+  selectStreamInfo: SELECT_STREAM_INFO,
+  selectChunk: SELECT_CHUNK,
+  exists: EXISTS
+};
+var DEDUP_SQL = {
+  schema: DEDUP_SCHEMA,
+  selectFull: `SELECT ${D_COLS} ${D_FROM} WHERE r.id = $1;`,
+  selectMany: `SELECT ${D_COLS} ${D_FROM} WHERE r.id = ANY($1::uuid[]);`,
+  selectMetadata: `SELECT r.id, b.mime_type, r.original_filename, b.size_bytes, b.width, b.height, r.checksum_sha256 ${D_FROM} WHERE r.id = $1;`,
+  selectStreamInfo: `SELECT b.size_bytes, 'postgres'::text AS storage_backend, NULL::text AS object_storage_key ${D_FROM} WHERE r.id = $1;`,
+  selectChunk: `SELECT substring(b.data FROM $1::int FOR $2::int) AS chunk ${D_FROM} WHERE r.id = $3;`,
+  exists: `SELECT 1 FROM zerobucket_image_refs WHERE id = $1;`
+};
 var RETRYABLE_SQLSTATES = /* @__PURE__ */ new Set([
   "40001",
   // serialization_failure
@@ -156,6 +277,13 @@ var PostgresBackend = class {
     this.maxRetries = opts.maxRetries ?? 3;
     this.retryBaseDelayMs = opts.retryBaseDelayMs ?? 100;
     this.autoMigrate = opts.autoMigrate ?? true;
+    this.dedup = opts.dedup ?? false;
+    if (this.dedup && opts.objectStorage) {
+      throw new TypeError(
+        "objectStorage is not supported together with dedup: true (same restriction as the Python package). Tiering moves one image's bytes, but a deduplicated blob can be shared by many images."
+      );
+    }
+    this.sql = this.dedup ? DEDUP_SQL : CLASSIC_SQL;
   }
   opts;
   pool;
@@ -165,6 +293,8 @@ var PostgresBackend = class {
   maxRetries;
   retryBaseDelayMs;
   autoMigrate;
+  dedup;
+  sql;
   // ---- lifecycle -------------------------------------------------------
   ready() {
     if (this.closed)
@@ -229,7 +359,7 @@ var PostgresBackend = class {
       await client.query(
         "SELECT pg_advisory_xact_lock(hashtext('zerobucket_migrate'))"
       );
-      await client.query(SCHEMA);
+      await client.query(this.sql.schema);
       await client.query("COMMIT");
       client.release();
     } catch (exc) {
@@ -262,123 +392,1029 @@ var PostgresBackend = class {
     }
   }
   /**
-   * Run `work` and return its result, emitting exactly one OperationEvent.
-   *
-   * connection given  -> run once on it, no BEGIN/COMMIT, no retry.
-   * connection absent -> pooled; `tx` wraps the work in BEGIN/COMMIT; transient
-   *                      failures retry the WHOLE closure on a fresh connection.
+   * Run `work` and return its result, emitting exactly one OperationEvent.
+   *
+   * connection given  -> run once on it, no BEGIN/COMMIT, no retry.
+   * connection absent -> pooled; `tx` wraps the work in BEGIN/COMMIT; transient
+   *                      failures retry the WHOLE closure on a fresh connection.
+   */
+  async run(operation, connection, work, { tx = false } = {}) {
+    if (connection) {
+      if (!isQueryable(connection)) {
+        throw new TypeError(
+          "PostgresBackend expects a pg client/pool client as `connection` (an object with query()), not a SQLite Database."
+        );
+      }
+      const start2 = performance.now();
+      try {
+        const result = tx ? await this.atomic(connection, work) : await work(connection);
+        this.emit(operation, start2, true, null, 0);
+        return result;
+      } catch (exc) {
+        this.emit(operation, start2, false, msg(exc), 0);
+        throw exc;
+      }
+    }
+    await this.ready();
+    const start = performance.now();
+    let attempt = 0;
+    for (; ; ) {
+      let client;
+      let destroy = false;
+      try {
+        client = await this.pool.connect();
+        if (tx) await client.query("BEGIN");
+        const result = await work(client);
+        if (tx) await client.query("COMMIT");
+        this.emit(operation, start, true, null, attempt);
+        return result;
+      } catch (exc) {
+        if (client && tx) {
+          try {
+            await client.query("ROLLBACK");
+          } catch {
+            destroy = true;
+          }
+        }
+        if (isConnectionLevel(exc)) destroy = true;
+        attempt += 1;
+        if (attempt > this.maxRetries || !isRetryable(exc)) {
+          this.emit(operation, start, false, msg(exc), attempt - 1);
+          throw exc;
+        }
+      } finally {
+        client?.release(destroy);
+      }
+      await sleep(backoffDelayMs(attempt, this.retryBaseDelayMs));
+    }
+  }
+  /**
+   * Make multi-statement work all-or-nothing on a CALLER-supplied connection.
+   *  - Caller has an open transaction -> SAVEPOINT: a failure rolls back only our work and the
+   *    caller's transaction stays usable; success joins their transaction.
+   *  - No open transaction (an autocommit pg.Client) -> open and commit our own, so a failure
+   *    can never leave half-applied state (e.g. an inflated dedup ref_count).
+   */
+  async atomic(conn, work) {
+    let ownTx = false;
+    try {
+      await conn.query("SAVEPOINT zerobucket_atomic");
+    } catch (exc) {
+      if (exc.code !== "25P01") throw exc;
+      ownTx = true;
+      await conn.query("BEGIN");
+    }
+    try {
+      const result = await work(conn);
+      await conn.query(
+        ownTx ? "COMMIT" : "RELEASE SAVEPOINT zerobucket_atomic"
+      );
+      return result;
+    } catch (exc) {
+      try {
+        await conn.query(
+          ownTx ? "ROLLBACK" : "ROLLBACK TO SAVEPOINT zerobucket_atomic"
+        );
+      } catch {
+      }
+      throw exc;
+    }
+  }
+  // ---- StorageBackend --------------------------------------------------
+  async put(row, { connection } = {}) {
+    try {
+      if (this.dedup) {
+        return await this.run(
+          "put",
+          connection,
+          async (q) => {
+            await q.query(D_UPSERT_BLOB, blobParams(row, 1));
+            return String(
+              (await q.query(D_INSERT_REF, [
+                row.checksumSha256,
+                row.originalFilename
+              ])).rows[0].id
+            );
+          },
+          { tx: true }
+        );
+      }
+      return await this.run("put", connection, async (q) => {
+        const res = await q.query(INSERT, rowParams(row));
+        return String(res.rows[0].id);
+      });
+    } catch (exc) {
+      throw wrap("Failed to store image", exc);
+    }
+  }
+  async putMany(rows, { connection } = {}) {
+    if (rows.length === 0) return [];
+    try {
+      if (this.dedup) {
+        return await this.run(
+          "put_many",
+          connection,
+          async (q) => {
+            const groups = /* @__PURE__ */ new Map();
+            for (const r of rows) {
+              const g = groups.get(r.checksumSha256);
+              if (g) g.n += 1;
+              else groups.set(r.checksumSha256, { row: r, n: 1 });
+            }
+            for (const checksum of [...groups.keys()].sort()) {
+              const g = groups.get(checksum);
+              await q.query(D_UPSERT_BLOB, blobParams(g.row, g.n));
+            }
+            const ids = [];
+            for (const r of rows) {
+              ids.push(
+                String(
+                  (await q.query(D_INSERT_REF, [
+                    r.checksumSha256,
+                    r.originalFilename
+                  ])).rows[0].id
+                )
+              );
+            }
+            return ids;
+          },
+          { tx: true }
+        );
+      }
+      return await this.run(
+        "put_many",
+        connection,
+        async (q) => {
+          const ids = [];
+          for (const r of rows)
+            ids.push(String((await q.query(INSERT, rowParams(r))).rows[0].id));
+          return ids;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to store image batch", exc);
+    }
+  }
+  async get(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    let row;
+    try {
+      row = await this.run(
+        "get",
+        connection,
+        async (q) => (await q.query(this.sql.selectFull, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image", exc);
+    }
+    return row ? this.hydrate(row, id) : null;
+  }
+  async getMany(ids, { connection } = {}) {
+    const valid = ids.filter(isValidId);
+    if (valid.length === 0) return [];
+    let rows;
+    try {
+      rows = await this.run(
+        "get_many",
+        connection,
+        async (q) => (await q.query(this.sql.selectMany, [valid])).rows
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image batch", exc);
+    }
+    return mapLimit(rows, 4, (r) => this.hydrate(r, String(r.id)));
+  }
+  async getMetadata(id, { connection } = {}) {
+    if (!isValidId(id)) return null;
+    let row;
+    try {
+      row = await this.run(
+        "get_metadata",
+        connection,
+        async (q) => (await q.query(this.sql.selectMetadata, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!row) return null;
+    return {
+      id: String(row.id),
+      mimeType: row.mime_type,
+      originalFilename: row.original_filename,
+      sizeBytes: row.size_bytes,
+      width: row.width,
+      height: row.height,
+      checksumSha256: row.checksum_sha256
+    };
+  }
+  async getStream(id, opts) {
+    if (!isValidId(id)) return null;
+    const { connection, chunkSize } = opts;
+    if (!Number.isInteger(chunkSize) || chunkSize <= 0)
+      throw new RangeError("chunkSize must be a positive integer");
+    let info;
+    try {
+      info = await this.run(
+        "get_metadata",
+        connection,
+        async (q) => (await q.query(this.sql.selectStreamInfo, [id])).rows[0]
+      );
+    } catch (exc) {
+      throw wrap("Failed to retrieve image metadata", exc);
+    }
+    if (!info) return null;
+    const totalSize = info.size_bytes;
+    const start = opts.range?.start ?? 0;
+    const end = Math.min(opts.range?.end ?? totalSize - 1, totalSize - 1);
+    if (info.storage_backend === "object_storage") {
+      const os = this.opts.objectStorage;
+      if (!os) throw tieredWithoutStorage(id, info.object_storage_key);
+      return streamFromObjectStorage(
+        os,
+        id,
+        info.object_storage_key,
+        start,
+        end,
+        chunkSize
+      );
+    }
+    const self = this;
+    async function* generate() {
+      let offset = start;
+      let delivered = 0;
+      const wanted = Math.max(0, end - start + 1);
+      while (delivered < wanted) {
+        const length = Math.min(chunkSize, wanted - delivered);
+        let row;
+        try {
+          row = await self.run(
+            "get_stream",
+            connection,
+            async (q) => (await q.query(self.sql.selectChunk, [offset + 1, length, id])).rows[0]
+          );
+        } catch (exc) {
+          throw wrap("Failed to stream image", exc);
+        }
+        if (!row) {
+          throw new StorageError(
+            `Image ${JSON.stringify(id)} was deleted while streaming (delivered ${delivered} of ${wanted} bytes). Pass connection with your own open transaction if you need a consistent read across concurrent writers.`
+          );
+        }
+        const chunk = row.chunk;
+        if (!chunk || chunk.length === 0) {
+          throw new StorageError(
+            `Image ${JSON.stringify(id)} ended early while streaming (delivered ${delivered} of ${wanted} bytes).`
+          );
+        }
+        yield chunk;
+        offset += chunk.length;
+        delivered += chunk.length;
+      }
+    }
+    return generate();
+  }
+  async delete(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    if (this.dedup) return this.deleteDedup(id, connection);
+    try {
+      const row = await this.run(
+        "delete",
+        connection,
+        async (q) => (await q.query(DELETE_RETURNING, [id])).rows[0]
+      );
+      if (row?.storage_backend === "object_storage")
+        await this.cleanupObject([row.object_storage_key], connection);
+      return row !== void 0;
+    } catch (exc) {
+      throw wrap("Failed to delete image", exc);
+    }
+  }
+  async deleteMany(ids, { connection } = {}) {
+    const valid = ids.filter(isValidId);
+    if (valid.length === 0) return [];
+    if (this.dedup) return this.deleteManyDedup(valid, connection);
+    try {
+      const rows = await this.run(
+        "delete_many",
+        connection,
+        async (q) => (await q.query(DELETE_MANY, [valid])).rows
+      );
+      await this.cleanupObject(
+        rows.filter((r) => r.storage_backend === "object_storage").map((r) => r.object_storage_key),
+        connection
+      );
+      return rows.map((r) => String(r.id));
+    } catch (exc) {
+      throw wrap("Failed to delete image batch", exc);
+    }
+  }
+  async exists(id, { connection } = {}) {
+    if (!isValidId(id)) return false;
+    try {
+      return await this.run(
+        "exists",
+        connection,
+        async (q) => ((await q.query(this.sql.exists, [id])).rowCount ?? 0) > 0
+      );
+    } catch (exc) {
+      throw wrap("Failed to check image existence", exc);
+    }
+  }
+  // ---- dedup deletes / migration ---------------------------------------
+  async deleteDedup(id, connection) {
+    try {
+      return await this.run(
+        "delete",
+        connection,
+        async (q) => {
+          const ref = (await q.query(D_DELETE_REF, [id])).rows[0];
+          if (!ref) return false;
+          const checksum = ref.checksum_sha256;
+          const dec = (await q.query(D_DECREMENT, [1, checksum])).rows[0];
+          if (dec && dec.ref_count <= 0)
+            await q.query(D_DELETE_EMPTY, [[checksum]]);
+          return true;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to delete image", exc);
+    }
+  }
+  async deleteManyDedup(ids, connection) {
+    try {
+      return await this.run(
+        "delete_many",
+        connection,
+        async (q) => {
+          const deleted = (await q.query(D_DELETE_REFS, [ids])).rows;
+          if (deleted.length === 0) return [];
+          const counts = /* @__PURE__ */ new Map();
+          for (const r of deleted)
+            counts.set(
+              r.checksum_sha256,
+              (counts.get(r.checksum_sha256) ?? 0) + 1
+            );
+          const emptied = [];
+          for (const checksum of [...counts.keys()].sort()) {
+            const dec = (await q.query(D_DECREMENT, [counts.get(checksum), checksum])).rows[0];
+            if (dec && dec.ref_count <= 0) emptied.push(checksum);
+          }
+          if (emptied.length > 0) await q.query(D_DELETE_EMPTY, [emptied]);
+          return deleted.map((r) => String(r.id));
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to delete image batch", exc);
+    }
+  }
+  /**
+   * One-time, NON-DESTRUCTIVE copy of every row in the classic `zerobucket_images` table into this
+   * dedup instance's tables, preserving every id (external references keep working) and
+   * deduplicating identical content on the way. The classic table is never modified.
+   *
+   * Differences from the Python version, all deliberate: rows are copied in small batches (bounded
+   * memory instead of loading the whole table); re-running is safe (already-migrated ids are
+   * skipped and reported, not an error); and classic rows already tiered to object storage are
+   * refused up front with a clear message (their bytes are not in the database to copy).
+   * Still all-or-nothing: one transaction.
+   */
+  async migrateClassicToDedup() {
+    if (!this.dedup) {
+      throw new StorageError(
+        "migrateClassicToDedup() must be called on an instance created with dedup: true."
+      );
+    }
+    await this.ready();
+    const client = await this.pool.connect();
+    let destroy = false;
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtext('zerobucket_migrate_dedup'))"
+      );
+      if (!(await client.query("SELECT to_regclass('zerobucket_images') AS t")).rows[0].t) {
+        throw new StorageError(
+          "No classic zerobucket_images table found in this database -- nothing to migrate."
+        );
+      }
+      const hasTierCol = (await client.query(
+        "SELECT 1 FROM information_schema.columns WHERE table_name = 'zerobucket_images' AND column_name = 'storage_backend'"
+      )).rowCount;
+      if (hasTierCol) {
+        const tiered = (await client.query(
+          "SELECT count(*)::int AS n FROM zerobucket_images WHERE storage_backend <> 'postgres'"
+        )).rows[0].n;
+        if (tiered > 0) {
+          throw new StorageError(
+            `${tiered} classic image(s) are tiered to object storage, so their bytes are not in the database to migrate. Dedup mode does not support tiering. Migrate only an un-tiered table, or bring those images back first.`
+          );
+        }
+      }
+      const seen = /* @__PURE__ */ new Set();
+      let migrated = 0;
+      let already = 0;
+      let cursor = null;
+      const BATCH = 20;
+      for (; ; ) {
+        const page = cursor ? await client.query(
+          `SELECT id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at::text AS created_at_txt
+               FROM zerobucket_images WHERE (created_at, id) > ($1::timestamptz, $2::uuid) ORDER BY created_at, id LIMIT ${BATCH}`,
+          [cursor.createdAt, cursor.id]
+        ) : await client.query(
+          `SELECT id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at::text AS created_at_txt
+               FROM zerobucket_images ORDER BY created_at, id LIMIT ${BATCH}`
+        );
+        if (page.rows.length === 0) break;
+        const last = page.rows[page.rows.length - 1];
+        if (cursor && cursor.createdAt === last.created_at_txt && cursor.id === last.id) {
+          throw new StorageError(
+            "Migration made no progress (keyset cursor did not advance); aborting instead of looping."
+          );
+        }
+        cursor = { createdAt: last.created_at_txt, id: last.id };
+        const have = new Set(
+          (await client.query(
+            "SELECT id FROM zerobucket_image_refs WHERE id = ANY($1::uuid[])",
+            [page.rows.map((r) => r.id)]
+          )).rows.map((r) => String(r.id))
+        );
+        const fresh = page.rows.filter((r) => !have.has(String(r.id)));
+        already += page.rows.length - fresh.length;
+        const groups = /* @__PURE__ */ new Map();
+        for (const r of fresh) {
+          const g = groups.get(r.checksum_sha256);
+          if (g) g.n += 1;
+          else groups.set(r.checksum_sha256, { row: r, n: 1 });
+        }
+        for (const checksum of [...groups.keys()].sort()) {
+          const { row, n } = groups.get(checksum);
+          await client.query(D_UPSERT_BLOB, [
+            checksum,
+            row.data,
+            row.mime_type,
+            row.size_bytes,
+            row.width,
+            row.height,
+            n
+          ]);
+        }
+        for (const r of fresh) {
+          await client.query(
+            "INSERT INTO zerobucket_image_refs (id, checksum_sha256, original_filename, created_at) VALUES ($1, $2, $3, $4::timestamptz)",
+            [r.id, r.checksum_sha256, r.original_filename, r.created_at_txt]
+          );
+          seen.add(r.checksum_sha256);
+          migrated += 1;
+        }
+      }
+      await client.query("COMMIT");
+      return {
+        imagesMigrated: migrated,
+        distinctBlobsCreated: seen.size,
+        duplicateReferencesFound: migrated - seen.size,
+        alreadyMigrated: already
+      };
+    } catch (exc) {
+      try {
+        await client.query("ROLLBACK");
+      } catch {
+        destroy = true;
+      }
+      throw exc instanceof StorageError ? exc : new StorageError(`Migration to dedup failed: ${msg(exc)}`, {
+        cause: exc
+      });
+    } finally {
+      client.release(destroy);
+    }
+  }
+  // ---- helpers ---------------------------------------------------------
+  hydrate(row, id) {
+    return hydrateRow(row, id, this.opts.objectStorage);
+  }
+  /**
+   * Remove tiered objects AFTER their rows are gone. Ordering is deliberate:
+   * once the row is deleted the image is correctly "not found" to everyone, so
+   * a failed object delete only leaves a harmless orphan, whereas deleting the
+   * object first and then failing the row delete would leave a row pointing at nothing.
+   *
+   * Never runs inside a caller-owned transaction (`connection`): we cannot know
+   * whether it will commit, and destroying data before the commit outcome is known
+   * could leave a rolled-back row pointing at a deleted object. In that case the
+   * object stays until you remove it yourself after committing (objectStorage.delete(id)).
+   * Failures are reported through onOperation and never fail the delete itself.
+   */
+  async cleanupObject(keys, connection) {
+    const os = this.opts.objectStorage;
+    if (!os || connection || keys.length === 0) return;
+    await Promise.all(
+      keys.map(async (key) => {
+        const start = performance.now();
+        try {
+          await os.delete(key);
+          this.emit("object_storage_delete", start, true, null, 0);
+        } catch (exc) {
+          this.emit("object_storage_delete", start, false, msg(exc), 0);
+        }
+      })
+    );
+  }
+  /**
+   * Move an image's bytes out of Postgres into object storage, replacing the
+   * row's `data` with a pointer. Returns:
+   *   null  - no such image
+   *   false - already tiered (a safe no-op, so backfills can be re-run)
+   *   true  - tiered just now
+   *
+   * SAFETY: the upload happens INSIDE the same transaction as the row lock
+   * (SELECT ... FOR UPDATE) and the UPDATE that flips the row. If the upload
+   * fails, the transaction rolls back and the row is untouched: there is no
+   * moment when the bytes exist nowhere, or when a row claims to be tiered
+   * without a completed upload.
+   *
+   * TRADEOFF: the row lock is held for the whole upload. Concurrent writes
+   * to THIS image (delete, tier) wait; every other row is unaffected, and plain
+   * reads are never blocked (Postgres MVCC). Meant for explicit maintenance, not hot paths.
+   *
+   * Retry is safe: a transient error replays the whole closure, and the
+   * deterministic key (the image id) makes the re-upload an idempotent overwrite.
+   */
+  async tierToObjectStorage(id, { connection } = {}) {
+    if (this.dedup) {
+      throw new StorageError(
+        "tierToObjectStorage() is not supported in dedup mode (a blob may be shared by many images)."
+      );
+    }
+    const os = this.opts.objectStorage;
+    if (!os) {
+      throw new StorageError(
+        "tierToObjectStorage() requires objectStorage to be configured (new ZeroBucket({ objectStorage: new ObjectStorage({ bucket }) }))."
+      );
+    }
+    if (!isValidId(id)) return null;
+    const key = id.toLowerCase();
+    try {
+      return await this.run(
+        "tier_to_object_storage",
+        connection,
+        async (q) => {
+          const row = (await q.query(SELECT_FOR_TIERING, [id])).rows[0];
+          if (!row) return null;
+          if (row.storage_backend !== "postgres") return false;
+          await os.upload(key, row.data, { mimeType: row.mime_type });
+          await q.query(UPDATE_AFTER_TIERING, [os.bucket, key, id]);
+          return true;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to tier image to object storage", exc);
+    }
+  }
+};
+function blobParams(r, refs) {
+  return [
+    r.checksumSha256,
+    r.data,
+    r.mimeType,
+    r.sizeBytes,
+    r.width,
+    r.height,
+    refs
+  ];
+}
+function rowParams(r) {
+  return [
+    r.data,
+    r.mimeType,
+    r.originalFilename,
+    r.sizeBytes,
+    r.width,
+    r.height,
+    r.checksumSha256
+  ];
+}
+function isQueryable(c) {
+  return typeof c.query === "function";
+}
+
+// src/adapters/sqlite.ts
+import { randomUUID } from "crypto";
+var SCHEMA2 = `
+CREATE TABLE IF NOT EXISTS zerobucket_images (
+    id                  TEXT PRIMARY KEY,
+    data                BLOB,
+    mime_type           TEXT NOT NULL,
+    original_filename   TEXT,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    checksum_sha256     TEXT NOT NULL,
+    created_at          TEXT NOT NULL,
+    updated_at          TEXT NOT NULL,
+    storage_backend     TEXT NOT NULL DEFAULT 'sqlite',
+    object_storage_bucket TEXT,
+    object_storage_key  TEXT,
+    CHECK (
+        (storage_backend = 'sqlite'
+            AND data IS NOT NULL
+            AND object_storage_key IS NULL
+            AND object_storage_bucket IS NULL)
+        OR
+        (storage_backend = 'object_storage'
+            AND data IS NULL
+            AND object_storage_key IS NOT NULL
+            AND object_storage_bucket IS NOT NULL)
+    )
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_checksum ON zerobucket_images (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_created_at ON zerobucket_images (created_at);
+`;
+var DEDUP_SCHEMA2 = `
+CREATE TABLE IF NOT EXISTS zerobucket_blobs (
+    checksum_sha256     TEXT PRIMARY KEY,
+    data                BLOB NOT NULL,
+    mime_type           TEXT NOT NULL,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    ref_count           INTEGER NOT NULL DEFAULT 0,
+    created_at          TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS zerobucket_image_refs (
+    id                  TEXT PRIMARY KEY,
+    checksum_sha256     TEXT NOT NULL REFERENCES zerobucket_blobs(checksum_sha256),
+    original_filename   TEXT,
+    created_at          TEXT NOT NULL,
+    updated_at          TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_checksum ON zerobucket_image_refs (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_image_refs_created_at ON zerobucket_image_refs (created_at);
+`;
+var COLS = `id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, storage_backend, object_storage_bucket, object_storage_key`;
+var INSERT2 = `INSERT INTO zerobucket_images (id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+var SELECT_FULL2 = `SELECT ${COLS} FROM zerobucket_images WHERE id = ?`;
+var selectMany = (n) => `SELECT ${COLS} FROM zerobucket_images WHERE id IN (${placeholders(n)})`;
+var SELECT_METADATA2 = `SELECT id, mime_type, original_filename, size_bytes, width, height, checksum_sha256 FROM zerobucket_images WHERE id = ?`;
+var STREAM_INFO = `SELECT size_bytes, storage_backend, object_storage_key FROM zerobucket_images WHERE id = ?`;
+var CHUNK = `SELECT substr(data, ?, ?) AS chunk FROM zerobucket_images WHERE id = ?`;
+var EXISTS2 = `SELECT 1 FROM zerobucket_images WHERE id = ?`;
+var DELETE_ONE = `DELETE FROM zerobucket_images WHERE id = ? RETURNING storage_backend, object_storage_key`;
+var deleteMany = (n) => `DELETE FROM zerobucket_images WHERE id IN (${placeholders(n)}) RETURNING id, storage_backend, object_storage_key`;
+var SELECT_FOR_TIERING2 = `SELECT data, mime_type, size_bytes, storage_backend FROM zerobucket_images WHERE id = ?`;
+var UPDATE_AFTER_TIERING2 = `UPDATE zerobucket_images SET data = NULL, storage_backend = 'object_storage', object_storage_bucket = ?, object_storage_key = ?, updated_at = ? WHERE id = ?`;
+var D_FROM2 = `FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256`;
+var D_COLS2 = `r.id AS id, b.data AS data, b.mime_type AS mime_type, r.original_filename AS original_filename, b.size_bytes AS size_bytes, b.width AS width, b.height AS height, r.checksum_sha256 AS checksum_sha256, 'sqlite' AS storage_backend, NULL AS object_storage_bucket, NULL AS object_storage_key`;
+var D_UPSERT = `INSERT INTO zerobucket_blobs (checksum_sha256, data, mime_type, size_bytes, width, height, ref_count, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (checksum_sha256) DO UPDATE SET ref_count = ref_count + excluded.ref_count`;
+var D_INSERT_REF2 = `INSERT INTO zerobucket_image_refs (id, checksum_sha256, original_filename, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`;
+var D_SELECT_FULL = `SELECT ${D_COLS2} ${D_FROM2} WHERE r.id = ?`;
+var dSelectMany = (n) => `SELECT ${D_COLS2} ${D_FROM2} WHERE r.id IN (${placeholders(n)})`;
+var D_SELECT_METADATA = `SELECT r.id AS id, b.mime_type AS mime_type, r.original_filename AS original_filename, b.size_bytes AS size_bytes, b.width AS width, b.height AS height, r.checksum_sha256 AS checksum_sha256 ${D_FROM2} WHERE r.id = ?`;
+var D_STREAM_INFO = `SELECT b.size_bytes AS size_bytes, 'sqlite' AS storage_backend, NULL AS object_storage_key ${D_FROM2} WHERE r.id = ?`;
+var D_CHUNK = `SELECT substr(b.data, ?, ?) AS chunk ${D_FROM2} WHERE r.id = ?`;
+var D_EXISTS = `SELECT 1 FROM zerobucket_image_refs WHERE id = ?`;
+var D_DELETE_REF2 = `DELETE FROM zerobucket_image_refs WHERE id = ? RETURNING checksum_sha256`;
+var dDeleteRefs = (n) => `DELETE FROM zerobucket_image_refs WHERE id IN (${placeholders(n)}) RETURNING id, checksum_sha256`;
+var D_DECREMENT2 = `UPDATE zerobucket_blobs SET ref_count = ref_count - ? WHERE checksum_sha256 = ? RETURNING ref_count`;
+var D_DELETE_EMPTY2 = `DELETE FROM zerobucket_blobs WHERE checksum_sha256 = ? AND ref_count <= 0`;
+var IN_CHUNK = 500;
+var ATTEMPT_BUSY_MS = 25;
+var DEFAULT_BUSY_TIMEOUT_MS = 1e4;
+function placeholders(n) {
+  return Array.from({ length: n }, () => "?").join(", ");
+}
+function isoNow() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace("Z", "000+00:00");
+}
+function isBusy(exc) {
+  const code = exc?.code;
+  return typeof code === "string" && (code.startsWith("SQLITE_BUSY") || code.startsWith("SQLITE_LOCKED"));
+}
+var Mutex = class {
+  tail = Promise.resolve();
+  run(fn) {
+    const prev = this.tail;
+    let release;
+    this.tail = new Promise((r) => release = r);
+    return prev.then(fn).finally(release);
+  }
+};
+var SQLiteBackend = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.path)
+      throw new TypeError(
+        'SQLiteBackend requires a `path` (a file path or ":memory:")'
+      );
+    this.dedup = opts.dedup ?? false;
+    this.busyTimeoutMs = opts.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+    if (this.dedup && opts.objectStorage) {
+      throw new TypeError(
+        "objectStorage is not supported together with dedup: true (same restriction as the Python package). Tiering moves one image's bytes, but a deduplicated blob can be shared by many images."
+      );
+    }
+  }
+  opts;
+  db;
+  Database;
+  readyPromise;
+  closed = false;
+  dedup;
+  busyTimeoutMs;
+  writeLock = new Mutex();
+  // ---- lifecycle -------------------------------------------------------
+  ready() {
+    if (this.closed)
+      return Promise.reject(
+        new StorageError("This ZeroBucket instance has been closed")
+      );
+    this.readyPromise ??= this.init().catch((exc) => {
+      this.readyPromise = void 0;
+      throw exc;
+    });
+    return this.readyPromise;
+  }
+  async init() {
+    try {
+      const mod = await import("better-sqlite3");
+      this.Database = mod.default ?? mod;
+    } catch (cause) {
+      throw new StorageError(
+        "SQLiteBackend requires the 'better-sqlite3' package. Install it with: npm install better-sqlite3",
+        { cause }
+      );
+    }
+    const db = new this.Database(this.opts.path, { timeout: ATTEMPT_BUSY_MS });
+    try {
+      await this.retrying(() => {
+        if (this.opts.path !== ":memory:" && db.pragma("journal_mode", { simple: true }) !== "wal") {
+          db.pragma("journal_mode = WAL");
+        }
+        db.pragma("foreign_keys = ON");
+        if (this.opts.autoMigrate ?? true)
+          db.exec(this.dedup ? DEDUP_SCHEMA2 : SCHEMA2);
+      });
+    } catch (exc) {
+      try {
+        db.close();
+      } catch {
+      }
+      throw new StorageError(
+        `Could not open SQLite database ${JSON.stringify(this.opts.path)}: ${msg(exc)}`,
+        { cause: exc }
+      );
+    }
+    this.db = db;
+  }
+  async close() {
+    this.closed = true;
+    const db = this.db;
+    this.db = void 0;
+    this.readyPromise = void 0;
+    await this.writeLock.run(async () => {
+      db?.close();
+    });
+  }
+  // ---- execution core --------------------------------------------------
+  emit(operation, start, success, error, retryCount) {
+    const cb = this.opts.onOperation;
+    if (!cb) return;
+    try {
+      cb({
+        operation,
+        durationMs: performance.now() - start,
+        success,
+        error,
+        retryCount
+      });
+    } catch {
+    }
+  }
+  /** Re-run `fn` while another connection holds a lock, sleeping asynchronously between attempts. `fn` must be atomic. */
+  async retrying(fn, onRetry) {
+    const deadline = performance.now() + this.busyTimeoutMs;
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        return fn();
+      } catch (exc) {
+        if (!isBusy(exc) || performance.now() >= deadline) throw exc;
+        attempt += 1;
+        onRetry?.(attempt);
+        await sleep(
+          Math.min(5 * 2 ** Math.min(attempt, 5), 100) + Math.random() * 5
+        );
+      }
+    }
+  }
+  /** BEGIN IMMEDIATE takes the write lock up front, so a BUSY comes before any work and the whole unit is safely re-runnable. */
+  tx(db, work) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      const result = work(db);
+      db.exec("COMMIT");
+      return result;
+    } catch (exc) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+      }
+      throw exc;
+    }
+  }
+  /**
+   * All-or-nothing work on a CALLER-supplied handle. SAVEPOINT works whether or not the caller has an open
+   * transaction: inside one it nests (a failure rolls back only our work); outside one it begins and, on
+   * RELEASE, commits.
    */
-  async run(operation, connection, work, { tx = false } = {}) {
-    if (connection) {
-      const start2 = performance.now();
+  atomic(db, work) {
+    db.exec("SAVEPOINT zerobucket_atomic");
+    try {
+      const result = work(db);
+      db.exec("RELEASE SAVEPOINT zerobucket_atomic");
+      return result;
+    } catch (exc) {
       try {
-        const result = await work(connection);
-        this.emit(operation, start2, true, null, 0);
-        return result;
-      } catch (exc) {
-        this.emit(operation, start2, false, msg(exc), 0);
-        throw exc;
+        db.exec("ROLLBACK TO SAVEPOINT zerobucket_atomic");
+        db.exec("RELEASE SAVEPOINT zerobucket_atomic");
+      } catch {
       }
+      throw exc;
     }
-    await this.ready();
+  }
+  async execute(operation, connection, mode, work) {
     const start = performance.now();
-    let attempt = 0;
-    for (; ; ) {
-      let client;
-      let destroy = false;
-      try {
-        client = await this.pool.connect();
-        if (tx) await client.query("BEGIN");
-        const result = await work(client);
-        if (tx) await client.query("COMMIT");
-        this.emit(operation, start, true, null, attempt);
-        return result;
-      } catch (exc) {
-        if (client && tx) {
-          try {
-            await client.query("ROLLBACK");
-          } catch {
-            destroy = true;
-          }
-        }
-        if (isConnectionLevel(exc)) destroy = true;
-        attempt += 1;
-        if (attempt > this.maxRetries || !isRetryable(exc)) {
-          this.emit(operation, start, false, msg(exc), attempt - 1);
-          throw exc;
+    let retries = 0;
+    try {
+      let result;
+      if (connection) {
+        if (typeof connection.prepare !== "function") {
+          throw new TypeError(
+            "SQLiteBackend expects a better-sqlite3 Database as `connection` (an object with prepare()), not a pg client."
+          );
         }
-      } finally {
-        client?.release(destroy);
+        const db = connection;
+        result = mode === "write" ? this.atomic(db, work) : work(db);
+      } else {
+        await this.ready();
+        const db = this.db;
+        const onRetry = (n) => retries = n;
+        result = mode === "write" ? await this.writeLock.run(
+          () => this.retrying(() => this.tx(db, work), onRetry)
+        ) : await this.retrying(() => work(db), onRetry);
       }
-      await sleep(backoffDelayMs(attempt, this.retryBaseDelayMs));
+      this.emit(operation, start, true, null, retries);
+      return result;
+    } catch (exc) {
+      this.emit(operation, start, false, msg(exc), retries);
+      throw exc;
     }
   }
   // ---- StorageBackend --------------------------------------------------
   async put(row, { connection } = {}) {
     try {
-      return await this.run("put", connection, async (q) => {
-        const res = await q.query(INSERT, rowParams(row));
-        return String(res.rows[0].id);
-      });
+      return await this.execute(
+        "put",
+        connection,
+        "write",
+        (db) => this.insertOne(db, row)
+      );
     } catch (exc) {
       throw wrap("Failed to store image", exc);
     }
   }
+  insertOne(db, r) {
+    const id = randomUUID();
+    const now = isoNow();
+    if (this.dedup) {
+      db.prepare(D_UPSERT).run(
+        r.checksumSha256,
+        r.data,
+        r.mimeType,
+        r.sizeBytes,
+        r.width,
+        r.height,
+        1,
+        now
+      );
+      db.prepare(D_INSERT_REF2).run(
+        id,
+        r.checksumSha256,
+        r.originalFilename,
+        now,
+        now
+      );
+    } else {
+      db.prepare(INSERT2).run(
+        id,
+        r.data,
+        r.mimeType,
+        r.originalFilename,
+        r.sizeBytes,
+        r.width,
+        r.height,
+        r.checksumSha256,
+        now,
+        now
+      );
+    }
+    return id;
+  }
   async putMany(rows, { connection } = {}) {
     if (rows.length === 0) return [];
     try {
-      return await this.run(
-        "put_many",
-        connection,
-        async (q) => {
-          const ids = [];
-          for (const r of rows)
-            ids.push(String((await q.query(INSERT, rowParams(r))).rows[0].id));
-          return ids;
-        },
-        { tx: true }
-      );
+      return await this.execute("put_many", connection, "write", (db) => {
+        if (!this.dedup) return rows.map((r) => this.insertOne(db, r));
+        const now = isoNow();
+        const groups = /* @__PURE__ */ new Map();
+        for (const r of rows) {
+          const g = groups.get(r.checksumSha256);
+          if (g) g.n += 1;
+          else groups.set(r.checksumSha256, { row: r, n: 1 });
+        }
+        for (const [checksum, { row, n }] of groups) {
+          db.prepare(D_UPSERT).run(
+            checksum,
+            row.data,
+            row.mimeType,
+            row.sizeBytes,
+            row.width,
+            row.height,
+            n,
+            now
+          );
+        }
+        return rows.map((r) => {
+          const id = randomUUID();
+          db.prepare(D_INSERT_REF2).run(
+            id,
+            r.checksumSha256,
+            r.originalFilename,
+            now,
+            now
+          );
+          return id;
+        });
+      });
     } catch (exc) {
       throw wrap("Failed to store image batch", exc);
     }
   }
   async get(id, { connection } = {}) {
     if (!isValidId(id)) return null;
+    const norm = id.toLowerCase();
     let row;
     try {
-      row = await this.run(
+      row = await this.execute(
         "get",
         connection,
-        async (q) => (await q.query(SELECT_FULL, [id])).rows[0]
+        "read",
+        (db) => db.prepare(this.dedup ? D_SELECT_FULL : SELECT_FULL2).get(norm)
       );
     } catch (exc) {
       throw wrap("Failed to retrieve image", exc);
     }
-    return row ? this.toRecord(row, id) : null;
+    return row ? hydrateRow(row, norm, this.opts.objectStorage) : null;
   }
   async getMany(ids, { connection } = {}) {
-    const valid = ids.filter(isValidId);
+    const valid = [
+      ...new Set(ids.filter(isValidId).map((i) => i.toLowerCase()))
+    ];
     if (valid.length === 0) return [];
     let rows;
     try {
-      rows = await this.run(
-        "get_many",
-        connection,
-        async (q) => (await q.query(SELECT_MANY, [valid])).rows
-      );
+      rows = await this.execute("get_many", connection, "read", (db) => {
+        const out = [];
+        for (let i = 0; i < valid.length; i += IN_CHUNK) {
+          const part = valid.slice(i, i + IN_CHUNK);
+          out.push(
+            ...db.prepare(
+              this.dedup ? dSelectMany(part.length) : selectMany(part.length)
+            ).all(...part)
+          );
+        }
+        return out;
+      });
     } catch (exc) {
       throw wrap("Failed to retrieve image batch", exc);
     }
-    return rows.map((r) => this.toRecord(r, String(r.id)));
+    return mapLimit(
+      rows,
+      4,
+      (r) => hydrateRow(r, String(r.id), this.opts.objectStorage)
+    );
   }
   async getMetadata(id, { connection } = {}) {
     if (!isValidId(id)) return null;
     let row;
     try {
-      row = await this.run(
+      row = await this.execute(
         "get_metadata",
         connection,
-        async (q) => (await q.query(SELECT_METADATA, [id])).rows[0]
+        "read",
+        (db) => db.prepare(this.dedup ? D_SELECT_METADATA : SELECT_METADATA2).get(id.toLowerCase())
       );
     } catch (exc) {
       throw wrap("Failed to retrieve image metadata", exc);
@@ -396,25 +1432,37 @@ var PostgresBackend = class {
   }
   async getStream(id, opts) {
     if (!isValidId(id)) return null;
+    const norm = id.toLowerCase();
     const { connection, chunkSize } = opts;
     if (!Number.isInteger(chunkSize) || chunkSize <= 0)
       throw new RangeError("chunkSize must be a positive integer");
     let info;
     try {
-      info = await this.run(
+      info = await this.execute(
         "get_metadata",
         connection,
-        async (q) => (await q.query(SELECT_STREAM_INFO, [id])).rows[0]
+        "read",
+        (db) => db.prepare(this.dedup ? D_STREAM_INFO : STREAM_INFO).get(norm)
       );
     } catch (exc) {
       throw wrap("Failed to retrieve image metadata", exc);
     }
     if (!info) return null;
-    if (info.storage_backend === "object_storage")
-      throw this.tieredWithoutStorage(id, info.object_storage_key);
     const totalSize = info.size_bytes;
     const start = opts.range?.start ?? 0;
     const end = Math.min(opts.range?.end ?? totalSize - 1, totalSize - 1);
+    if (info.storage_backend === "object_storage") {
+      const os = this.opts.objectStorage;
+      if (!os) throw tieredWithoutStorage(norm, info.object_storage_key);
+      return streamFromObjectStorage(
+        os,
+        norm,
+        info.object_storage_key,
+        start,
+        end,
+        chunkSize
+      );
+    }
     const self = this;
     async function* generate() {
       let offset = start;
@@ -424,23 +1472,24 @@ var PostgresBackend = class {
         const length = Math.min(chunkSize, wanted - delivered);
         let row;
         try {
-          row = await self.run(
+          row = await self.execute(
             "get_stream",
             connection,
-            async (q) => (await q.query(SELECT_CHUNK, [offset + 1, length, id])).rows[0]
+            "read",
+            (db) => db.prepare(self.dedup ? D_CHUNK : CHUNK).get(offset + 1, length, norm)
           );
         } catch (exc) {
           throw wrap("Failed to stream image", exc);
         }
         if (!row) {
           throw new StorageError(
-            `Image ${JSON.stringify(id)} was deleted while streaming (delivered ${delivered} of ${wanted} bytes). Pass connection with your own open transaction if you need a consistent read across concurrent writers.`
+            `Image ${JSON.stringify(norm)} was deleted while streaming (delivered ${delivered} of ${wanted} bytes). Pass connection with your own open transaction if you need a consistent read across concurrent writers.`
           );
         }
         const chunk = row.chunk;
         if (!chunk || chunk.length === 0) {
           throw new StorageError(
-            `Image ${JSON.stringify(id)} ended early while streaming (delivered ${delivered} of ${wanted} bytes).`
+            `Image ${JSON.stringify(norm)} ended early while streaming (delivered ${delivered} of ${wanted} bytes).`
           );
         }
         yield chunk;
@@ -452,25 +1501,74 @@ var PostgresBackend = class {
   }
   async delete(id, { connection } = {}) {
     if (!isValidId(id)) return false;
+    const norm = id.toLowerCase();
     try {
-      const row = await this.run(
+      if (this.dedup) {
+        return await this.execute("delete", connection, "write", (db) => {
+          const ref = db.prepare(D_DELETE_REF2).get(norm);
+          if (!ref) return false;
+          const dec = db.prepare(D_DECREMENT2).get(1, ref.checksum_sha256);
+          if (dec && dec.ref_count <= 0)
+            db.prepare(D_DELETE_EMPTY2).run(ref.checksum_sha256);
+          return true;
+        });
+      }
+      const row = await this.execute(
         "delete",
         connection,
-        async (q) => (await q.query(DELETE_RETURNING, [id])).rows[0]
+        "write",
+        (db) => db.prepare(DELETE_ONE).get(norm)
       );
+      if (row?.storage_backend === "object_storage")
+        await this.cleanupObjects([row.object_storage_key], connection);
       return row !== void 0;
     } catch (exc) {
       throw wrap("Failed to delete image", exc);
     }
   }
   async deleteMany(ids, { connection } = {}) {
-    const valid = ids.filter(isValidId);
+    const valid = [
+      ...new Set(ids.filter(isValidId).map((i) => i.toLowerCase()))
+    ];
     if (valid.length === 0) return [];
     try {
-      const rows = await this.run(
+      if (this.dedup) {
+        return await this.execute("delete_many", connection, "write", (db) => {
+          const deleted = [];
+          for (let i = 0; i < valid.length; i += IN_CHUNK) {
+            const part = valid.slice(i, i + IN_CHUNK);
+            deleted.push(...db.prepare(dDeleteRefs(part.length)).all(...part));
+          }
+          const counts = /* @__PURE__ */ new Map();
+          for (const r of deleted)
+            counts.set(
+              r.checksum_sha256,
+              (counts.get(r.checksum_sha256) ?? 0) + 1
+            );
+          for (const [checksum, n] of counts) {
+            const dec = db.prepare(D_DECREMENT2).get(n, checksum);
+            if (dec && dec.ref_count <= 0)
+              db.prepare(D_DELETE_EMPTY2).run(checksum);
+          }
+          return deleted.map((r) => String(r.id));
+        });
+      }
+      const rows = await this.execute(
         "delete_many",
         connection,
-        async (q) => (await q.query(DELETE_MANY, [valid])).rows
+        "write",
+        (db) => {
+          const out = [];
+          for (let i = 0; i < valid.length; i += IN_CHUNK) {
+            const part = valid.slice(i, i + IN_CHUNK);
+            out.push(...db.prepare(deleteMany(part.length)).all(...part));
+          }
+          return out;
+        }
+      );
+      await this.cleanupObjects(
+        rows.filter((r) => r.storage_backend === "object_storage").map((r) => r.object_storage_key),
+        connection
       );
       return rows.map((r) => String(r.id));
     } catch (exc) {
@@ -480,56 +1578,116 @@ var PostgresBackend = class {
   async exists(id, { connection } = {}) {
     if (!isValidId(id)) return false;
     try {
-      return await this.run(
+      return await this.execute(
         "exists",
         connection,
-        async (q) => ((await q.query(EXISTS, [id])).rowCount ?? 0) > 0
+        "read",
+        (db) => db.prepare(this.dedup ? D_EXISTS : EXISTS2).get(id.toLowerCase()) !== void 0
       );
     } catch (exc) {
       throw wrap("Failed to check image existence", exc);
     }
   }
-  // ---- helpers ---------------------------------------------------------
-  toRecord(row, id) {
-    if (row.storage_backend === "object_storage")
-      throw this.tieredWithoutStorage(id, row.object_storage_key);
-    return {
-      id: String(row.id),
-      data: row.data,
-      mimeType: row.mime_type,
-      originalFilename: row.original_filename,
-      sizeBytes: row.size_bytes,
-      width: row.width,
-      height: row.height,
-      checksumSha256: row.checksum_sha256
-    };
-  }
-  tieredWithoutStorage(id, key) {
-    return new StorageError(
-      `Image ${JSON.stringify(id)} is stored in object storage (key=${JSON.stringify(key)}) but object-storage tiering is not available in this version of the npm package yet. Read it from the Python package (configured with the same bucket), or wait for npm tiering support.`
+  /**
+   * Remove tiered objects AFTER their rows are gone (a failed object delete leaves a harmless orphan; the
+   * reverse order could leave a row pointing at nothing). Skipped inside a caller-owned transaction, since the
+   * commit outcome is unknown. Failures never fail the delete; they are reported through onOperation.
+   */
+  async cleanupObjects(keys, connection) {
+    const os = this.opts.objectStorage;
+    if (!os || connection || keys.length === 0) return;
+    await Promise.all(
+      keys.map(async (key) => {
+        const start = performance.now();
+        try {
+          await os.delete(key);
+          this.emit("object_storage_delete", start, true, null, 0);
+        } catch (exc) {
+          this.emit("object_storage_delete", start, false, msg(exc), 0);
+        }
+      })
     );
   }
+  /**
+   * Move an image's bytes into object storage. null = no such image, false = already tiered, true = tiered now.
+   *
+   * SAFETY (same guarantee as Postgres): the upload happens INSIDE a BEGIN IMMEDIATE transaction; if it fails the
+   * transaction rolls back and the row is untouched.
+   *
+   * TRADEOFF (coarser than Postgres): SQLite has no row locks, so BEGIN IMMEDIATE locks the WHOLE DATABASE for the
+   * upload. Other processes' writes wait; this process's writes queue behind an async lock; reads are not blocked.
+   */
+  async tierToObjectStorage(id, { connection } = {}) {
+    if (this.dedup)
+      throw new StorageError(
+        "tierToObjectStorage() is not supported in dedup mode (a blob may be shared by many images)."
+      );
+    const os = this.opts.objectStorage;
+    if (!os) {
+      throw new StorageError(
+        "tierToObjectStorage() requires objectStorage to be configured (new ZeroBucket({ sqlite, objectStorage: new ObjectStorage({ bucket }) }))."
+      );
+    }
+    if (connection) {
+      throw new StorageError(
+        "tierToObjectStorage() does not accept `connection` on SQLite: it needs its own dedicated connection for the BEGIN IMMEDIATE transaction."
+      );
+    }
+    if (this.opts.path === ":memory:") {
+      throw new StorageError(
+        "tierToObjectStorage() needs a database file: an in-memory SQLite database cannot be shared with its dedicated tiering connection."
+      );
+    }
+    if (!isValidId(id)) return null;
+    const norm = id.toLowerCase();
+    const start = performance.now();
+    let retries = 0;
+    try {
+      await this.ready();
+      const result = await this.writeLock.run(async () => {
+        const tdb = new this.Database(this.opts.path, {
+          timeout: ATTEMPT_BUSY_MS
+        });
+        try {
+          await this.retrying(
+            () => tdb.exec("BEGIN IMMEDIATE"),
+            (n) => retries = n
+          );
+          try {
+            const row = tdb.prepare(SELECT_FOR_TIERING2).get(norm);
+            if (!row) {
+              tdb.exec("ROLLBACK");
+              return null;
+            }
+            if (row.storage_backend !== "sqlite") {
+              tdb.exec("ROLLBACK");
+              return false;
+            }
+            await os.upload(norm, row.data, {
+              mimeType: row.mime_type
+            });
+            tdb.prepare(UPDATE_AFTER_TIERING2).run(os.bucket, norm, isoNow(), norm);
+            tdb.exec("COMMIT");
+            return true;
+          } catch (exc) {
+            try {
+              tdb.exec("ROLLBACK");
+            } catch {
+            }
+            throw exc;
+          }
+        } finally {
+          tdb.close();
+        }
+      });
+      this.emit("tier_to_object_storage", start, true, null, retries);
+      return result;
+    } catch (exc) {
+      this.emit("tier_to_object_storage", start, false, msg(exc), retries);
+      throw wrap("Failed to tier image to object storage", exc);
+    }
+  }
 };
-function rowParams(r) {
-  return [
-    r.data,
-    r.mimeType,
-    r.originalFilename,
-    r.sizeBytes,
-    r.width,
-    r.height,
-    r.checksumSha256
-  ];
-}
-function wrap(prefix, exc) {
-  return exc instanceof StorageError ? exc : new StorageError(`${prefix}: ${msg(exc)}`, { cause: exc });
-}
-function msg(exc) {
-  return exc instanceof Error ? exc.message : String(exc);
-}
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // src/validation.ts
 var FORMAT_TO_MIME = {
@@ -673,7 +1831,18 @@ var ZeroBucket = class _ZeroBucket {
   beforeGet;
   beforePut;
   constructor(options = {}) {
-    this.backend = options.backend ?? new PostgresBackend({
+    if (options.sqlite !== void 0 && (options.connectionString || options.pool)) {
+      throw new TypeError(
+        "Choose one database: `sqlite` OR `connectionString`/`pool`, not both."
+      );
+    }
+    this.backend = options.backend ?? (options.sqlite !== void 0 ? new SQLiteBackend({
+      path: options.sqlite,
+      autoMigrate: options.autoMigrate,
+      dedup: options.dedup,
+      objectStorage: options.objectStorage,
+      onOperation: options.onOperation
+    }) : new PostgresBackend({
       connectionString: options.connectionString,
       pool: options.pool,
       autoMigrate: options.autoMigrate,
@@ -682,8 +1851,10 @@ var ZeroBucket = class _ZeroBucket {
       poolMinSize: options.poolMinSize,
       poolMaxSize: options.poolMaxSize,
       poolTimeoutMs: options.poolTimeoutMs,
-      onOperation: options.onOperation
-    });
+      onOperation: options.onOperation,
+      objectStorage: options.objectStorage,
+      dedup: options.dedup
+    }));
     this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
     this.maxPixels = options.maxPixels ?? DEFAULT_MAX_PIXELS;
     this.allowedFormats = options.allowedFormats ?? SUPPORTED_FORMATS;
@@ -804,7 +1975,7 @@ var ZeroBucket = class _ZeroBucket {
     }
     const results = new Array(images.length);
     const prepared = [];
-    await mapLimit(images, PREPARE_CONCURRENCY, async (image, i) => {
+    await mapLimit2(images, PREPARE_CONCURRENCY, async (image, i) => {
       try {
         const row = await this.prepareRow(image, {
           ...options,
@@ -1020,6 +2191,32 @@ var ZeroBucket = class _ZeroBucket {
       success: true
     }));
   }
+  /**
+   * Move an image's bytes from Postgres into object storage; reads, streams and
+   * deletes keep working transparently. Returns true if tiered now, false if it was
+   * already tiered (safe to re-run in a backfill). Throws ImageNotFoundError if missing.
+   *
+   * The upload runs inside the database transaction: if it fails, the row is left
+   * completely untouched. Explicit and opt-in: put() never tiers automatically.
+   * Not gated by beforeGet/beforePut (it is a maintenance operation, as in the Python package).
+   */
+  async tierToObjectStorage(imageId, options = {}) {
+    const result = await this.backend.tierToObjectStorage(imageId, options);
+    if (result === null) throw new ImageNotFoundError(imageId);
+    return result;
+  }
+  /**
+   * One-time, non-destructive copy of classic-mode images into a dedup instance's tables, keeping every
+   * id. Call it on an instance created with `dedup: true`. Safe to re-run. See PostgresBackend for details.
+   */
+  async migrateClassicToDedup() {
+    if (!this.backend.migrateClassicToDedup) {
+      throw new StorageError(
+        "This backend does not support migrateClassicToDedup()."
+      );
+    }
+    return this.backend.migrateClassicToDedup();
+  }
   /** Release the pool (if ZeroBucket created it). */
   close() {
     return this.backend.close();
@@ -1073,7 +2270,7 @@ async function readInput(image, filename, maxBytes) {
     "Unsupported image input. Pass a Buffer, Uint8Array, file path string, Blob/File, or a readable stream."
   );
 }
-async function mapLimit(items, limit, fn) {
+async function mapLimit2(items, limit, fn) {
   let next = 0;
   const workers = Array.from(
     { length: Math.min(limit, items.length) },
@@ -1090,6 +2287,119 @@ function errText(exc) {
   return exc instanceof Error ? exc.message : String(exc);
 }
 
+// src/object-storage.ts
+var ObjectStorage = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.bucket)
+      throw new TypeError("ObjectStorage requires a bucket name");
+    this.bucket = opts.bucket;
+  }
+  opts;
+  bucket;
+  clientPromise;
+  connection() {
+    this.clientPromise ??= (async () => {
+      let sdk;
+      try {
+        sdk = await import("@aws-sdk/client-s3");
+      } catch (cause) {
+        throw new StorageError(
+          "Object-storage tiering requires the optional dependency '@aws-sdk/client-s3'. Install it with: npm install @aws-sdk/client-s3",
+          { cause }
+        );
+      }
+      const o = this.opts;
+      const client = o.client ?? new sdk.S3Client({
+        endpoint: o.endpoint,
+        region: o.region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1",
+        credentials: o.credentials,
+        forcePathStyle: o.forcePathStyle ?? o.endpoint !== void 0
+      });
+      return { sdk, client };
+    })().catch((exc) => {
+      this.clientPromise = void 0;
+      throw exc;
+    });
+    return this.clientPromise;
+  }
+  async upload(key, data, { mimeType }) {
+    const { sdk, client } = await this.connection();
+    try {
+      await client.send(
+        new sdk.PutObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Body: data,
+          ContentType: mimeType
+        })
+      );
+    } catch (exc) {
+      throw new StorageError(
+        `Failed to upload ${JSON.stringify(key)} to bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+  async download(key) {
+    return this.get(key, void 0);
+  }
+  async downloadRange(key, start, endInclusive) {
+    return this.get(key, `bytes=${start}-${endInclusive}`);
+  }
+  async get(key, range) {
+    const { sdk, client } = await this.connection();
+    try {
+      const res = await client.send(
+        new sdk.GetObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Range: range
+        })
+      );
+      return Buffer.from(await res.Body.transformToByteArray());
+    } catch (exc) {
+      throw new StorageError(
+        `Failed to download ${JSON.stringify(key)} from bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+  async delete(key) {
+    const { sdk, client } = await this.connection();
+    try {
+      await client.send(
+        new sdk.DeleteObjectCommand({ Bucket: this.bucket, Key: key })
+      );
+    } catch (exc) {
+      throw new StorageError(
+        `Failed to delete ${JSON.stringify(key)} from bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+  async exists(key) {
+    const { sdk, client } = await this.connection();
+    try {
+      await client.send(
+        new sdk.HeadObjectCommand({ Bucket: this.bucket, Key: key })
+      );
+      return true;
+    } catch (exc) {
+      const e = exc;
+      if (e.name === "NotFound" || e.name === "NoSuchKey" || e.$metadata?.httpStatusCode === 404)
+        return false;
+      throw new StorageError(
+        `Failed to check ${JSON.stringify(key)} in bucket ${JSON.stringify(this.bucket)}: ${msg2(exc)}`,
+        { cause: exc }
+      );
+    }
+  }
+};
+function msg2(exc) {
+  return exc instanceof Error ? exc.message : String(exc);
+}
+
 // src/validators/pdf.ts
 var DEFAULT_MAX_PDF_BYTES = 20 * 1024 * 1024;
 var PDFValidator = class {
@@ -1132,8 +2442,10 @@ export {
   ImageNotFoundError,
   ImageTooLargeError,
   ImageValidationError,
+  ObjectStorage,
   PDFValidator,
   PostgresBackend,
+  SQLiteBackend,
   SUPPORTED_FORMATS,
   StorageError,
   UnsupportedFormatError,