zerobucket 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -39,6 +39,7 @@ __export(src_exports, {
   ImageNotFoundError: () => ImageNotFoundError,
   ImageTooLargeError: () => ImageTooLargeError,
   ImageValidationError: () => ImageValidationError,
+  MySQLBackend: () => MySQLBackend,
   ObjectStorage: () => ObjectStorage,
   PDFValidator: () => PDFValidator,
   PostgresBackend: () => PostgresBackend,
@@ -59,7 +60,7 @@ var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${_
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
 // src/client.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 var import_promises = require("fs/promises");
 var import_node_path2 = require("path");
 
@@ -1984,6 +1985,711 @@ var SQLiteBackend = class {
   }
 };
 
+// src/adapters/mysql.ts
+var import_node_crypto2 = require("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 WHERE id IN (?) ORDER BY id FOR UPDATE`;
+var DELETE_MANY2 = `DELETE FROM zerobucket_images WHERE id IN (?)`;
+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 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`"
+      );
+    }
+    if (opts.dedup) {
+      throw new TypeError(
+        "dedup mode is not available for MySQL in the npm package yet (the Python package supports it). Use classic mode, or Postgres/SQLite for dedup."
+      );
+    }
+    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;
+  // ---- 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 {
+      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(() => {
+      });
+    }
+  }
+  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 = (0, import_node_crypto2.randomUUID)();
+      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(() => (0, import_node_crypto2.randomUUID)());
+      await this.run(
+        "put_many",
+        connection,
+        async (q) => {
+          const now = mysqlNow();
+          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(SELECT_FULL3, [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(SELECT_MANY2, [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(SELECT_METADATA3, [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(STREAM_INFO2, [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(CHUNK2, [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;
+    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 [];
+    try {
+      const rows = await this.run(
+        "delete_many",
+        connection,
+        async (q) => {
+          const found = (await q.query(LOCK_MANY, [valid]))[0];
+          if (found.length === 0) return [];
+          await q.query(DELETE_MANY2, [found.map((r) => 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(EXISTS3, [id]))[0].length > 0
+      );
+    } catch (exc) {
+      throw wrap("Failed to check image existence", 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 } = {}) {
+    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 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
 var import_node_module = require("module");
 var import_node_path = require("path");
@@ -2372,9 +3078,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({
@@ -2383,6 +3094,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,
@@ -2479,7 +3202,7 @@ var ZeroBucket = class _ZeroBucket {
       sizeBytes,
       width,
       height,
-      checksumSha256: (0, import_node_crypto2.createHash)("sha256").update(finalData).digest("hex")
+      checksumSha256: (0, import_node_crypto3.createHash)("sha256").update(finalData).digest("hex")
     };
   }
   /** Validate, optionally optimize, checksum and store one image. Returns its id (a UUID). */
@@ -2984,6 +3707,7 @@ var PDFValidator = class {
   ImageNotFoundError,
   ImageTooLargeError,
   ImageValidationError,
+  MySQLBackend,
   ObjectStorage,
   PDFValidator,
   PostgresBackend,