leblob 0.4.0.dev1__py3-none-any.whl

leblob/meta.py

@@ -0,0 +1,2327 @@
+"""Every SQL statement, with one public function per transaction.
+
+Transaction functions are plain synchronous code on a worker thread, so none of
+them can `await` while holding a transaction open: a slow client can never block
+a writer. Callers see them as `await meta.something(db, ...)`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import fcntl
+import heapq
+import json
+import os
+import secrets
+import shutil
+import sqlite3
+import threading
+import time
+from collections import deque
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass, replace
+from functools import partial, wraps
+from itertools import groupby, starmap
+from operator import attrgetter, itemgetter
+from typing import TYPE_CHECKING, Any
+
+from leblob.blobstore import fsync_directory
+from leblob.model import (
+    NULL_VERSION_ID,
+    Blob,
+    BucketRecord,
+    Checksum,
+    ChecksumPlan,
+    ChecksumType,
+    CompletedUpload,
+    DeleteOutcome,
+    KeyVerdict,
+    KnownBlob,
+    LifecycleReport,
+    LifecycleRule,
+    ObjectRecord,
+    ObjectRef,
+    ObjectSummary,
+    Part,
+    RepairWork,
+    Upload,
+    UploadExtras,
+    Versioning,
+    VersionSummary,
+    VolumeRecord,
+)
+from leblob.s3 import (
+    conditions,
+    errors,
+    lifecycle,
+    listing,
+    multipart,
+    sse,
+    xml_config,
+)
+from leblob.s3.access import FULL, Level, Scope
+from leblob.s3.errors import S3Error
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Awaitable,
+        Callable,
+        Iterable,
+        Iterator,
+        Mapping,
+        Sequence,
+    )
+    from pathlib import Path
+    from typing import BinaryIO, Concatenate
+
+    from leblob.model import CompletionRequest, DeleteTarget, UploadRef
+    from leblob.s3.conditions import WriteCondition
+    from leblob.s3.listing import ListPage, ListQuery
+
+GC_GRACE_MS = 3_600_000
+
+DAY_MS = 24 * 3600 * 1000
+SCRUB_REST_MS = DAY_MS  # Between passes, so an idle store stays idle.
+
+WRITER_LOCK_SUFFIX = ".writer-lock"
+
+_BEGIN_WRITE = "BEGIN IMMEDIATE"
+_BUSY_TIMEOUT_MS = 30_000
+_READ_THREADS = 4
+_WRITE_THREADS = 1  # Writers go one at a time, across every worker.
+_MOST_WRITES_IN_A_COMMIT = 32  # So that the writer lock isn't held for long.
+_MILLISECONDS = 1000
+_NO_LIMIT = -1  # As SQLite understands it.
+_VERSION_ID_BYTES = 24
+_SCRUB_MIN_BYTES_PER_BLOB = 64 * 1024  # So that tiny blobs still cost their seek.
+NO_EXTRAS = UploadExtras()
+_LIFECYCLE_BATCH = 1000
+LIFECYCLE_BATCH_REMOVALS = (
+    100  # Removing is what holds up writers: 1000 took up to 2 s.
+)
+# ponytail: one rate for any store, slow enough to leave the writer to clients: about
+# 80 min to walk 10M keys, and about 17M removals a day. Make them settings if needed.
+_LIFECYCLE_VERSIONS_PER_SECOND = 2000
+_LIFECYCLE_REMOVALS_PER_SECOND = 250
+_AFTER = "\x00"  # Sorts straight after a name, since neither keys nor buckets hold it.
+
+# What a version holds is listed in each statement that moves one, in this order, and
+# `test_every_column_of_a_version_is_moved_with_it` holds them to the tables.
+_BLOBS_OF_CURRENT_VERSION = """
+    SELECT blob.blob_id, blob.size, blob.md5,
+           (SELECT group_concat(here.volume_id) FROM blob_locations AS here
+            WHERE here.blob_id = blob.blob_id)
+    FROM object_blobs AS link
+    JOIN blobs AS blob ON blob.blob_id = link.blob_id
+    WHERE link.bucket = ? AND link.key = ?
+    ORDER BY link.position
+"""
+_BLOBS_OF_OLDER_VERSION = """
+    SELECT blob.blob_id, blob.size, blob.md5,
+           (SELECT group_concat(here.volume_id) FROM blob_locations AS here
+            WHERE here.blob_id = blob.blob_id)
+    FROM version_blobs AS link
+    JOIN blobs AS blob ON blob.blob_id = link.blob_id
+    WHERE link.bucket = ? AND link.key = ? AND link.version_id = ?
+    ORDER BY link.position
+"""
+_LIST_OBJECTS = """
+    SELECT key, size, etag, modified_at FROM objects
+    WHERE bucket = ? AND key >= ?
+    ORDER BY key LIMIT ?
+"""
+_LIST_CURRENT_VERSIONS = """
+    SELECT key, version_id, -9223372036854775808, 0, size, etag, modified_at, tags
+    FROM objects WHERE bucket = ? AND key >= ? ORDER BY key
+"""
+_LIST_OLDER_VERSIONS = """
+    SELECT key, version_id, rank, is_delete_marker, size, etag, modified_at, tags
+    FROM object_versions INDEXED BY object_versions_by_rank
+    WHERE bucket = ? AND key >= ? ORDER BY key, rank
+"""
+_LIST_OBJECTS_BELOW = """
+    SELECT key, size, etag, modified_at FROM objects
+    WHERE bucket = ? AND key >= ? AND key < ?
+    ORDER BY key LIMIT ?
+"""
+
+MIGRATIONS = (
+    """
+    CREATE TABLE buckets (
+        name        TEXT PRIMARY KEY,
+        created_at  INTEGER NOT NULL
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE TABLE blobs (
+        blob_id     TEXT PRIMARY KEY,
+        size        INTEGER NOT NULL,
+        md5         TEXT NOT NULL
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE TABLE objects (
+        bucket      TEXT NOT NULL REFERENCES buckets(name),
+        key         TEXT NOT NULL,
+        size        INTEGER NOT NULL,
+        etag        TEXT NOT NULL,
+        modified_at INTEGER NOT NULL,
+        headers     TEXT NOT NULL,
+        checksum    TEXT,
+        PRIMARY KEY (bucket, key)
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE TABLE object_blobs (
+        bucket      TEXT NOT NULL,
+        key         TEXT NOT NULL,
+        position    INTEGER NOT NULL,
+        blob_id     TEXT NOT NULL REFERENCES blobs(blob_id),
+        PRIMARY KEY (bucket, key, position),
+        FOREIGN KEY (bucket, key) REFERENCES objects(bucket, key) ON DELETE CASCADE
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE TABLE uploads (
+        upload_id   TEXT PRIMARY KEY,
+        bucket      TEXT NOT NULL REFERENCES buckets(name),
+        key         TEXT NOT NULL,
+        headers     TEXT NOT NULL,
+        created_at  INTEGER NOT NULL
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE INDEX uploads_by_key ON uploads (bucket, key, upload_id);
+
+    CREATE TABLE upload_parts (
+        upload_id   TEXT NOT NULL REFERENCES uploads(upload_id) ON DELETE CASCADE,
+        part_number INTEGER NOT NULL,
+        blob_id     TEXT NOT NULL REFERENCES blobs(blob_id),
+        checksum    TEXT,
+        modified_at INTEGER NOT NULL,
+        PRIMARY KEY (upload_id, part_number)
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE TABLE completed_uploads (
+        upload_id    TEXT PRIMARY KEY,
+        bucket       TEXT NOT NULL,
+        key          TEXT NOT NULL,
+        etag         TEXT NOT NULL,
+        completed_at INTEGER NOT NULL
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE TABLE blob_gc (
+        blob_id     TEXT PRIMARY KEY,
+        due_at      INTEGER NOT NULL
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE INDEX blob_gc_by_due ON blob_gc (due_at);
+
+    CREATE TABLE access_keys (
+        access_key  TEXT PRIMARY KEY,
+        secret      TEXT NOT NULL,
+        created_at  INTEGER NOT NULL
+    ) STRICT, WITHOUT ROWID;
+    """,
+    # Keys from before this migration stay as they were: full access.
+    """
+    ALTER TABLE access_keys ADD COLUMN scoped INTEGER NOT NULL DEFAULT 0
+        CHECK (scoped IN (0, 1));
+
+    CREATE TABLE key_grants (
+        access_key  TEXT NOT NULL REFERENCES access_keys(access_key) ON DELETE CASCADE,
+        bucket      TEXT NOT NULL REFERENCES buckets(name) ON DELETE CASCADE,
+        level       INTEGER NOT NULL CHECK (level IN (1, 2, 3)),
+        PRIMARY KEY (access_key, bucket)
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE INDEX key_grants_by_bucket ON key_grants (bucket);
+    """,
+    # Uploads and objects from before this migration have no checksum to keep.
+    """
+    ALTER TABLE uploads ADD COLUMN checksum_algorithm TEXT;
+    ALTER TABLE uploads ADD COLUMN checksum_type TEXT
+        CHECK (checksum_type IN ('COMPOSITE', 'FULL_OBJECT'));
+    ALTER TABLE completed_uploads ADD COLUMN checksum TEXT;
+    """,
+    # Without these, forgetting a blob scans both tables to check nothing refers to it.
+    """
+    CREATE INDEX object_blobs_by_blob ON object_blobs (blob_id);
+    CREATE INDEX upload_parts_by_blob ON upload_parts (blob_id);
+    """,
+    # The data directory becomes the first volume, with its files where they are.
+    """
+    CREATE TABLE volumes (
+        volume_id   INTEGER PRIMARY KEY,
+        identity    TEXT NOT NULL UNIQUE,
+        path        TEXT NOT NULL UNIQUE
+    ) STRICT;
+
+    INSERT INTO volumes (volume_id, identity, path)
+        VALUES (1, lower(hex(randomblob(16))), '.');
+
+    CREATE TABLE blob_locations (
+        blob_id     TEXT NOT NULL REFERENCES blobs(blob_id) ON DELETE CASCADE,
+        volume_id   INTEGER NOT NULL REFERENCES volumes(volume_id),
+        PRIMARY KEY (blob_id, volume_id)
+    ) STRICT, WITHOUT ROWID;
+
+    INSERT INTO blob_locations (blob_id, volume_id) SELECT blob_id, 1 FROM blobs;
+
+    CREATE INDEX blob_locations_by_volume ON blob_locations (volume_id);
+    """,
+    # How many copies new blobs get. It is here so that a restart can't lower it.
+    """
+    CREATE TABLE settings (
+        only_row    INTEGER PRIMARY KEY CHECK (only_row = 1),
+        copies      INTEGER NOT NULL CHECK (copies >= 1)
+    ) STRICT;
+
+    INSERT INTO settings (only_row, copies) VALUES (1, 1);
+    """,
+    # A queue rather than a scan: finding short blobs by walking them all, every few
+    # seconds, would cost a read of the whole table on a store with nothing to repair.
+    """
+    ALTER TABLE volumes ADD COLUMN draining INTEGER NOT NULL DEFAULT 0
+        CHECK (draining IN (0, 1));
+    ALTER TABLE settings ADD COLUMN scrub_cursor TEXT NOT NULL DEFAULT '';
+    ALTER TABLE settings ADD COLUMN scrub_not_before INTEGER NOT NULL DEFAULT 0;
+
+    CREATE TABLE repair_queue (
+        blob_id     TEXT PRIMARY KEY REFERENCES blobs(blob_id) ON DELETE CASCADE,
+        due_at      INTEGER NOT NULL
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE INDEX repair_queue_by_due ON repair_queue (due_at);
+
+    INSERT INTO repair_queue (blob_id, due_at)
+        SELECT blob_id, 0 FROM blob_locations GROUP BY blob_id
+        HAVING count(*) < (SELECT copies FROM settings);
+    """,
+    # The current version stays in `objects`, so listing and reading it cost what they
+    # did. Rows here are older versions and delete markers. `rank` falls as they are
+    # added, so an index walks a key's versions newest first. A current version is
+    # always newer than any of them, or there is none.
+    """
+    ALTER TABLE buckets ADD COLUMN versioning TEXT
+        CHECK (versioning IN ('Enabled', 'Suspended'));
+    ALTER TABLE objects ADD COLUMN version_id TEXT NOT NULL DEFAULT 'null';
+    ALTER TABLE completed_uploads ADD COLUMN version_id TEXT;
+
+    CREATE TABLE object_versions (
+        bucket      TEXT NOT NULL REFERENCES buckets(name),
+        key         TEXT NOT NULL,
+        version_id  TEXT NOT NULL,
+        rank        INTEGER NOT NULL,
+        is_delete_marker INTEGER NOT NULL CHECK (is_delete_marker IN (0, 1)),
+        size        INTEGER NOT NULL,
+        etag        TEXT NOT NULL,
+        modified_at INTEGER NOT NULL,
+        headers     TEXT NOT NULL,
+        checksum    TEXT,
+        PRIMARY KEY (bucket, key, version_id)
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE UNIQUE INDEX object_versions_by_rank
+        ON object_versions (bucket, key, rank);
+
+    CREATE TABLE version_blobs (
+        bucket      TEXT NOT NULL,
+        key         TEXT NOT NULL,
+        version_id  TEXT NOT NULL,
+        position    INTEGER NOT NULL,
+        blob_id     TEXT NOT NULL REFERENCES blobs(blob_id),
+        PRIMARY KEY (bucket, key, version_id, position),
+        FOREIGN KEY (bucket, key, version_id)
+            REFERENCES object_versions(bucket, key, version_id) ON DELETE CASCADE
+    ) STRICT, WITHOUT ROWID;
+
+    CREATE INDEX version_blobs_by_blob ON version_blobs (blob_id);
+    """,
+    # A bucket's rules are kept as the XML a client gets back. The cursor and pace are
+    # shared by every worker, and a pass carries on from where it was after a restart.
+    """
+    ALTER TABLE buckets ADD COLUMN lifecycle TEXT;
+    ALTER TABLE settings ADD COLUMN lifecycle_bucket TEXT NOT NULL DEFAULT '';
+    ALTER TABLE settings ADD COLUMN lifecycle_key TEXT NOT NULL DEFAULT '';
+    ALTER TABLE settings ADD COLUMN lifecycle_not_before INTEGER NOT NULL DEFAULT 0;
+    """,
+    # Empty for nearly every object, so it costs little, and moves with its version.
+    """
+    ALTER TABLE objects ADD COLUMN tags TEXT;
+    ALTER TABLE object_versions ADD COLUMN tags TEXT;
+    ALTER TABLE uploads ADD COLUMN tags TEXT;
+    """,
+    "ALTER TABLE buckets ADD COLUMN cors TEXT;",
+    # Whether anyone may list a bucket, or read a version of an object. S3 keeps the
+    # two apart: a public bucket doesn't make its objects public, or the reverse.
+    """
+    ALTER TABLE buckets ADD COLUMN public INTEGER NOT NULL DEFAULT 0;
+    ALTER TABLE objects ADD COLUMN public INTEGER NOT NULL DEFAULT 0;
+    ALTER TABLE object_versions ADD COLUMN public INTEGER NOT NULL DEFAULT 0;
+    ALTER TABLE uploads ADD COLUMN public INTEGER NOT NULL DEFAULT 0;
+    """,
+    # Whether a version is encrypted, and how to tell the right key when it is sent.
+    """
+    ALTER TABLE objects ADD COLUMN sse_check TEXT;
+    ALTER TABLE object_versions ADD COLUMN sse_check TEXT;
+    ALTER TABLE uploads ADD COLUMN sse_check TEXT;
+    """,
+)
+
+
+def initialize(path: Path) -> None:
+    """Create or migrate the database. Runs once, before any worker starts."""
+    connection = sqlite3.connect(path, autocommit=True)
+    try:
+        connection.execute("PRAGMA journal_mode=WAL")
+        version = connection.execute("PRAGMA user_version").fetchone()[0]
+        for number, script in enumerate(MIGRATIONS[version:], start=version + 1):
+            connection.executescript(
+                f"BEGIN IMMEDIATE;{script};PRAGMA user_version={number};COMMIT;"
+            )
+    finally:
+        connection.close()
+
+
+def load_volumes(path: Path) -> tuple[VolumeRecord, ...]:
+    """Every volume, first the data directory."""
+    connection = sqlite3.connect(path)
+    try:
+        return _load_volumes(connection)
+    finally:
+        connection.close()
+
+
+def _load_volumes(connection: sqlite3.Connection) -> tuple[VolumeRecord, ...]:
+    rows = connection.execute(
+        "SELECT volume_id, identity, path, draining FROM volumes ORDER BY volume_id"
+    )
+    return tuple(
+        VolumeRecord(volume_id, identity, path, bool(draining))
+        for volume_id, identity, path, draining in rows
+    )
+
+
+def load_copies(path: Path) -> int:
+    """The number of copies new blobs get, for commands and for starting a server."""
+    connection = sqlite3.connect(path)
+    try:
+        return _copies(connection)
+    finally:
+        connection.close()
+
+
+class MetadataUnavailableError(Exception):
+    """The metadata can't be read right now, as on a full disk."""
+
+
+def load_store_settings(path: Path) -> tuple[tuple[VolumeRecord, ...], int]:
+    """Every volume and the number of copies, for a worker starting up.
+
+    On a full disk SQLite may be unable to reopen a database whose WAL needs recovery,
+    so this can fail until there is room again.
+    """
+    try:
+        return load_volumes(path), load_copies(path)
+    except sqlite3.Error as error:
+        raise MetadataUnavailableError(str(error)) from error
+
+
+class VolumeChangeError(Exception):
+    """A change to the volumes that would do harm. The message says why."""
+
+
+class BackupError(Exception):
+    """A backup that can't be made or used. The message says why."""
+
+
+def backup(path: Path, destination: Path) -> None:
+    """Copy the database while it is in use, as one snapshot, durably.
+
+    The copy takes a single step: one made in small steps starts again whenever a
+    writer commits, so under load it might never finish. Writers don't wait for it.
+    """
+    if destination.exists():
+        message = f"{destination} already exists"
+        raise BackupError(message)
+    partial_copy = destination.with_name(destination.name + ".partial")
+    # The copy holds the access keys' secrets, so it is private from the start.
+    os.close(os.open(partial_copy, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600))
+    try:
+        source = sqlite3.connect(path, timeout=_BUSY_TIMEOUT_MS / _MILLISECONDS)
+        target = sqlite3.connect(partial_copy)
+        try:
+            source.backup(target)
+        finally:
+            target.close()
+            source.close()
+        _install(partial_copy, destination)
+    finally:
+        partial_copy.unlink(missing_ok=True)
+
+
+def restore(backup_path: Path, path: Path) -> None:
+    """Put a backup where the database was, refusing to replace anything.
+
+    A leftover WAL would be replayed over the backup and corrupt it, so it counts as
+    being in the way too. The server must be stopped: one still running would keep
+    writing to the database it has open.
+    """
+    if not backup_path.is_file():
+        message = f"no backup at {backup_path}"
+        raise BackupError(message)
+    for suffix in ("", "-wal", "-shm"):
+        existing = path.with_name(path.name + suffix)
+        if existing.exists():
+            message = f"{existing} is in the way; move the old metadata aside first"
+            raise BackupError(message)
+    partial_copy = path.with_name(path.name + ".restoring")
+    shutil.copyfile(backup_path, partial_copy)
+    try:
+        _check_backup(partial_copy, backup_path)
+        _install(partial_copy, path)
+    finally:
+        partial_copy.unlink(missing_ok=True)
+
+
+def _check_backup(path: Path, named_as: Path) -> None:
+    connection = sqlite3.connect(path)
+    try:
+        version = connection.execute("PRAGMA user_version").fetchone()[0]
+        integrity = connection.execute("PRAGMA integrity_check").fetchall()
+    except sqlite3.DatabaseError as error:
+        message = f"{named_as} isn't a usable backup: {error}"
+        raise BackupError(message) from error
+    finally:
+        connection.close()
+    if integrity != [("ok",)]:
+        message = f"{named_as} is damaged: {integrity[0][0]}"
+        raise BackupError(message)
+    if not 1 <= version <= len(MIGRATIONS):
+        message = f"{named_as} isn't a backup this version can use: schema {version}"
+        raise BackupError(message)
+
+
+def _install(partial_copy: Path, destination: Path) -> None:
+    descriptor = os.open(partial_copy, os.O_RDONLY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+    partial_copy.rename(destination)
+    fsync_directory(destination.parent)
+
+
+@dataclass(frozen=True, slots=True)
+class _QueuedWrite:
+    function: Callable[[sqlite3.Connection], Any]
+    future: Future[Any]
+
+
+def _run_each(
+    batch: Sequence[_QueuedWrite], connection: sqlite3.Connection
+) -> list[tuple[Any, Exception | None]]:
+    outcomes: list[tuple[Any, Exception | None]] = []
+    for write in batch:
+        connection.execute("SAVEPOINT one_write")
+        try:
+            result = write.function(connection)
+        # Anything else is a bug, and fails the whole batch, in the caller's sight.
+        except (S3Error, sqlite3.Error, OSError) as error:
+            connection.execute("ROLLBACK TO one_write")
+            outcomes.append((None, error))
+        else:
+            outcomes.append((result, None))
+        connection.execute("RELEASE one_write")
+    return outcomes
+
+
+class Database:
+    """Pools of threads, each holding its own SQLite connection.
+
+    Reads have a pool of their own, because a writer holds its thread while it waits
+    for the writer lock. Sharing one, a few queued writers would stop every read.
+    """
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._local = threading.local()
+        self._connections: list[sqlite3.Connection] = []
+        self._writer_locks: list[BinaryIO] = []
+        self._lock = threading.Lock()
+        self._read_pool = ThreadPoolExecutor(max_workers=_READ_THREADS)
+        self._write_pool = ThreadPoolExecutor(max_workers=_WRITE_THREADS)
+        self._waiting: deque[_QueuedWrite] = deque()
+
+    def _open_connection_once(self) -> None:
+        """Open this thread's connection, on its first transaction.
+
+        Not in a pool initializer: one failure there, such as on a full disk, breaks
+        the pool until the server restarts. Here it fails one request.
+        """
+        if hasattr(self._local, "connection"):
+            return
+        connection = sqlite3.connect(
+            self._path,
+            autocommit=True,
+            timeout=_BUSY_TIMEOUT_MS / _MILLISECONDS,
+            check_same_thread=False,
+        )
+        # In WAL mode, synchronous=NORMAL can lose acknowledged commits on power loss.
+        connection.execute("PRAGMA synchronous=FULL")
+        connection.execute("PRAGMA foreign_keys=ON")
+        writer_lock = self._path.with_name(self._path.name + WRITER_LOCK_SUFFIX).open(
+            "ab"
+        )
+        self._local.connection = connection
+        self._local.writer_lock = writer_lock
+        with self._lock:
+            self._connections.append(connection)
+            self._writer_locks.append(writer_lock)
+
+    def _transact[R](
+        self, begin: str, function: Callable[[sqlite3.Connection], R]
+    ) -> R:
+        self._open_connection_once()
+        connection: sqlite3.Connection = self._local.connection
+        connection.execute(begin)
+        try:
+            result = function(connection)
+            connection.execute("COMMIT")
+        except BaseException:
+            # A failed COMMIT (disk full) may already have rolled back. Left open,
+            # the transaction would make every later BEGIN on this thread fail.
+            if connection.in_transaction:
+                connection.execute("ROLLBACK")
+            raise
+        return result
+
+    def _transact_in_turn[R](
+        self, begin: str, function: Callable[[sqlite3.Connection], R]
+    ) -> R:
+        """Queue on a kernel lock, across workers, rather than on SQLite's.
+
+        SQLite's busy handler sleeps up to 100 ms between tries, so writers sleep
+        while the lock is free, and an unlucky one waits for seconds. The kernel wakes
+        the next writer on release, and releases the lock if its process dies.
+        """
+        self._open_connection_once()
+        writer_lock: BinaryIO = self._local.writer_lock
+        fcntl.flock(writer_lock, fcntl.LOCK_EX)
+        try:
+            return self._transact(begin, function)
+        finally:
+            fcntl.flock(writer_lock, fcntl.LOCK_UN)
+
+    def _commit_what_is_waiting(self) -> None:
+        """Run the writes queued in this worker in one transaction, with one flush.
+
+        A commit takes as long as the disk needs to flush, and writers wait in line for
+        it, so one commit each caps a store at what one flush at a time allows. Each
+        write has a savepoint, so one that fails takes no other with it, and sees the
+        ones before it. None is told it succeeded until the commit is durable. If that
+        fails, all of them did.
+        """
+        batch: list[_QueuedWrite] = []
+        while self._waiting and len(batch) < _MOST_WRITES_IN_A_COMMIT:
+            write = self._waiting.popleft()
+            if write.future.set_running_or_notify_cancel():
+                batch.append(write)
+        if not batch:
+            return  # An earlier round took them.
+        try:
+            outcomes = self._transact_in_turn(_BEGIN_WRITE, partial(_run_each, batch))
+        except BaseException as error:
+            for write in batch:
+                write.future.set_exception(error)
+            raise
+        for write, (result, failure) in zip(batch, outcomes, strict=True):
+            if failure is None:
+                write.future.set_result(result)
+            else:
+                write.future.set_exception(failure)
+
+    async def run[R](
+        self, begin: str, function: Callable[[sqlite3.Connection], R]
+    ) -> R:
+        if begin == _BEGIN_WRITE:
+            future: Future[R] = Future()
+            self._waiting.append(_QueuedWrite(function, future))
+            self._write_pool.submit(self._commit_what_is_waiting)
+            return await asyncio.wrap_future(future)
+        work = partial(self._transact, begin, function)
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(self._read_pool, work)
+
+    def close(self) -> None:
+        self._read_pool.shutdown(wait=True)
+        self._write_pool.shutdown(wait=True)
+        for connection in self._connections:
+            connection.close()
+        for writer_lock in self._writer_locks:
+            writer_lock.close()
+
+
+def _transaction[**P, R](
+    begin: str,
+) -> Callable[
+    [Callable[Concatenate[sqlite3.Connection, P], R]],
+    Callable[Concatenate[Database, P], Awaitable[R]],
+]:
+    def decorate(
+        function: Callable[Concatenate[sqlite3.Connection, P], R],
+    ) -> Callable[Concatenate[Database, P], Awaitable[R]]:
+        @wraps(function)
+        async def wrapper(db: Database, /, *args: P.args, **kwargs: P.kwargs) -> R:
+            return await db.run(
+                begin, lambda connection: function(connection, *args, **kwargs)
+            )
+
+        return wrapper
+
+    return decorate
+
+
+_read = _transaction("BEGIN")
+_write = _transaction(_BEGIN_WRITE)
+
+
+def now_ms() -> int:
+    return time.time_ns() // 1_000_000
+
+
+#
+# Access keys
+#
+@_read
+def get_access_key(
+    connection: sqlite3.Connection, access_key: str
+) -> tuple[str, Scope]:
+    """A key's secret and scope, read per request: a revocation applies at once."""
+    row = connection.execute(
+        "SELECT secret, scoped FROM access_keys WHERE access_key = ?", (access_key,)
+    ).fetchone()
+    if row is None:
+        raise S3Error(errors.INVALID_ACCESS_KEY)
+    secret, scoped = row
+    return secret, _scope(connection, access_key) if scoped else FULL
+
+
+def _scope(connection: sqlite3.Connection, access_key: str) -> Scope:
+    rows = connection.execute(
+        "SELECT bucket, level FROM key_grants WHERE access_key = ?", (access_key,)
+    )
+    return Scope({bucket: Level(level) for bucket, level in rows})
+
+
+@_read
+def list_access_keys(connection: sqlite3.Connection) -> dict[str, Scope]:
+    rows = connection.execute(
+        "SELECT access_key, scoped FROM access_keys ORDER BY access_key"
+    ).fetchall()
+    return {
+        access_key: _scope(connection, access_key) if scoped else FULL
+        for access_key, scoped in rows
+    }
+
+
+@_write
+def add_access_key(
+    connection: sqlite3.Connection,
+    access_key: str,
+    secret: str,
+    *,
+    scoped: bool = False,
+) -> None:
+    connection.execute(
+        """
+        INSERT INTO access_keys (access_key, secret, created_at, scoped)
+        VALUES (?, ?, ?, ?)
+        """,
+        (access_key, secret, now_ms(), scoped),
+    )
+
+
+@_write
+def grant_bucket(
+    connection: sqlite3.Connection, access_key: str, bucket: str, level: Level
+) -> None:
+    """Give a scoped key a level on a bucket, replacing any it had."""
+    row = connection.execute(
+        "SELECT scoped FROM access_keys WHERE access_key = ?", (access_key,)
+    ).fetchone()
+    if row is None:
+        raise S3Error(errors.INVALID_ACCESS_KEY)
+    if not row[0]:
+        raise S3Error(
+            errors.INVALID_REQUEST,
+            f"{access_key} has full access: a grant would limit nothing.",
+        )
+    _require_bucket(connection, bucket)
+    connection.execute(
+        """
+        INSERT INTO key_grants (access_key, bucket, level) VALUES (?, ?, ?)
+        ON CONFLICT (access_key, bucket) DO UPDATE SET level = excluded.level
+        """,
+        (access_key, bucket, int(level)),
+    )
+
+
+@_write
+def revoke_bucket(connection: sqlite3.Connection, access_key: str, bucket: str) -> bool:
+    cursor = connection.execute(
+        "DELETE FROM key_grants WHERE access_key = ? AND bucket = ?",
+        (access_key, bucket),
+    )
+    return cursor.rowcount > 0
+
+
+@_write
+def delete_access_key(connection: sqlite3.Connection, access_key: str) -> bool:
+    cursor = connection.execute(
+        "DELETE FROM access_keys WHERE access_key = ?", (access_key,)
+    )
+    return cursor.rowcount > 0
+
+
+@_read
+def ping(connection: sqlite3.Connection) -> None:
+    connection.execute("SELECT 1 FROM buckets LIMIT 1").fetchone()
+
+
+#
+# Buckets
+#
+@_read
+def list_buckets(connection: sqlite3.Connection) -> list[BucketRecord]:
+    rows = connection.execute("SELECT name, created_at FROM buckets ORDER BY name")
+    return list(starmap(BucketRecord, rows))
+
+
+@_read
+def require_bucket(connection: sqlite3.Connection, bucket: str) -> None:
+    _require_bucket(connection, bucket)
+
+
+@_write
+def create_bucket(
+    connection: sqlite3.Connection, bucket: str, *, public: bool = False
+) -> None:
+    cursor = connection.execute(
+        """
+        INSERT INTO buckets (name, created_at, public) VALUES (?, ?, ?)
+        ON CONFLICT DO NOTHING
+        """,
+        (bucket, now_ms(), public),
+    )
+    if cursor.rowcount == 0:
+        raise S3Error(errors.BUCKET_ALREADY_OWNED)
+
+
+@_read
+def bucket_is_public(connection: sqlite3.Connection, bucket: str) -> bool:
+    """No bucket and a private one look the same, to those who may not know which."""
+    row = connection.execute(
+        "SELECT public FROM buckets WHERE name = ?", (bucket,)
+    ).fetchone()
+    return row is not None and bool(row[0])
+
+
+@_write
+def set_bucket_public(
+    connection: sqlite3.Connection, bucket: str, *, public: bool
+) -> None:
+    _require_bucket(connection, bucket)
+    connection.execute("UPDATE buckets SET public = ? WHERE name = ?", (public, bucket))
+
+
+@_write
+def set_object_public(
+    connection: sqlite3.Connection,
+    target: ObjectRef,
+    version_id: str | None,
+    *,
+    public: bool,
+) -> str:
+    """Change who may read one version of a key, and return which version that was."""
+    bucket, key = target.bucket, target.key
+    named = _load_version(connection, bucket, key, version_id).version_id
+    parameters = (public, bucket, key, named)
+    connection.execute(
+        "UPDATE objects SET public = ? WHERE bucket = ? AND key = ? AND version_id = ?",
+        parameters,
+    )
+    connection.execute(
+        """
+        UPDATE object_versions SET public = ?
+        WHERE bucket = ? AND key = ? AND version_id = ?
+        """,
+        parameters,
+    )
+    return named
+
+
+@_write
+def delete_bucket(connection: sqlite3.Connection, bucket: str) -> None:
+    _require_bucket(connection, bucket)
+    has_objects = connection.execute(
+        """
+        SELECT 1 FROM objects WHERE bucket = ?
+        UNION ALL SELECT 1 FROM object_versions WHERE bucket = ?
+        LIMIT 1
+        """,
+        (bucket, bucket),
+    ).fetchone()
+    if has_objects:
+        raise S3Error(errors.BUCKET_NOT_EMPTY)
+
+    _queue_for_gc(
+        connection,
+        """
+        SELECT part.blob_id FROM upload_parts AS part
+        JOIN uploads ON uploads.upload_id = part.upload_id
+        WHERE uploads.bucket = ?
+        """,
+        (bucket,),
+    )
+    connection.execute("DELETE FROM uploads WHERE bucket = ?", (bucket,))
+    connection.execute("DELETE FROM buckets WHERE name = ?", (bucket,))
+
+
+#
+# Objects
+#
+@_read
+def get_object(
+    connection: sqlite3.Connection,
+    bucket: str,
+    key: str,
+    version_id: str | None = None,
+) -> ObjectRecord:
+    """Read a version, or if none is named, the current one."""
+    return _load_version(connection, bucket, key, version_id)
+
+
+@_write
+def set_object_tags(
+    connection: sqlite3.Connection,
+    bucket: str,
+    key: str,
+    version_id: str | None,
+    tags: Mapping[str, str],
+) -> str:
+    """Replace a version's tags, and return which version that was.
+
+    Nothing else about it changes, its time included, so an object doesn't look newer
+    to a lifecycle rule for having been tagged.
+    """
+    named = _load_version(connection, bucket, key, version_id).version_id
+    parameters = (_dump_tags(tags), bucket, key, named)
+    # The version is in one of these, whichever it is.
+    connection.execute(
+        "UPDATE objects SET tags = ? WHERE bucket = ? AND key = ? AND version_id = ?",
+        parameters,
+    )
+    connection.execute(
+        """
+        UPDATE object_versions SET tags = ?
+        WHERE bucket = ? AND key = ? AND version_id = ?
+        """,
+        parameters,
+    )
+    return named
+
+
+def _load_version(
+    connection: sqlite3.Connection,
+    bucket: str,
+    key: str,
+    version_id: str | None,
+) -> ObjectRecord:
+    row = connection.execute(
+        """
+        SELECT version_id, size, etag, modified_at, headers, checksum, tags, public,
+               sse_check
+        FROM objects
+        WHERE bucket = ? AND key = ?
+        """,
+        (bucket, key),
+    ).fetchone()
+    if row is not None and version_id in {None, row[0]}:
+        blobs = connection.execute(_BLOBS_OF_CURRENT_VERSION, (bucket, key)).fetchall()
+        return _record_from(key, row[0], row[1:], blobs)
+    _require_bucket(connection, bucket)
+    if version_id is None:
+        raise _no_current_version(connection, bucket, key)
+    return _load_older_version(connection, bucket, key, version_id)
+
+
+def _no_current_version(
+    connection: sqlite3.Connection, bucket: str, key: str
+) -> S3Error:
+    """The error for a key with no current version, naming a delete marker if any."""
+    marker = connection.execute(
+        """
+        SELECT version_id FROM object_versions
+        WHERE bucket = ? AND key = ? AND is_delete_marker = 1
+          AND rank = (SELECT min(rank) FROM object_versions
+                      WHERE bucket = ? AND key = ?)
+        """,
+        (bucket, key, bucket, key),
+    ).fetchone()
+    if marker is None:
+        return S3Error(errors.NO_SUCH_KEY)
+    return S3Error(errors.NO_SUCH_KEY, headers=_delete_marker_headers(marker[0]))
+
+
+def _delete_marker_headers(version_id: str) -> tuple[tuple[str, str], ...]:
+    return (("x-amz-delete-marker", "true"), ("x-amz-version-id", version_id))
+
+
+def _load_older_version(
+    connection: sqlite3.Connection, bucket: str, key: str, version_id: str
+) -> ObjectRecord:
+    row = connection.execute(
+        """
+        SELECT is_delete_marker,
+               size, etag, modified_at, headers, checksum, tags, public, sse_check
+        FROM object_versions
+        WHERE bucket = ? AND key = ? AND version_id = ?
+        """,
+        (bucket, key, version_id),
+    ).fetchone()
+    if row is None:
+        raise S3Error(errors.NO_SUCH_VERSION)
+    if row[0]:
+        raise S3Error(
+            errors.METHOD_NOT_ALLOWED,
+            "This version is a delete marker.",
+            headers=_delete_marker_headers(version_id),
+        )
+    blobs = connection.execute(
+        _BLOBS_OF_OLDER_VERSION, (bucket, key, version_id)
+    ).fetchall()
+    return _record_from(key, version_id, row[1:], blobs)
+
+
+def _record_from(
+    key: str,
+    version_id: str,
+    fields: Sequence[Any],
+    blobs: Iterable[tuple[str, int, str, str]],
+) -> ObjectRecord:
+    """Build a record from a version's fields, which every statement lists alike."""
+    size, etag, modified_at, headers, checksum, tags, public, check = fields
+    return ObjectRecord(
+        key,
+        size,
+        etag,
+        modified_at,
+        json.loads(headers),
+        _load_checksum(checksum),
+        tuple(starmap(_load_blob, blobs)),
+        version_id,
+        _load_tags(tags),
+        bool(public),
+        check,
+    )
+
+
+@_write
+def commit_object(
+    connection: sqlite3.Connection,
+    bucket: str,
+    record: ObjectRecord,
+    condition: WriteCondition,
+) -> str | None:
+    """Make an object visible. This is the only moment a PUT takes effect.
+
+    Returns its version ID, or None if the bucket has never been versioned.
+    """
+    _check_write(connection, bucket, record.key, condition)
+    _insert_blobs(connection, record.blobs)
+    return _store_as_current(connection, bucket, record)
+
+
+@_write
+def delete_object(
+    connection: sqlite3.Connection,
+    bucket: str,
+    key: str,
+    condition: WriteCondition,
+) -> DeleteOutcome:
+    _check_write(connection, bucket, key, condition)
+    return _delete_current(connection, bucket, key)
+
+
+@_write
+def delete_object_version(
+    connection: sqlite3.Connection, bucket: str, key: str, version_id: str
+) -> DeleteOutcome:
+    _require_bucket(connection, bucket)
+    return _erase_version(connection, bucket, key, version_id)
+
+
+@_write
+def delete_objects(
+    connection: sqlite3.Connection, bucket: str, targets: Iterable[DeleteTarget]
+) -> list[DeleteOutcome]:
+    _require_bucket(connection, bucket)
+    return [
+        _delete_current(connection, bucket, target.key)
+        if target.version_id is None
+        else _erase_version(connection, bucket, target.key, target.version_id)
+        for target in targets
+    ]
+
+
+@_read
+def get_versioning(connection: sqlite3.Connection, bucket: str) -> Versioning | None:
+    _require_bucket(connection, bucket)
+    return _versioning(connection, bucket)
+
+
+@_write
+def set_versioning(
+    connection: sqlite3.Connection, bucket: str, state: Versioning
+) -> None:
+    """Set a bucket's state. Once versioned it can be suspended, never un-versioned."""
+    _require_bucket(connection, bucket)
+    connection.execute(
+        "UPDATE buckets SET versioning = ? WHERE name = ?", (state.value, bucket)
+    )
+
+
+@_read
+def list_versions(
+    connection: sqlite3.Connection,
+    bucket: str,
+    query: ListQuery,
+    version_marker: str,
+) -> ListPage[VersionSummary]:
+    _require_bucket(connection, bucket)
+    return listing.scan_versions(
+        partial(_versions_from, connection, bucket), query, version_marker
+    )
+
+
+def _versions_from(
+    connection: sqlite3.Connection, bucket: str, lower: str
+) -> Iterator[VersionSummary]:
+    """Every version from a key on, in key order, and newest first within a key."""
+    current = connection.execute(_LIST_CURRENT_VERSIONS, (bucket, lower))
+    older = connection.execute(_LIST_OLDER_VERSIONS, (bucket, lower))
+    rows = heapq.merge(current, older, key=itemgetter(0, 2))
+    return (
+        VersionSummary(
+            key,
+            version_id,
+            rank,
+            bool(marker),
+            size,
+            etag,
+            modified,
+            tags=_load_tags(tags),
+        )
+        for key, version_id, rank, marker, size, etag, modified, tags in rows
+    )
+
+
+@_read
+def get_lifecycle(connection: sqlite3.Connection, bucket: str) -> str:
+    _require_bucket(connection, bucket)
+    row = connection.execute(
+        "SELECT lifecycle FROM buckets WHERE name = ?", (bucket,)
+    ).fetchone()
+    if row[0] is None:
+        raise S3Error(errors.NO_SUCH_LIFECYCLE)
+    return row[0]
+
+
+@_write
+def set_lifecycle(
+    connection: sqlite3.Connection, bucket: str, configuration: str | None
+) -> None:
+    """Replace a bucket's rules, or remove them with None."""
+    _require_bucket(connection, bucket)
+    connection.execute(
+        "UPDATE buckets SET lifecycle = ? WHERE name = ?", (configuration, bucket)
+    )
+
+
+@_read
+def get_cors(connection: sqlite3.Connection, bucket: str) -> str | None:
+    """A bucket's CORS rules. No bucket and no rules look the same to a browser."""
+    row = connection.execute(
+        "SELECT cors FROM buckets WHERE name = ?", (bucket,)
+    ).fetchone()
+    return None if row is None else row[0]
+
+
+@_write
+def set_cors(
+    connection: sqlite3.Connection, bucket: str, configuration: str | None
+) -> None:
+    """Replace a bucket's CORS rules, or remove them with None."""
+    _require_bucket(connection, bucket)
+    connection.execute(
+        "UPDATE buckets SET cors = ? WHERE name = ?", (configuration, bucket)
+    )
+
+
+@_read
+def lifecycle_due_at(connection: sqlite3.Connection) -> int:
+    row = connection.execute("SELECT lifecycle_not_before FROM settings").fetchone()
+    return row[0]
+
+
+@_write
+def expire_batch(
+    connection: sqlite3.Connection,
+    now: int,
+    day_ms: int,
+    limit: int = _LIFECYCLE_BATCH,
+) -> LifecycleReport:
+    """Apply lifecycle rules to the next stretch of keys, in one transaction.
+
+    One transaction is enough because removing an object only moves rows: its bytes
+    wait for the collector. Keeping the cursor and the pace here spreads one store-wide
+    rate over the workers, with no leader.
+    """
+    position, after_key, not_before = connection.execute(
+        "SELECT lifecycle_bucket, lifecycle_key, lifecycle_not_before FROM settings"
+    ).fetchone()
+    if now < not_before:
+        return LifecycleReport()
+    row = connection.execute(
+        """
+        SELECT name, lifecycle FROM buckets
+        WHERE name >= ? AND lifecycle IS NOT NULL ORDER BY name LIMIT 1
+        """,
+        (position,),
+    ).fetchone()
+    if row is None:
+        _move_lifecycle_cursor(connection, "", "", now + day_ms)  # A pass has ended.
+        return LifecycleReport()
+    bucket, configuration = row
+    if bucket != position:
+        after_key = ""
+    rules = xml_config.parse_lifecycle(configuration.encode())
+    clock = lifecycle.Clock(now, day_ms)
+
+    verdicts, last_key, seen = _judge_next_keys(
+        connection, ObjectRef(bucket, after_key), rules, clock, limit
+    )
+    stale = _stale_uploads(
+        connection, bucket, _KeyRange(after_key, last_key), rules, clock
+    )
+    for key, verdict in verdicts:
+        for version_id in verdict.erase:
+            _erase_version(connection, bucket, key, version_id)
+        if verdict.expire_current:
+            _delete_current(connection, bucket, key)
+    for upload_id in stale:
+        _remove_upload(connection, upload_id)
+
+    removals = sum(verdict.removals for _, verdict in verdicts) + len(stale)
+    pause_ms = (
+        seen * _MILLISECONDS // _LIFECYCLE_VERSIONS_PER_SECOND
+        + removals * _MILLISECONDS // _LIFECYCLE_REMOVALS_PER_SECOND
+    )
+    if last_key is None:
+        _move_lifecycle_cursor(connection, bucket + _AFTER, "", now + pause_ms)
+    else:
+        _move_lifecycle_cursor(connection, bucket, last_key, now + pause_ms)
+    return LifecycleReport(
+        expired=sum(verdict.expire_current for _, verdict in verdicts),
+        erased=sum(len(verdict.erase) for _, verdict in verdicts),
+        aborted=len(stale),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class _KeyRange:
+    """The keys after one, through another, or to the end with None."""
+
+    after: str
+    through: str | None
+
+
+def _judge_next_keys(
+    connection: sqlite3.Connection,
+    after: ObjectRef,
+    rules: Sequence[LifecycleRule],
+    clock: lifecycle.Clock,
+    limit: int,
+) -> tuple[list[tuple[str, KeyVerdict]], str | None, int]:
+    """Judge whole keys after one, up to a limit. Also returns the last, if more may
+    follow, and how many versions were seen.
+
+    Read before anything changes: what a query sees of changes made while it runs is
+    undefined. A key is never split, since its versions are judged against each other.
+    """
+    # ponytail: a key with a great many versions makes one long batch. Walk it in
+    # stretches, keeping the last version seen, if a store has such keys.
+    verdicts: list[tuple[str, KeyVerdict]] = []
+    seen = removals = 0
+    rows = _versions_from(connection, after.bucket, after.key + _AFTER)
+    for key, group in groupby(rows, key=attrgetter("key")):
+        versions = list(group)
+        verdict = lifecycle.judge_key(rules, versions, clock)
+        verdicts.append((key, verdict))
+        seen += len(versions)
+        removals += verdict.removals
+        if seen >= limit or removals >= LIFECYCLE_BATCH_REMOVALS:
+            return verdicts, key, seen
+    return verdicts, None, seen
+
+
+def _stale_uploads(
+    connection: sqlite3.Connection,
+    bucket: str,
+    key_range: _KeyRange,
+    rules: Sequence[LifecycleRule],
+    clock: lifecycle.Clock,
+) -> list[str]:
+    """Uploads past their time, among the keys this batch covers."""
+    # ponytail: a great many uploads between two keys make one long batch. Count them
+    # towards the limit, if a store collects that many before its first rule.
+    after_key, last_key = key_range.after, key_range.through
+    rows = connection.execute(
+        """
+        SELECT upload_id, key, created_at FROM uploads
+        WHERE bucket = ? AND key > ? AND (? IS NULL OR key <= ?)
+        ORDER BY key
+        """,
+        (bucket, after_key, last_key, last_key),
+    )
+    return [
+        upload_id
+        for upload_id, key, created_at in rows
+        if lifecycle.upload_is_stale(rules, key, created_at, clock)
+    ]
+
+
+def _move_lifecycle_cursor(
+    connection: sqlite3.Connection, bucket: str, key: str, not_before: int
+) -> None:
+    connection.execute(
+        """
+        UPDATE settings
+        SET lifecycle_bucket = ?, lifecycle_key = ?, lifecycle_not_before = ?
+        """,
+        (bucket, key, not_before),
+    )
+
+
+@_read
+def list_objects(
+    connection: sqlite3.Connection, bucket: str, query: ListQuery
+) -> ListPage:
+    _require_bucket(connection, bucket)
+
+    def fetch(lower: str, upper: str | None, limit: int) -> Iterator[ObjectSummary]:
+        rows = (
+            connection.execute(_LIST_OBJECTS, (bucket, lower, limit))
+            if upper is None
+            else connection.execute(_LIST_OBJECTS_BELOW, (bucket, lower, upper, limit))
+        )
+        return starmap(ObjectSummary, rows)
+
+    return listing.scan(fetch, query)
+
+
+#
+# Multipart uploads
+#
+@_write
+def create_upload(
+    connection: sqlite3.Connection,
+    upload: UploadRef,
+    headers: Mapping[str, str],
+    checksum: ChecksumPlan | None = None,
+    extras: UploadExtras = NO_EXTRAS,
+) -> None:
+    _require_bucket(connection, upload.bucket)
+    connection.execute(
+        """
+        INSERT INTO uploads
+            (upload_id, bucket, key, headers, created_at,
+             checksum_algorithm, checksum_type, tags, public, sse_check)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            upload.upload_id,
+            upload.bucket,
+            upload.key,
+            json.dumps(headers),
+            now_ms(),
+            checksum and checksum.algorithm,
+            checksum and checksum.checksum_type,
+            _dump_tags(extras.tags),
+            extras.public,
+            extras.sse_check,
+        ),
+    )
+
+
+@_read
+def require_upload(connection: sqlite3.Connection, upload: UploadRef) -> Upload:
+    return _load_upload(connection, upload)
+
+
+@_write
+def commit_part(
+    connection: sqlite3.Connection,
+    upload: UploadRef,
+    number: int,
+    blob: Blob,
+    checksum: Checksum | None,
+) -> None:
+    """Record a part. Uploading the same number again replaces the earlier one."""
+    _load_upload(connection, upload)
+    _queue_for_gc(
+        connection,
+        "SELECT blob_id FROM upload_parts WHERE upload_id = ? AND part_number = ?",
+        (upload.upload_id, number),
+    )
+    _insert_blobs(connection, (blob,))
+    connection.execute(
+        """
+        INSERT OR REPLACE INTO upload_parts
+            (upload_id, part_number, blob_id, checksum, modified_at)
+        VALUES (?, ?, ?, ?, ?)
+        """,
+        (upload.upload_id, number, blob.blob_id, _dump_checksum(checksum), now_ms()),
+    )
+
+
+@_write
+def complete_upload(
+    connection: sqlite3.Connection,
+    upload: UploadRef,
+    request: CompletionRequest,
+    condition: WriteCondition,
+) -> CompletedUpload:
+    """Turn parts into an object in one transaction, without touching any data.
+
+    A retry after a lost reply must succeed rather than report NoSuchUpload for an
+    upload that did complete, so the result stays available for a while. A claim
+    that turns out false rolls everything back, so the client can complete it again.
+    """
+    previous = connection.execute(
+        """
+        SELECT etag, checksum, version_id FROM completed_uploads
+        WHERE upload_id = ? AND bucket = ? AND key = ?
+        """,
+        (upload.upload_id, upload.bucket, upload.key),
+    ).fetchone()
+    if previous is not None:
+        completed = CompletedUpload(
+            previous[0], _load_checksum(previous[1]), previous[2]
+        )
+        multipart.check_checksum_claims(request, completed.checksum)
+        return completed
+
+    started = _load_upload(connection, upload)
+    _check_write(connection, upload.bucket, upload.key, condition)
+    parts = _load_parts(connection, upload.upload_id, 0, _NO_LIMIT)
+    assembly = multipart.assemble(
+        request.parts,
+        {part.number: part for part in parts},
+        # Encrypted parts take a little more room than the bytes they hold.
+        sse.plain_size if started.sse_check else None,
+    )
+    checksum = multipart.object_checksum(started.checksum, assembly.parts)
+    multipart.check_checksum_claims(request, checksum)
+    multipart.check_size_claim(request, assembly.size)
+
+    record = ObjectRecord(
+        upload.key,
+        assembly.size,
+        assembly.etag,
+        now_ms(),
+        started.headers,
+        checksum,
+        assembly.blobs,
+        tags=started.tags,
+        public=started.public,
+        sse_check=started.sse_check,
+    )
+    connection.executemany(
+        "INSERT INTO blob_gc (blob_id, due_at) VALUES (?, ?)",
+        [(blob_id, _gc_due_at()) for blob_id in assembly.unused_blob_ids],
+    )
+    connection.execute("DELETE FROM uploads WHERE upload_id = ?", (upload.upload_id,))
+    version_id = _store_as_current(connection, upload.bucket, record)
+    connection.execute(
+        """
+        INSERT INTO completed_uploads
+            (upload_id, bucket, key, etag, completed_at, checksum, version_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            upload.upload_id,
+            upload.bucket,
+            upload.key,
+            record.etag,
+            record.modified_at,
+            _dump_checksum(checksum),
+            version_id,
+        ),
+    )
+    return CompletedUpload(record.etag, checksum, version_id)
+
+
+@_write
+def abort_upload(connection: sqlite3.Connection, upload: UploadRef) -> None:
+    _load_upload(connection, upload)
+    _remove_upload(connection, upload.upload_id)
+
+
+def _remove_upload(connection: sqlite3.Connection, upload_id: str) -> None:
+    _queue_for_gc(
+        connection,
+        "SELECT blob_id FROM upload_parts WHERE upload_id = ?",
+        (upload_id,),
+    )
+    connection.execute("DELETE FROM uploads WHERE upload_id = ?", (upload_id,))
+
+
+@_read
+def list_parts(
+    connection: sqlite3.Connection, upload: UploadRef, after_part: int, limit: int
+) -> list[Part]:
+    _load_upload(connection, upload)
+    return _load_parts(connection, upload.upload_id, after_part, limit)
+
+
+@_read
+def list_uploads(
+    connection: sqlite3.Connection,
+    bucket: str,
+    prefix: str,
+    after: tuple[str, str],
+    limit: int,
+) -> list[Upload]:
+    """List uploads in (key, upload ID) order, after the given position."""
+    _require_bucket(connection, bucket)
+    upper = listing.key_after_prefix(prefix) if prefix else None
+    rows = connection.execute(
+        """
+        SELECT upload_id, bucket, key, headers, created_at,
+               checksum_algorithm, checksum_type
+        FROM uploads
+        WHERE bucket = ? AND key >= ? AND (? IS NULL OR key < ?)
+          AND (key, upload_id) > (?, ?)
+        ORDER BY key, upload_id LIMIT ?
+        """,
+        (bucket, prefix, upper, upper, *after, limit),
+    )
+    return [
+        Upload(
+            upload_id,
+            row_bucket,
+            key,
+            json.loads(headers),
+            created_at,
+            _load_plan(algorithm, checksum_type),
+        )
+        for (
+            upload_id,
+            row_bucket,
+            key,
+            headers,
+            created_at,
+            algorithm,
+            checksum_type,
+        ) in rows
+    ]
+
+
+#
+# Blob collection and consistency checks
+#
+@_read
+def blobs_due_for_collection(
+    connection: sqlite3.Connection, now: int, limit: int
+) -> dict[str, tuple[int, ...]]:
+    """Each blob due, in order, with the volumes it is on."""
+    rows = connection.execute(
+        """
+        SELECT due.blob_id,
+               (SELECT group_concat(here.volume_id) FROM blob_locations AS here
+                WHERE here.blob_id = due.blob_id)
+        FROM blob_gc AS due
+        WHERE due.due_at <= ?
+        ORDER BY due.due_at LIMIT ?
+        """,
+        (now, limit),
+    )
+    return {blob_id: _load_volume_ids(volume_ids) for blob_id, volume_ids in rows}
+
+
+@_write
+def forget_completed_uploads(connection: sqlite3.Connection, before: int) -> None:
+    connection.execute(
+        "DELETE FROM completed_uploads WHERE completed_at < ?", (before,)
+    )
+
+
+@_write
+def forget_blobs(connection: sqlite3.Connection, blob_ids: Sequence[str]) -> None:
+    parameters = [(blob_id,) for blob_id in blob_ids]
+    connection.executemany("DELETE FROM blob_gc WHERE blob_id = ?", parameters)
+    connection.executemany("DELETE FROM blobs WHERE blob_id = ?", parameters)
+
+
+@_read
+def all_blobs(connection: sqlite3.Connection) -> dict[str, KnownBlob]:
+    # ponytail: loads every ID into memory; stream with a sorted merge if fsck
+    # has to run on stores too large for that.
+    rows = connection.execute(
+        """
+        SELECT blobs.blob_id, blobs.size, blob_gc.blob_id IS NOT NULL,
+               (SELECT group_concat(here.volume_id) FROM blob_locations AS here
+                WHERE here.blob_id = blobs.blob_id)
+        FROM blobs LEFT JOIN blob_gc USING (blob_id)
+        """
+    )
+    return {
+        blob_id: KnownBlob(size, bool(queued), _load_volume_ids(volume_ids))
+        for blob_id, size, queued, volume_ids in rows
+    }
+
+
+#
+# Volumes
+#
+@_write
+def add_volume(connection: sqlite3.Connection, identity: str, path: str) -> int:
+    row = connection.execute(
+        "INSERT INTO volumes (identity, path) VALUES (?, ?) RETURNING volume_id",
+        (identity, path),
+    ).fetchone()
+    return row[0]
+
+
+@_read
+def current_volumes(
+    connection: sqlite3.Connection,
+) -> tuple[tuple[VolumeRecord, ...], int]:
+    """Every volume and the number of copies, for workers to follow changes."""
+    return _load_volumes(connection), _copies(connection)
+
+
+@_write
+def set_copies(connection: sqlite3.Connection, copies: int) -> None:
+    connection.execute("UPDATE settings SET copies = ?", (copies,))
+    connection.execute(
+        """
+        INSERT OR IGNORE INTO repair_queue (blob_id, due_at)
+        SELECT location.blob_id, 0 FROM blob_locations AS location
+        WHERE NOT EXISTS (SELECT 1 FROM blob_gc WHERE blob_id = location.blob_id)
+        GROUP BY location.blob_id HAVING count(*) < ?
+        """,
+        (copies,),
+    )
+
+
+@_write
+def drain_volume(connection: sqlite3.Connection, volume_id: int) -> None:
+    """Stop using a volume, and queue what it holds for moving elsewhere."""
+    copies = _copies(connection)
+    others = connection.execute(
+        "SELECT count(*) FROM volumes WHERE draining = 0 AND volume_id != ?",
+        (volume_id,),
+    ).fetchone()[0]
+    if others < copies:
+        message = (
+            f"{others} other volumes can't hold {copies} copies: "
+            "add a volume or lower the copies first"
+        )
+        raise VolumeChangeError(message)
+    if not _set_draining(connection, volume_id):
+        message = f"no volume {volume_id}"
+        raise VolumeChangeError(message)
+    _queue_blobs_on_volume(connection, volume_id)
+
+
+def _set_draining(connection: sqlite3.Connection, volume_id: int) -> bool:
+    updated = connection.execute(
+        "UPDATE volumes SET draining = 1 WHERE volume_id = ?", (volume_id,)
+    )
+    return updated.rowcount == 1
+
+
+def _queue_blobs_on_volume(connection: sqlite3.Connection, volume_id: int) -> None:
+    connection.execute(
+        """
+        INSERT OR IGNORE INTO repair_queue (blob_id, due_at)
+        SELECT location.blob_id, 0 FROM blob_locations AS location
+        WHERE location.volume_id = ?
+          AND NOT EXISTS (SELECT 1 FROM blob_gc WHERE blob_id = location.blob_id)
+        """,
+        (volume_id,),
+    )
+
+
+@_write
+def forget_volume(
+    connection: sqlite3.Connection,
+    volume_id: int,
+    *,
+    disk_lost: bool = False,
+    accept_loss: bool = False,
+) -> None:
+    """Remove a volume that is empty, or whose disk is gone for good."""
+    row = connection.execute(
+        "SELECT path FROM volumes WHERE volume_id = ?", (volume_id,)
+    ).fetchone()
+    if row is None:
+        message = f"no volume {volume_id}"
+        raise VolumeChangeError(message)
+    if row[0] == ".":
+        message = "the data directory stays a volume; drain it to empty it"
+        raise VolumeChangeError(message)
+    held = connection.execute(
+        "SELECT count(*) FROM blob_locations WHERE volume_id = ?", (volume_id,)
+    ).fetchone()[0]
+    if held and not disk_lost:
+        message = (
+            f"volume {volume_id} holds {held} blobs: drain it, "
+            "or say the disk is gone with --disk-lost"
+        )
+        raise VolumeChangeError(message)
+    only_copies = connection.execute(
+        """
+        SELECT count(*) FROM blob_locations AS here
+        WHERE here.volume_id = ?
+          AND NOT EXISTS (SELECT 1 FROM blob_gc WHERE blob_id = here.blob_id)
+          AND NOT EXISTS (
+              SELECT 1 FROM blob_locations AS other
+              WHERE other.blob_id = here.blob_id AND other.volume_id != here.volume_id
+          )
+        """,
+        (volume_id,),
+    ).fetchone()[0]
+    if only_copies and not accept_loss:
+        message = (
+            f"{only_copies} blobs have no other copy, so their objects would be "
+            "lost: if the disk really is gone, say so with --accept-loss"
+        )
+        raise VolumeChangeError(message)
+    _queue_blobs_on_volume(connection, volume_id)
+    connection.execute("DELETE FROM blob_locations WHERE volume_id = ?", (volume_id,))
+    connection.execute("DELETE FROM volumes WHERE volume_id = ?", (volume_id,))
+
+
+#
+# Repair
+#
+@_read
+def repairs_due(connection: sqlite3.Connection, now: int) -> bool:
+    """Whether a claim could find anything, without queueing for the writer lock."""
+    row = connection.execute(
+        "SELECT 1 FROM repair_queue WHERE due_at <= ? LIMIT 1", (now,)
+    ).fetchone()
+    return row is not None
+
+
+@_read
+def repairs_queued(connection: sqlite3.Connection) -> int:
+    return connection.execute("SELECT count(*) FROM repair_queue").fetchone()[0]
+
+
+@_read
+def blobs_awaiting_collection(connection: sqlite3.Connection) -> int:
+    return connection.execute("SELECT count(*) FROM blob_gc").fetchone()[0]
+
+
+@_write
+def claim_repairs(
+    connection: sqlite3.Connection, now: int, limit: int, lease_ms: int
+) -> list[RepairWork]:
+    """Take a batch for a while: other workers skip it, and a crash gives it back."""
+    rows = connection.execute(
+        """
+        SELECT blob.blob_id, blob.size, blob.md5,
+               (SELECT group_concat(here.volume_id) FROM blob_locations AS here
+                WHERE here.blob_id = blob.blob_id),
+               EXISTS (SELECT 1 FROM blob_gc WHERE blob_id = blob.blob_id)
+        FROM repair_queue AS queued
+        JOIN blobs AS blob ON blob.blob_id = queued.blob_id
+        WHERE queued.due_at <= ?
+        ORDER BY queued.due_at LIMIT ?
+        """,
+        (now, limit),
+    ).fetchall()
+    connection.executemany(
+        "DELETE FROM repair_queue WHERE blob_id = ?",
+        [(row[0],) for row in rows if row[4]],
+    )
+    connection.executemany(
+        "UPDATE repair_queue SET due_at = ? WHERE blob_id = ?",
+        [(now + lease_ms, row[0]) for row in rows if not row[4]],
+    )
+    copies = _copies(connection)
+    draining = _draining_volumes(connection)
+    return [
+        RepairWork(
+            Blob(blob_id, size, md5, _load_volume_ids(volume_ids)), copies, draining
+        )
+        for blob_id, size, md5, volume_ids, queued_for_collection in rows
+        if not queued_for_collection
+    ]
+
+
+@_write
+def add_location(connection: sqlite3.Connection, blob_id: str, volume_id: int) -> bool:
+    """Record a new copy. False if the blob has gone, and the copy with it."""
+    exists = connection.execute(
+        "SELECT 1 FROM blobs WHERE blob_id = ?", (blob_id,)
+    ).fetchone()
+    if exists is None:
+        return False
+    connection.execute(
+        "INSERT OR IGNORE INTO blob_locations (blob_id, volume_id) VALUES (?, ?)",
+        (blob_id, volume_id),
+    )
+    return True
+
+
+@_write
+def postpone_repair(connection: sqlite3.Connection, blob_id: str, due_at: int) -> None:
+    connection.execute(
+        "UPDATE repair_queue SET due_at = ? WHERE blob_id = ?", (due_at, blob_id)
+    )
+
+
+@_write
+def finish_repair(connection: sqlite3.Connection, blob_id: str) -> bool:
+    """Take a blob off the queue, if it now has what it needs.
+
+    Checked here and not by the caller, whose view may be old: scrub may have removed
+    a copy since, and queueing the blob again did nothing while it was still queued.
+    """
+    held = connection.execute(
+        """
+        SELECT count(*), coalesce(sum(volume.draining), 0)
+        FROM blob_locations AS location JOIN volumes AS volume USING (volume_id)
+        WHERE location.blob_id = ?
+        """,
+        (blob_id,),
+    ).fetchone()
+    copies, draining = held
+    if copies - draining < _copies(connection) or draining:
+        return False
+    connection.execute("DELETE FROM repair_queue WHERE blob_id = ?", (blob_id,))
+    return True
+
+
+@_read
+def other_copies(
+    connection: sqlite3.Connection, blob_id: str, volume_id: int
+) -> int | None:
+    """How many other copies a blob has, or None if it is gone or on its way out."""
+    row = connection.execute(
+        """
+        SELECT count(other.volume_id) FROM blobs AS blob
+        LEFT JOIN blob_locations AS other
+            ON other.blob_id = blob.blob_id AND other.volume_id != ?
+        WHERE blob.blob_id = ?
+          AND NOT EXISTS (SELECT 1 FROM blob_gc WHERE blob_id = blob.blob_id)
+        GROUP BY blob.blob_id
+        """,
+        (volume_id, blob_id),
+    ).fetchone()
+    return None if row is None else row[0]
+
+
+@_write
+def remove_location(
+    connection: sqlite3.Connection, blob_id: str, volume_id: int
+) -> None:
+    """Forget a copy whose file has gone, and queue the blob if that leaves it short."""
+    connection.execute(
+        "DELETE FROM blob_locations WHERE blob_id = ? AND volume_id = ?",
+        (blob_id, volume_id),
+    )
+    connection.execute(
+        """
+        INSERT OR IGNORE INTO repair_queue (blob_id, due_at)
+        SELECT ?, 0 FROM settings
+        WHERE copies > (SELECT count(*) FROM blob_locations WHERE blob_id = ?)
+          AND NOT EXISTS (SELECT 1 FROM blob_gc WHERE blob_id = ?)
+          AND EXISTS (SELECT 1 FROM blobs WHERE blob_id = ?)
+        """,
+        (blob_id, blob_id, blob_id, blob_id),
+    )
+
+
+#
+# Scrub
+#
+@_read
+def scrub_due_at(connection: sqlite3.Connection) -> int:
+    row = connection.execute("SELECT scrub_not_before FROM settings").fetchone()
+    return row[0]
+
+
+@_write
+def claim_scrub_batch(
+    connection: sqlite3.Connection, now: int, limit: int, bytes_per_second: int
+) -> list[Blob]:
+    """Take the next blobs to check, and hold off every worker for what they cost.
+
+    Keeping the cursor and the pace here spreads one store-wide rate over the workers,
+    with no leader, and carries on from where it was after a restart.
+    """
+    cursor, not_before = connection.execute(
+        "SELECT scrub_cursor, scrub_not_before FROM settings"
+    ).fetchone()
+    if now < not_before:
+        return []
+    batch = _blobs_to_scrub(connection, cursor, limit)
+    cost = sum(blob.size + _SCRUB_MIN_BYTES_PER_BLOB for blob in batch)
+    pause_ms = cost * _MILLISECONDS // bytes_per_second
+    finished_a_pass = len(batch) < limit
+    connection.execute(
+        "UPDATE settings SET scrub_cursor = ?, scrub_not_before = ?",
+        (
+            "" if finished_a_pass else batch[-1].blob_id,
+            now + (SCRUB_REST_MS if finished_a_pass else pause_ms),
+        ),
+    )
+    return batch
+
+
+@_read
+def blobs_to_scrub(
+    connection: sqlite3.Connection, after: str, limit: int
+) -> list[Blob]:
+    return _blobs_to_scrub(connection, after, limit)
+
+
+def _blobs_to_scrub(
+    connection: sqlite3.Connection, after: str, limit: int
+) -> list[Blob]:
+    rows = connection.execute(
+        """
+        SELECT blob.blob_id, blob.size, blob.md5,
+               (SELECT group_concat(here.volume_id) FROM blob_locations AS here
+                WHERE here.blob_id = blob.blob_id)
+        FROM blobs AS blob
+        WHERE blob.blob_id > ?
+          AND NOT EXISTS (SELECT 1 FROM blob_gc WHERE blob_id = blob.blob_id)
+        ORDER BY blob.blob_id LIMIT ?
+        """,
+        (after, limit),
+    )
+    return [
+        Blob(blob_id, size, md5, _load_volume_ids(volume_ids))
+        for blob_id, size, md5, volume_ids in rows
+    ]
+
+
+@_read
+def blobs_per_volume(connection: sqlite3.Connection) -> dict[int, int]:
+    rows = connection.execute(
+        "SELECT volume_id, count(*) FROM blob_locations GROUP BY volume_id"
+    )
+    return dict(rows.fetchall())
+
+
+#
+# Helpers: pieces of a transaction, called only from the functions above.
+#
+def _require_bucket(connection: sqlite3.Connection, bucket: str) -> None:
+    row = connection.execute(
+        "SELECT 1 FROM buckets WHERE name = ?", (bucket,)
+    ).fetchone()
+    if row is None:
+        raise S3Error(errors.NO_SUCH_BUCKET)
+
+
+def _check_write(
+    connection: sqlite3.Connection,
+    bucket: str,
+    key: str,
+    condition: WriteCondition,
+) -> None:
+    _require_bucket(connection, bucket)
+    row = connection.execute(
+        "SELECT etag FROM objects WHERE bucket = ? AND key = ?", (bucket, key)
+    ).fetchone()
+    conditions.check_write_condition(condition, row[0] if row else None)
+
+
+def _insert_blobs(connection: sqlite3.Connection, blobs: Iterable[Blob]) -> None:
+    connection.executemany(
+        "INSERT INTO blobs (blob_id, size, md5) VALUES (?, ?, ?)",
+        [(blob.blob_id, blob.size, blob.md5) for blob in blobs],
+    )
+    connection.executemany(
+        "INSERT INTO blob_locations (blob_id, volume_id) VALUES (?, ?)",
+        [(blob.blob_id, volume_id) for blob in blobs for volume_id in blob.volume_ids],
+    )
+    copies = _copies(connection)
+    draining = _draining_volumes(connection)
+    connection.executemany(
+        "INSERT OR IGNORE INTO repair_queue (blob_id, due_at) VALUES (?, 0)",
+        [
+            (blob.blob_id,)
+            for blob in blobs
+            if len(blob.volume_ids) < copies or draining.intersection(blob.volume_ids)
+        ],
+    )
+
+
+def _copies(connection: sqlite3.Connection) -> int:
+    return connection.execute("SELECT copies FROM settings").fetchone()[0]
+
+
+def _draining_volumes(connection: sqlite3.Connection) -> frozenset[int]:
+    rows = connection.execute("SELECT volume_id FROM volumes WHERE draining = 1")
+    return frozenset(row[0] for row in rows)
+
+
+def _insert_object(
+    connection: sqlite3.Connection, bucket: str, record: ObjectRecord
+) -> None:
+    connection.execute(
+        """
+        INSERT INTO objects
+            (bucket, key, version_id,
+             size, etag, modified_at, headers, checksum, tags, public, sse_check)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            bucket,
+            record.key,
+            record.version_id,
+            record.size,
+            record.etag,
+            record.modified_at,
+            json.dumps(record.headers),
+            _dump_checksum(record.checksum),
+            _dump_tags(record.tags),
+            record.public,
+            record.sse_check,
+        ),
+    )
+    connection.executemany(
+        """
+        INSERT INTO object_blobs (bucket, key, position, blob_id)
+        VALUES (?, ?, ?, ?)
+        """,
+        [
+            (bucket, record.key, position, blob.blob_id)
+            for position, blob in enumerate(record.blobs)
+        ],
+    )
+
+
+def _remove_object(connection: sqlite3.Connection, bucket: str, key: str) -> None:
+    """Remove the current object, if any, and queue its bytes for collection."""
+    _queue_for_gc(
+        connection,
+        "SELECT blob_id FROM object_blobs WHERE bucket = ? AND key = ?",
+        (bucket, key),
+    )
+    connection.execute(
+        "DELETE FROM objects WHERE bucket = ? AND key = ?", (bucket, key)
+    )
+
+
+def _versioning(connection: sqlite3.Connection, bucket: str) -> Versioning | None:
+    row = connection.execute(
+        "SELECT versioning FROM buckets WHERE name = ?", (bucket,)
+    ).fetchone()
+    return Versioning(row[0]) if row[0] else None
+
+
+def _store_as_current(
+    connection: sqlite3.Connection, bucket: str, record: ObjectRecord
+) -> str | None:
+    """Put a new version in place, keeping or discarding the old as the bucket says."""
+    state = _versioning(connection, bucket)
+    if state is None:
+        _remove_object(connection, bucket, record.key)
+        version_id = None
+    elif state is Versioning.ENABLED:
+        _archive_current(connection, bucket, record.key)
+        version_id = _new_version_id()
+    else:
+        _clear_null_version(connection, bucket, record.key)
+        version_id = NULL_VERSION_ID
+    _insert_object(
+        connection,
+        bucket,
+        replace(record, version_id=version_id or NULL_VERSION_ID),
+    )
+    return version_id
+
+
+def _new_version_id() -> str:
+    return secrets.token_urlsafe(_VERSION_ID_BYTES)
+
+
+def _delete_current(
+    connection: sqlite3.Connection, bucket: str, key: str
+) -> DeleteOutcome:
+    """Delete a key: for good if unversioned, or else behind a new delete marker."""
+    state = _versioning(connection, bucket)
+    if state is None:
+        _remove_object(connection, bucket, key)
+        return DeleteOutcome(key)
+    if state is Versioning.ENABLED:
+        _archive_current(connection, bucket, key)
+        version_id = _new_version_id()
+    else:
+        _clear_null_version(connection, bucket, key)
+        version_id = NULL_VERSION_ID
+    connection.execute(
+        """
+        INSERT INTO object_versions
+            (bucket, key, version_id, rank, is_delete_marker,
+             size, etag, modified_at, headers, checksum)
+        VALUES (?, ?, ?, ?, 1, 0, '', ?, '{}', NULL)
+        """,
+        (bucket, key, version_id, _next_rank(connection, bucket, key), now_ms()),
+    )
+    return DeleteOutcome(key, version_id, is_delete_marker=True)
+
+
+def _next_rank(connection: sqlite3.Connection, bucket: str, key: str) -> int:
+    row = connection.execute(
+        "SELECT min(rank) FROM object_versions WHERE bucket = ? AND key = ?",
+        (bucket, key),
+    ).fetchone()
+    return -1 if row[0] is None else row[0] - 1
+
+
+def _archive_current(connection: sqlite3.Connection, bucket: str, key: str) -> None:
+    """Make the current version an older one. Its blobs stay exactly where they are."""
+    rank = _next_rank(connection, bucket, key)
+    copied = connection.execute(
+        """
+        INSERT INTO object_versions
+            (bucket, key, version_id, rank, is_delete_marker,
+             size, etag, modified_at, headers, checksum, tags, public, sse_check)
+        SELECT bucket, key, version_id, ?, 0,
+               size, etag, modified_at, headers, checksum, tags, public, sse_check
+        FROM objects WHERE bucket = ? AND key = ?
+        """,
+        (rank, bucket, key),
+    )
+    if copied.rowcount == 0:
+        return
+    connection.execute(
+        """
+        INSERT INTO version_blobs (bucket, key, version_id, position, blob_id)
+        SELECT link.bucket, link.key, objects.version_id, link.position, link.blob_id
+        FROM object_blobs AS link
+        JOIN objects USING (bucket, key)
+        WHERE link.bucket = ? AND link.key = ?
+        """,
+        (bucket, key),
+    )
+    connection.execute(
+        "DELETE FROM objects WHERE bucket = ? AND key = ?", (bucket, key)
+    )
+
+
+def _clear_null_version(connection: sqlite3.Connection, bucket: str, key: str) -> None:
+    """Make way for a new version named "null", which replaces any before it."""
+    current = connection.execute(
+        "SELECT version_id FROM objects WHERE bucket = ? AND key = ?", (bucket, key)
+    ).fetchone()
+    if current is not None and current[0] == NULL_VERSION_ID:
+        _remove_object(connection, bucket, key)
+    else:
+        _archive_current(connection, bucket, key)
+    _remove_older_version(connection, bucket, key, NULL_VERSION_ID)
+
+
+def _remove_older_version(
+    connection: sqlite3.Connection, bucket: str, key: str, version_id: str
+) -> bool:
+    """Remove an older version or marker, if any, and queue its bytes for collection."""
+    _queue_for_gc(
+        connection,
+        """
+        SELECT blob_id FROM version_blobs
+        WHERE bucket = ? AND key = ? AND version_id = ?
+        """,
+        (bucket, key, version_id),
+    )
+    removed = connection.execute(
+        """
+        DELETE FROM object_versions WHERE bucket = ? AND key = ? AND version_id = ?
+        """,
+        (bucket, key, version_id),
+    )
+    return removed.rowcount > 0
+
+
+def _erase_version(
+    connection: sqlite3.Connection, bucket: str, key: str, version_id: str
+) -> DeleteOutcome:
+    """Remove one version for good, so that the next newest may become current."""
+    current = connection.execute(
+        "SELECT version_id FROM objects WHERE bucket = ? AND key = ?", (bucket, key)
+    ).fetchone()
+    if current is not None and current[0] == version_id:
+        _remove_object(connection, bucket, key)
+        _promote_newest(connection, bucket, key)
+        return DeleteOutcome(key, version_id)
+    row = connection.execute(
+        """
+        SELECT is_delete_marker FROM object_versions
+        WHERE bucket = ? AND key = ? AND version_id = ?
+        """,
+        (bucket, key, version_id),
+    ).fetchone()
+    if row is None:
+        return DeleteOutcome(key, version_id)  # As with a key, gone is gone.
+    _remove_older_version(connection, bucket, key, version_id)
+    if current is None:
+        _promote_newest(connection, bucket, key)
+    return DeleteOutcome(key, version_id, is_delete_marker=bool(row[0]))
+
+
+def _promote_newest(connection: sqlite3.Connection, bucket: str, key: str) -> None:
+    """With no current version, the newest older one takes over, unless a marker."""
+    newest = connection.execute(
+        """
+        SELECT version_id, is_delete_marker FROM object_versions
+        WHERE bucket = ? AND key = ? ORDER BY rank LIMIT 1
+        """,
+        (bucket, key),
+    ).fetchone()
+    if newest is None or newest[1]:
+        return
+    version_id = newest[0]
+    connection.execute(
+        """
+        INSERT INTO objects
+            (bucket, key, version_id,
+             size, etag, modified_at, headers, checksum, tags, public, sse_check)
+        SELECT bucket, key, version_id,
+               size, etag, modified_at, headers, checksum, tags, public, sse_check
+        FROM object_versions WHERE bucket = ? AND key = ? AND version_id = ?
+        """,
+        (bucket, key, version_id),
+    )
+    connection.execute(
+        """
+        INSERT INTO object_blobs (bucket, key, position, blob_id)
+        SELECT bucket, key, position, blob_id FROM version_blobs
+        WHERE bucket = ? AND key = ? AND version_id = ?
+        """,
+        (bucket, key, version_id),
+    )
+    connection.execute(
+        """
+        DELETE FROM object_versions WHERE bucket = ? AND key = ? AND version_id = ?
+        """,
+        (bucket, key, version_id),
+    )
+
+
+def _queue_for_gc(
+    connection: sqlite3.Connection, select_blob_ids: str, parameters: tuple[object, ...]
+) -> None:
+    rows = connection.execute(select_blob_ids, parameters).fetchall()
+    due_at = _gc_due_at()
+    connection.executemany(
+        "INSERT INTO blob_gc (blob_id, due_at) VALUES (?, ?)",
+        [(row[0], due_at) for row in rows],
+    )
+
+
+def _gc_due_at() -> int:
+    return now_ms() + GC_GRACE_MS
+
+
+def _load_upload(connection: sqlite3.Connection, upload: UploadRef) -> Upload:
+    row = connection.execute(
+        """
+        SELECT headers, created_at, checksum_algorithm, checksum_type, tags, public,
+               sse_check
+        FROM uploads
+        WHERE upload_id = ? AND bucket = ? AND key = ?
+        """,
+        (upload.upload_id, upload.bucket, upload.key),
+    ).fetchone()
+    if row is None:
+        raise S3Error(errors.NO_SUCH_UPLOAD)
+    return Upload(
+        upload.upload_id,
+        upload.bucket,
+        upload.key,
+        json.loads(row[0]),
+        row[1],
+        _load_plan(row[2], row[3]),
+        _load_tags(row[4]),
+        bool(row[5]),
+        row[6],
+    )
+
+
+def _load_plan(algorithm: str | None, checksum_type: str | None) -> ChecksumPlan | None:
+    if algorithm is None or checksum_type is None:
+        return None
+    return ChecksumPlan(algorithm, ChecksumType(checksum_type))
+
+
+def _load_parts(
+    connection: sqlite3.Connection, upload_id: str, after_part: int, limit: int
+) -> list[Part]:
+    """Load parts in order."""
+    rows = connection.execute(
+        """
+        SELECT part.part_number, blob.blob_id, blob.size, blob.md5,
+               (SELECT group_concat(here.volume_id) FROM blob_locations AS here
+                WHERE here.blob_id = blob.blob_id),
+               part.checksum, part.modified_at
+        FROM upload_parts AS part
+        JOIN blobs AS blob ON blob.blob_id = part.blob_id
+        WHERE part.upload_id = ? AND part.part_number > ?
+        ORDER BY part.part_number LIMIT ?
+        """,
+        (upload_id, after_part, limit),
+    )
+    return [
+        Part(
+            number,
+            _load_blob(blob_id, size, md5, volume_ids),
+            _load_checksum(checksum),
+            modified_at,
+        )
+        for number, blob_id, size, md5, volume_ids, checksum, modified_at in rows
+    ]
+
+
+def _load_blob(blob_id: str, size: int, md5: str, volume_ids: str) -> Blob:
+    return Blob(blob_id, size, md5, _load_volume_ids(volume_ids))
+
+
+def _load_volume_ids(volume_ids: str | None) -> tuple[int, ...]:
+    """Parse `group_concat`, which gives NULL for a blob with no location left."""
+    return tuple(map(int, volume_ids.split(","))) if volume_ids else ()
+
+
+def _dump_tags(tags: Mapping[str, str]) -> str | None:
+    return json.dumps(tags) if tags else None
+
+
+def _load_tags(text: str | None) -> dict[str, str]:
+    return json.loads(text) if text else {}
+
+
+def _dump_checksum(checksum: Checksum | None) -> str | None:
+    if checksum is None:
+        return None
+    return json.dumps({"algorithm": checksum.algorithm, "value": checksum.value})
+
+
+def _load_checksum(text: str | None) -> Checksum | None:
+    return None if text is None else Checksum(**json.loads(text))