browser/openspec/changes/add-mysql-platform-metadata-storage/design.md

Design

Metadata backend

PLATFORM_STORAGE_BACKEND selects the platform metadata store:

• file: default local durable snapshot at PLATFORM_METADATA_PATH.
• memory: test/disposable storage.
• mysql: MySQL-backed metadata snapshot using PLATFORM_MYSQL_DSN.

The first MySQL implementation stores one platform-owned JSON snapshot in a platform_metadata_snapshots table. This gives operators a real durable MySQL option now while preserving the existing repo.Store boundary. Later changes can normalize individual repositories into relational tables without changing handlers or services.

Log body backend

PLATFORM_LOG_BODY_BACKEND selects log body storage separately:

• empty: follows the metadata backend, except mysql maps to file.
• file: segmented JSONL log files in PLATFORM_LOG_DIR.
• memory: tests/disposable local runs.

MySQL metadata storage does not imply MySQL log bodies. Hundreds or thousands of servers should use segmented files for local deployments and log-optimized stores such as ClickHouse, Loki, OpenSearch/Elasticsearch, or object-storage segments in production.

Docker guidance

The root docker-compose.yml keeps the default file backend. It includes commented MySQL service/config blocks so operators can uncomment them when they want local MySQL metadata:

PLATFORM_STORAGE_BACKEND=mysql
PLATFORM_MYSQL_DSN=platform:platform@tcp(mysql:3306)/platform?parseTime=true
PLATFORM_LOG_BODY_BACKEND=file

Failure behavior

If PLATFORM_STORAGE_BACKEND=mysql is set without PLATFORM_MYSQL_DSN, platform startup fails with a direct configuration error. If the DSN is present but the database is unreachable, startup fails fast rather than silently falling back to memory.