zerobucket 0.6.1 → 0.8.0

package/dist/index.js

@@ -1880,6 +1880,977 @@ var SQLiteBackend = class {
   }
 };
 
+// src/adapters/mysql.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var SCHEMA3 = `
+CREATE TABLE IF NOT EXISTS zerobucket_images (
+    id                  CHAR(36) PRIMARY KEY,
+    data                LONGBLOB NOT NULL,
+    mime_type           VARCHAR(255) NOT NULL,
+    original_filename   TEXT,
+    size_bytes          INT NOT NULL,
+    width               INT,
+    height              INT,
+    checksum_sha256     CHAR(64) NOT NULL,
+    created_at          DATETIME(6) NOT NULL,
+    updated_at          DATETIME(6) NOT NULL,
+    INDEX idx_zerobucket_checksum (checksum_sha256),
+    INDEX idx_zerobucket_created_at (created_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`;
+var TIERING_CHECK = "chk_zerobucket_storage";
+var MIGRATE_LOCK = "zerobucket_migrate";
+var COLS2 = `id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, storage_backend, object_storage_bucket, object_storage_key`;
+var INSERT3 = `INSERT INTO zerobucket_images (id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+var SELECT_FULL3 = `SELECT ${COLS2} FROM zerobucket_images WHERE id = ?`;
+var SELECT_MANY2 = `SELECT ${COLS2} FROM zerobucket_images WHERE id IN (?)`;
+var SELECT_METADATA3 = `SELECT id, mime_type, original_filename, size_bytes, width, height, checksum_sha256 FROM zerobucket_images WHERE id = ?`;
+var STREAM_INFO2 = `SELECT size_bytes, storage_backend, object_storage_key FROM zerobucket_images WHERE id = ?`;
+var CHUNK2 = `SELECT SUBSTRING(data FROM ? FOR ?) AS chunk FROM zerobucket_images WHERE id = ?`;
+var EXISTS3 = `SELECT 1 FROM zerobucket_images WHERE id = ?`;
+var LOCK_ONE = `SELECT storage_backend, object_storage_key FROM zerobucket_images WHERE id = ? FOR UPDATE`;
+var DELETE_ONE2 = `DELETE FROM zerobucket_images WHERE id = ?`;
+var LOCK_MANY = `SELECT id, storage_backend, object_storage_key FROM zerobucket_images FORCE INDEX (PRIMARY) WHERE id IN (?) ORDER BY id FOR UPDATE`;
+var SELECT_FOR_TIERING3 = `SELECT data, mime_type, size_bytes, storage_backend FROM zerobucket_images WHERE id = ? FOR UPDATE`;
+var UPDATE_AFTER_TIERING3 = `UPDATE zerobucket_images SET data = NULL, storage_backend = 'object_storage', object_storage_bucket = ?, object_storage_key = ?, updated_at = ? WHERE id = ?`;
+var LOCAL = "mysql";
+var DEDUP_BLOBS_SCHEMA = `
+CREATE TABLE IF NOT EXISTS zerobucket_blobs (
+    checksum_sha256     CHAR(64) PRIMARY KEY,
+    data                LONGBLOB NOT NULL,
+    mime_type           VARCHAR(255) NOT NULL,
+    size_bytes          INT NOT NULL,
+    width               INT,
+    height              INT,
+    ref_count           INT NOT NULL DEFAULT 0,
+    created_at          DATETIME(6) NOT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`;
+var DEDUP_REFS_SCHEMA = `
+CREATE TABLE IF NOT EXISTS zerobucket_image_refs (
+    id                  CHAR(36) PRIMARY KEY,
+    checksum_sha256     CHAR(64) NOT NULL,
+    original_filename   TEXT,
+    created_at          DATETIME(6) NOT NULL,
+    updated_at          DATETIME(6) NOT NULL,
+    INDEX idx_zerobucket_image_refs_checksum (checksum_sha256),
+    INDEX idx_zerobucket_image_refs_created_at (created_at),
+    FOREIGN KEY (checksum_sha256) REFERENCES zerobucket_blobs(checksum_sha256)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`;
+function upsertBlobSql(n) {
+  if (!Number.isInteger(n) || n < 1) throw new RangeError("invalid ref count");
+  return `INSERT INTO zerobucket_blobs (checksum_sha256, data, mime_type, size_bytes, width, height, ref_count, created_at) VALUES (?, ?, ?, ?, ?, ?, ${n}, ?) ON DUPLICATE KEY UPDATE ref_count = ref_count + ${n}`;
+}
+var D_INSERT_REF3 = `INSERT INTO zerobucket_image_refs (id, checksum_sha256, original_filename, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`;
+var D_COLS3 = `r.id, b.data, b.mime_type, r.original_filename, b.size_bytes, b.width, b.height, r.checksum_sha256, '${LOCAL}' AS storage_backend, NULL AS object_storage_bucket, NULL AS object_storage_key`;
+var D_FROM3 = `FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256`;
+var D_LOCK_REF = `SELECT checksum_sha256 FROM zerobucket_image_refs WHERE id = ? FOR UPDATE`;
+var D_DELETE_REF3 = `DELETE FROM zerobucket_image_refs WHERE id = ?`;
+var D_LOCK_REFS = `SELECT id, checksum_sha256 FROM zerobucket_image_refs FORCE INDEX (PRIMARY) WHERE id IN (?) ORDER BY id FOR UPDATE`;
+var D_DECREMENT3 = `UPDATE zerobucket_blobs SET ref_count = ref_count - ? WHERE checksum_sha256 = ?`;
+var D_DELETE_EMPTY3 = `DELETE FROM zerobucket_blobs WHERE checksum_sha256 = ? AND ref_count <= 0`;
+var CLASSIC_SQL2 = {
+  selectFull: SELECT_FULL3,
+  selectMany: SELECT_MANY2,
+  selectMetadata: SELECT_METADATA3,
+  streamInfo: STREAM_INFO2,
+  chunk: CHUNK2,
+  exists: EXISTS3
+};
+var DEDUP_SQL2 = {
+  selectFull: `SELECT ${D_COLS3} ${D_FROM3} WHERE r.id = ?`,
+  selectMany: `SELECT ${D_COLS3} ${D_FROM3} WHERE r.id IN (?)`,
+  selectMetadata: `SELECT r.id, b.mime_type, r.original_filename, b.size_bytes, b.width, b.height, r.checksum_sha256 ${D_FROM3} WHERE r.id = ?`,
+  streamInfo: `SELECT b.size_bytes, '${LOCAL}' AS storage_backend, NULL AS object_storage_key ${D_FROM3} WHERE r.id = ?`,
+  chunk: `SELECT SUBSTRING(b.data FROM ? FOR ?) AS chunk ${D_FROM3} WHERE r.id = ?`,
+  exists: `SELECT 1 FROM zerobucket_image_refs WHERE id = ?`
+};
+var RETRYABLE_ERRNOS = /* @__PURE__ */ new Set([
+  1205,
+  // ER_LOCK_WAIT_TIMEOUT
+  1213,
+  // ER_LOCK_DEADLOCK
+  1040,
+  // ER_CON_COUNT_ERROR (too many connections)
+  1053,
+  // ER_SERVER_SHUTDOWN
+  1927,
+  // ER_CONNECTION_KILLED (MariaDB)
+  2002,
+  // CR_CONNECTION_ERROR
+  2003,
+  // CR_CONN_HOST_ERROR
+  2006,
+  // CR_SERVER_GONE_ERROR
+  2013
+  // CR_SERVER_LOST
+]);
+var CONNECTION_CODES = /* @__PURE__ */ new Set([
+  "PROTOCOL_CONNECTION_LOST",
+  "PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR",
+  "PROTOCOL_ENQUEUE_AFTER_QUIT",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EPIPE",
+  "ECONNABORTED"
+]);
+function errnoOf(exc) {
+  const n = exc?.errno;
+  return typeof n === "number" ? n : void 0;
+}
+var PoolTimeoutError = class extends StorageError {
+};
+function isRetryable2(exc) {
+  if (!(exc instanceof Error) || exc instanceof PoolTimeoutError) return false;
+  const e = exc;
+  const n = errnoOf(exc);
+  if (n !== void 0 && RETRYABLE_ERRNOS.has(n)) return true;
+  if (typeof e.code === "string") {
+    if (CONNECTION_CODES.has(e.code)) return true;
+    if (e.code === "ER_LOCK_WAIT_TIMEOUT" || e.code === "ER_LOCK_DEADLOCK" || e.code === "ER_CON_COUNT_ERROR" || e.code === "ER_SERVER_SHUTDOWN" || e.code === "ER_CONNECTION_KILLED")
+      return true;
+  }
+  return false;
+}
+function isConnectionLevel2(exc) {
+  if (!(exc instanceof Error)) return false;
+  const e = exc;
+  if (e.fatal === true) return true;
+  if (typeof e.code === "string" && CONNECTION_CODES.has(e.code)) return true;
+  const n = errnoOf(exc);
+  return n === 2006 || n === 2013 || n === 1927 || n === 1053;
+}
+var MAX_BACKOFF_MS2 = 2e3;
+function backoffDelayMs2(attempt, baseDelayMs) {
+  const exponential = baseDelayMs * 2 ** (attempt - 1);
+  const jitter = Math.random() * baseDelayMs;
+  return Math.min(exponential + jitter, MAX_BACKOFF_MS2);
+}
+function friendly(prefix, exc) {
+  if (errnoOf(exc) === 1153) {
+    return new StorageError(
+      `${prefix}: the image is larger than the server's max_allowed_packet. Raise it (for example \`SET GLOBAL max_allowed_packet = 67108864\`, and set it in my.cnf to make it permanent), or lower \`maxBytes\`.`,
+      { cause: exc }
+    );
+  }
+  return wrap(prefix, exc);
+}
+function mysqlNow() {
+  return `${(/* @__PURE__ */ new Date()).toISOString().replace("T", " ").replace("Z", "")}000`;
+}
+function normalizeUrl(url) {
+  return url.replace(/^mariadb:\/\//i, "mysql://");
+}
+function isMysqlConnection(c) {
+  const m = c;
+  return typeof m.query === "function" && typeof m.execute === "function";
+}
+var MySQLBackend = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.connectionString && !opts.pool) {
+      throw new TypeError(
+        "MySQLBackend requires either `connectionString` or `pool`"
+      );
+    }
+    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_SQL2 : CLASSIC_SQL2;
+    this.ownsPool = !opts.pool;
+    this.pool = opts.pool;
+    this.maxRetries = opts.maxRetries ?? 3;
+    this.retryBaseDelayMs = opts.retryBaseDelayMs ?? 100;
+    this.poolTimeoutMs = opts.poolTimeoutMs ?? 1e4;
+    this.autoMigrate = opts.autoMigrate ?? true;
+  }
+  opts;
+  pool;
+  ownsPool;
+  readyPromise;
+  closed = false;
+  maxRetries;
+  retryBaseDelayMs;
+  poolTimeoutMs;
+  autoMigrate;
+  dedup;
+  sql;
+  // ---- 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() {
+    if (!this.pool) {
+      let mod;
+      try {
+        mod = await import("mysql2/promise");
+      } catch (cause) {
+        throw new StorageError(
+          "MySQLBackend requires the 'mysql2' package. Install it with: npm install mysql2",
+          { cause }
+        );
+      }
+      const createPool = (mod.default ?? mod).createPool;
+      this.pool = createPool({
+        uri: normalizeUrl(this.opts.connectionString),
+        connectionLimit: this.opts.poolMaxSize ?? 5,
+        waitForConnections: true,
+        queueLimit: 0,
+        connectTimeout: this.poolTimeoutMs,
+        charset: "utf8mb4",
+        timezone: "Z",
+        enableKeepAlive: true
+      });
+    }
+    try {
+      if (this.autoMigrate) {
+        await this.runPooled("migrate", (q) => this.migrate(q), false);
+      } else {
+        await this.runPooled("ping", (q) => q.query("SELECT 1"), false);
+      }
+    } catch (exc) {
+      if (this.ownsPool) {
+        await this.pool.end().catch(() => {
+        });
+        this.pool = void 0;
+      }
+      throw exc instanceof StorageError ? exc : new StorageError(`Could not connect to MySQL/MariaDB: ${msg(exc)}`, {
+        cause: exc
+      });
+    }
+  }
+  /**
+   * Create the schema if missing, under a server-side named lock so concurrent first callers (in this
+   * or any other process) run the DDL one at a time. Every step checks before it changes anything, so
+   * re-running is a no-op.
+   */
+  async migrate(q) {
+    const locked = (await q.query("SELECT GET_LOCK(?, 30) AS got", [MIGRATE_LOCK]))[0][0]?.got;
+    if (locked !== 1) {
+      throw new StorageError(
+        "Timed out waiting for another process to finish migrating the ZeroBucket schema."
+      );
+    }
+    try {
+      if (this.dedup) {
+        await this.migrateDedup(q);
+        return;
+      }
+      const tableExists = (await q.query(
+        "SELECT 1 FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'zerobucket_images'"
+      ))[0].length > 0;
+      if (!tableExists) await q.query(SCHEMA3);
+      const cols = new Map(
+        (await q.query(
+          "SELECT COLUMN_NAME AS c, IS_NULLABLE AS nullable FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'zerobucket_images'"
+        ))[0].map((r) => [r.c, r.nullable])
+      );
+      if (!cols.has("storage_backend"))
+        await q.query(
+          `ALTER TABLE zerobucket_images ADD COLUMN storage_backend VARCHAR(20) NOT NULL DEFAULT '${LOCAL}'`
+        );
+      if (!cols.has("object_storage_bucket"))
+        await q.query(
+          "ALTER TABLE zerobucket_images ADD COLUMN object_storage_bucket VARCHAR(255)"
+        );
+      if (!cols.has("object_storage_key"))
+        await q.query(
+          "ALTER TABLE zerobucket_images ADD COLUMN object_storage_key VARCHAR(512)"
+        );
+      if (cols.get("data") === "NO")
+        await q.query(
+          "ALTER TABLE zerobucket_images MODIFY data LONGBLOB NULL"
+        );
+      const hasCheck = (await q.query(
+        "SELECT 1 FROM information_schema.TABLE_CONSTRAINTS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'zerobucket_images' AND CONSTRAINT_NAME = ?",
+        [TIERING_CHECK]
+      ))[0].length > 0;
+      if (!hasCheck) {
+        await q.query(
+          `ALTER TABLE zerobucket_images ADD CONSTRAINT ${TIERING_CHECK} CHECK ((storage_backend = '${LOCAL}' AND data IS NOT NULL AND object_storage_bucket IS NULL AND object_storage_key IS NULL) OR (storage_backend = 'object_storage' AND data IS NULL AND object_storage_bucket IS NOT NULL AND object_storage_key IS NOT NULL))`
+        );
+      }
+    } catch (exc) {
+      throw new StorageError(`Migration failed: ${msg(exc)}`, { cause: exc });
+    } finally {
+      await q.query("SELECT RELEASE_LOCK(?)", [MIGRATE_LOCK]).catch(() => {
+      });
+    }
+  }
+  /** Dedup tables, created only if missing (same no-needless-DDL rule as the classic table). */
+  async migrateDedup(q) {
+    const have = new Set(
+      (await q.query(
+        "SELECT TABLE_NAME AS t FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN ('zerobucket_blobs', 'zerobucket_image_refs')"
+      ))[0].map((r) => r.t)
+    );
+    if (!have.has("zerobucket_blobs")) await q.query(DEDUP_BLOBS_SCHEMA);
+    if (!have.has("zerobucket_image_refs")) await q.query(DEDUP_REFS_SCHEMA);
+  }
+  async close() {
+    this.closed = true;
+    const pool = this.pool;
+    this.pool = void 0;
+    this.readyPromise = void 0;
+    if (pool && this.ownsPool) await pool.end();
+  }
+  // ---- 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 {
+    }
+  }
+  /** Wait for a pool slot, but never longer than poolTimeoutMs. */
+  acquire() {
+    const pool = this.pool;
+    if (this.closed || !pool)
+      return Promise.reject(
+        new StorageError("This ZeroBucket instance has been closed")
+      );
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        settled = true;
+        reject(
+          new PoolTimeoutError(
+            `Timed out after ${this.poolTimeoutMs}ms waiting for a MySQL/MariaDB connection (poolMaxSize=${this.opts.poolMaxSize ?? 5}; all connections are in use).`
+          )
+        );
+      }, this.poolTimeoutMs);
+      pool.getConnection().then(
+        (conn) => {
+          if (settled) {
+            conn.release();
+            return;
+          }
+          settled = true;
+          clearTimeout(timer);
+          resolve(conn);
+        },
+        (exc) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          reject(exc);
+        }
+      );
+    });
+  }
+  /**
+   * Run `work` on a pooled connection. `tx` wraps it in a transaction. Transient failures retry the
+   * WHOLE closure on a fresh connection after a full rollback.
+   */
+  async runPooled(operation, work, tx) {
+    const start = performance.now();
+    let attempt = 0;
+    for (; ; ) {
+      let conn;
+      let destroy = false;
+      try {
+        conn = await this.acquire();
+        if (tx) await conn.beginTransaction();
+        const result = await work(conn);
+        if (tx) await conn.commit();
+        this.emit(operation, start, true, null, attempt);
+        return result;
+      } catch (exc) {
+        if (conn && tx) {
+          try {
+            await conn.rollback();
+          } catch {
+            destroy = true;
+          }
+        }
+        if (isConnectionLevel2(exc)) destroy = true;
+        attempt += 1;
+        if (attempt > this.maxRetries || !isRetryable2(exc)) {
+          this.emit(operation, start, false, msg(exc), attempt - 1);
+          throw exc;
+        }
+      } finally {
+        if (conn) {
+          if (destroy) conn.destroy();
+          else conn.release();
+        }
+      }
+      await sleep(backoffDelayMs2(attempt, this.retryBaseDelayMs));
+    }
+  }
+  /**
+   * Run `work` and return its result, emitting exactly one OperationEvent.
+   *
+   * connection given  -> run once on it; no retry, and no commit/rollback of the caller's transaction.
+   * connection absent -> pooled, retried (see runPooled).
+   */
+  async run(operation, connection, work, { tx = false } = {}) {
+    if (connection) {
+      if (!isMysqlConnection(connection)) {
+        throw new TypeError(
+          "MySQLBackend expects a mysql2/promise connection as `connection` (an object with query() and execute())."
+        );
+      }
+      const start = performance.now();
+      try {
+        const result = tx ? await this.atomic(connection, work) : await work(connection);
+        this.emit(operation, start, true, null, 0);
+        return result;
+      } catch (exc) {
+        this.emit(operation, start, false, msg(exc), 0);
+        throw exc;
+      }
+    }
+    await this.ready();
+    return this.runPooled(operation, work, tx);
+  }
+  /**
+   * Make multi-statement work all-or-nothing on a CALLER-supplied connection.
+   *
+   * Is a transaction open? SAVEPOINT followed by ROLLBACK TO SAVEPOINT succeeds only inside one (in
+   * autocommit mode the savepoint is gone before the next statement and the rollback fails with 1305).
+   *  - Open  -> reuse that SAVEPOINT: a failure undoes only our work; success joins the caller's transaction.
+   *  - None  -> START TRANSACTION and COMMIT our own, so a failure can never leave half-applied state.
+   */
+  async atomic(conn, work) {
+    let inTransaction;
+    await conn.query("SAVEPOINT zerobucket_atomic");
+    try {
+      await conn.query("ROLLBACK TO SAVEPOINT zerobucket_atomic");
+      inTransaction = true;
+    } catch (exc) {
+      if (errnoOf(exc) !== 1305) throw exc;
+      inTransaction = false;
+      await conn.query("START TRANSACTION");
+    }
+    try {
+      const result = await work(conn);
+      await conn.query(
+        inTransaction ? "RELEASE SAVEPOINT zerobucket_atomic" : "COMMIT"
+      );
+      return result;
+    } catch (exc) {
+      try {
+        await conn.query(
+          inTransaction ? "ROLLBACK TO SAVEPOINT zerobucket_atomic" : "ROLLBACK"
+        );
+        if (inTransaction)
+          await conn.query("RELEASE SAVEPOINT zerobucket_atomic");
+      } catch {
+      }
+      throw exc;
+    }
+  }
+  // ---- StorageBackend --------------------------------------------------
+  async put(row, { connection } = {}) {
+    try {
+      const id = randomUUID2();
+      if (this.dedup) {
+        await this.run(
+          "put",
+          connection,
+          async (q) => {
+            const now = mysqlNow();
+            await q.execute(upsertBlobSql(1), blobParams2(row, now));
+            await q.execute(D_INSERT_REF3, refParams(id, row, now));
+          },
+          { tx: true }
+        );
+        return id;
+      }
+      await this.run("put", connection, async (q) => {
+        await q.execute(INSERT3, rowParams2(id, row, mysqlNow()));
+      });
+      return id;
+    } catch (exc) {
+      throw friendly("Failed to store image", exc);
+    }
+  }
+  async putMany(rows, { connection } = {}) {
+    if (rows.length === 0) return [];
+    try {
+      const ids = rows.map(() => randomUUID2());
+      await this.run(
+        "put_many",
+        connection,
+        async (q) => {
+          const now = mysqlNow();
+          if (this.dedup) {
+            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.execute(upsertBlobSql(g.n), blobParams2(g.row, now));
+            }
+            for (let i = 0; i < rows.length; i++)
+              await q.execute(D_INSERT_REF3, refParams(ids[i], rows[i], now));
+            return;
+          }
+          for (let i = 0; i < rows.length; i++)
+            await q.execute(INSERT3, rowParams2(ids[i], rows[i], now));
+        },
+        { tx: true }
+      );
+      return ids;
+    } catch (exc) {
+      throw friendly("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]))[0][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]))[0]
+      );
+    } 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]))[0][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.streamInfo, [id]))[0][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.chunk, [offset + 1, length, id]))[0][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) => {
+          const found = (await q.query(LOCK_ONE, [id]))[0][0];
+          if (!found) return void 0;
+          await q.query(DELETE_ONE2, [id]);
+          return found;
+        },
+        { tx: true }
+      );
+      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 = [...new Set(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) => {
+          const found = (await q.query(LOCK_MANY, [valid]))[0];
+          for (const r of found) await q.query(DELETE_ONE2, [r.id]);
+          return found;
+        },
+        { tx: true }
+      );
+      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]))[0].length > 0
+      );
+    } catch (exc) {
+      throw wrap("Failed to check image existence", exc);
+    }
+  }
+  // ---- maintenance (CLI) -----------------------------------------------
+  /** Storage statistics, or null if the tables do not exist yet (nothing is created). */
+  async getInfo() {
+    try {
+      return await this.run("info", void 0, async (q) => {
+        const need = this.dedup ? ["zerobucket_image_refs", "zerobucket_blobs"] : ["zerobucket_images"];
+        const present = new Set(
+          (await q.query(
+            "SELECT TABLE_NAME AS t FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (?)",
+            [need]
+          ))[0].map((r) => r.t)
+        );
+        if (!need.every((t) => present.has(t))) return null;
+        const j = this.dedup ? "FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256" : "FROM zerobucket_images";
+        const size = this.dedup ? "b.size_bytes" : "size_bytes";
+        const created = this.dedup ? "r.created_at" : "created_at";
+        const mime = this.dedup ? "b.mime_type" : "mime_type";
+        const tot = (await q.query(
+          `SELECT COUNT(*) AS n, COALESCE(SUM(${size}), 0) AS bytes, CAST(MIN(${created}) AS CHAR) AS oldest, CAST(MAX(${created}) AS CHAR) AS newest ${j}`
+        ))[0][0];
+        const disk = (await q.query(
+          "SELECT COALESCE(SUM(DATA_LENGTH + INDEX_LENGTH), 0) AS s FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (?)",
+          [need]
+        ))[0][0];
+        const fmt = (await q.query(
+          `SELECT ${mime} AS m, COUNT(*) AS n, COALESCE(SUM(${size}), 0) AS bytes ${j} GROUP BY ${mime} ORDER BY COUNT(*) DESC, ${mime}`
+        ))[0];
+        const utc = (v) => v ? `${v}+00:00` : null;
+        const info = {
+          mode: this.dedup ? "dedup" : "classic",
+          count: Number(tot.n),
+          totalBytes: Number(tot.bytes),
+          oldest: utc(tot.oldest),
+          newest: utc(tot.newest),
+          onDisk: prettySize(Number(disk.s)),
+          byFormat: fmt.map((r) => ({
+            mimeType: r.m,
+            count: Number(r.n),
+            bytes: Number(r.bytes)
+          }))
+        };
+        if (this.dedup) {
+          const b = (await q.query(
+            "SELECT COUNT(*) AS n, COALESCE(SUM(size_bytes), 0) AS bytes FROM zerobucket_blobs"
+          ))[0][0];
+          info.dedup = { blobs: Number(b.n), storedBytes: Number(b.bytes) };
+        } else {
+          const t = (await q.query(
+            "SELECT COUNT(*) AS n, COALESCE(SUM(size_bytes), 0) AS bytes FROM zerobucket_images WHERE storage_backend = 'object_storage'"
+          ))[0][0];
+          info.tiered = { count: Number(t.n), bytes: Number(t.bytes) };
+        }
+        return info;
+      });
+    } catch (exc) {
+      throw wrap("Failed to read storage info", exc);
+    }
+  }
+  /** Ids matching the filters: oldest first, or a random sample. Used by the CLI's verify and tier. */
+  async listImages(o = {}) {
+    const where = [];
+    const params = [];
+    const created = this.dedup ? "r.created_at" : "created_at";
+    if (o.minSize !== void 0) {
+      where.push(`${this.dedup ? "b.size_bytes" : "size_bytes"} >= ?`);
+      params.push(o.minSize);
+    }
+    if (o.olderThanDays !== void 0) {
+      where.push(`${created} <= UTC_TIMESTAMP(6) - INTERVAL ? DAY`);
+      params.push(o.olderThanDays);
+    }
+    if (o.onlyUntiered && !this.dedup)
+      where.push(`storage_backend = '${LOCAL}'`);
+    const from = this.dedup ? "FROM zerobucket_image_refs r JOIN zerobucket_blobs b ON r.checksum_sha256 = b.checksum_sha256" : "FROM zerobucket_images";
+    const idCol = this.dedup ? "r.id" : "id";
+    const tierCol = this.dedup ? "0 AS tiered" : "(storage_backend = 'object_storage') AS tiered";
+    const order = o.sample !== void 0 ? "ORDER BY RAND()" : `ORDER BY ${created}, ${idCol}`;
+    const lim = o.sample ?? o.limit;
+    let sql = `SELECT ${idCol} AS id, ${tierCol} ${from}${where.length ? " WHERE " + where.join(" AND ") : ""} ${order}`;
+    if (lim !== void 0) {
+      if (!Number.isInteger(lim) || lim < 0)
+        throw new RangeError("limit/sample must be a non-negative integer");
+      sql += ` LIMIT ${lim}`;
+    }
+    try {
+      const rows = await this.run(
+        "list_images",
+        void 0,
+        async (q) => (await q.query(sql, params))[0]
+      );
+      return rows.map((r) => ({
+        id: String(r.id),
+        tiered: Boolean(Number(r.tiered))
+      }));
+    } catch (exc) {
+      throw wrap("Failed to list images", exc);
+    }
+  }
+  // ---- dedup deletes ---------------------------------------------------
+  /**
+   * Lock the ref row, delete it, then decrement its blob (the UPDATE takes the blob row lock, so two
+   * deletes of different refs to one blob serialize instead of racing) and remove the blob once nothing
+   * references it. All in one transaction: a failure can never leave a ref without its count or the reverse.
+   */
+  async deleteDedup(id, connection) {
+    try {
+      return await this.run(
+        "delete",
+        connection,
+        async (q) => {
+          const ref = (await q.query(D_LOCK_REF, [id]))[0][0];
+          if (!ref) return false;
+          const checksum = ref.checksum_sha256;
+          await q.query(D_DELETE_REF3, [id]);
+          await q.query(D_DECREMENT3, [1, checksum]);
+          await q.query(D_DELETE_EMPTY3, [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 found = (await q.query(D_LOCK_REFS, [ids]))[0];
+          if (found.length === 0) return [];
+          for (const r of found) await q.query(D_DELETE_REF3, [r.id]);
+          const counts = /* @__PURE__ */ new Map();
+          for (const r of found)
+            counts.set(
+              r.checksum_sha256,
+              (counts.get(r.checksum_sha256) ?? 0) + 1
+            );
+          for (const checksum of [...counts.keys()].sort()) {
+            await q.query(D_DECREMENT3, [counts.get(checksum), checksum]);
+            await q.query(D_DELETE_EMPTY3, [checksum]);
+          }
+          return found.map((r) => String(r.id));
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to delete image batch", exc);
+    }
+  }
+  // ---- helpers ---------------------------------------------------------
+  hydrate(row, id) {
+    return hydrateRow(row, id, this.opts.objectStorage);
+  }
+  /**
+   * Remove tiered objects AFTER their rows are gone: 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. In that case the object stays until you remove it yourself after committing. 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 the database 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) or 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: InnoDB row-locks only THIS row for the duration of the upload. Concurrent writes to this
+   * image wait (up to innodb_lock_wait_timeout, 50s by default); every other row is unaffected and
+   * plain reads are never blocked. 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_TIERING3, [id]))[0][0];
+          if (!row) return null;
+          if (row.storage_backend !== LOCAL) return false;
+          await os.upload(key, row.data, { mimeType: row.mime_type });
+          await q.query(UPDATE_AFTER_TIERING3, [os.bucket, key, mysqlNow(), id]);
+          return true;
+        },
+        { tx: true }
+      );
+    } catch (exc) {
+      throw wrap("Failed to tier image to object storage", exc);
+    }
+  }
+};
+function blobParams2(r, now) {
+  return [
+    r.checksumSha256,
+    r.data,
+    r.mimeType,
+    r.sizeBytes,
+    r.width,
+    r.height,
+    now
+  ];
+}
+function refParams(id, r, now) {
+  return [id, r.checksumSha256, r.originalFilename, now, now];
+}
+function rowParams2(id, r, now) {
+  return [
+    id,
+    r.data,
+    r.mimeType,
+    r.originalFilename,
+    r.sizeBytes,
+    r.width,
+    r.height,
+    r.checksumSha256,
+    now,
+    now
+  ];
+}
+
 // src/heic.ts
 import { createRequire } from "module";
 import { join } from "path";
@@ -2268,9 +3239,14 @@ var ZeroBucket = class _ZeroBucket {
   beforeGet;
   beforePut;
   constructor(options = {}) {
-    if (options.sqlite !== void 0 && (options.connectionString || options.pool)) {
+    const chosen = [
+      options.sqlite !== void 0 && "`sqlite`",
+      (options.mysql !== void 0 || options.mysqlPool) && "`mysql`/`mysqlPool`",
+      (options.connectionString || options.pool) && "`connectionString`/`pool`"
+    ].filter(Boolean);
+    if (chosen.length > 1) {
       throw new TypeError(
-        "Choose one database: `sqlite` OR `connectionString`/`pool`, not both."
+        `Choose one database: ${chosen.join(" OR ")}, not several.`
       );
     }
     this.backend = options.backend ?? (options.sqlite !== void 0 ? new SQLiteBackend({
@@ -2279,6 +3255,18 @@ var ZeroBucket = class _ZeroBucket {
       dedup: options.dedup,
       objectStorage: options.objectStorage,
       onOperation: options.onOperation
+    }) : options.mysql !== void 0 || options.mysqlPool ? new MySQLBackend({
+      connectionString: options.mysql,
+      pool: options.mysqlPool,
+      autoMigrate: options.autoMigrate,
+      maxRetries: options.maxRetries,
+      retryBaseDelayMs: options.retryBaseDelayMs,
+      poolMinSize: options.poolMinSize,
+      poolMaxSize: options.poolMaxSize,
+      poolTimeoutMs: options.poolTimeoutMs,
+      onOperation: options.onOperation,
+      objectStorage: options.objectStorage,
+      dedup: options.dedup
     }) : new PostgresBackend({
       connectionString: options.connectionString,
       pool: options.pool,
@@ -2879,6 +3867,7 @@ export {
   ImageNotFoundError,
   ImageTooLargeError,
   ImageValidationError,
+  MySQLBackend,
   ObjectStorage,
   PDFValidator,
   PostgresBackend,