Schema Migration

July 18, 2026 · View on GitHub

This document defines how codex-auth versions the on-disk ~/.codex/accounts/registry.json file.

Terms

  • app_version is the CLI release version from src/version.zig.
  • schema_version is the registry file format version stored in registry.json.
  • schema_version is about migration only; it is not the same thing as the CLI release version.

Current Policy

  • The current persisted format is schema_version = 4.
  • The compatibility guarantee for this release is migration from released schema 3 to the final schema 4 format.
  • The legacy version = 2 loader remains available, but it is not the compatibility boundary for this change.
  • The current binary accepts current-layout files that still use the old top-level key version = 3, or still carry the old global last_attributed_rollout shape, and rewrites them to normalized schema_version = 4.
  • If the binary sees a newer schema_version than it understands, it fails with UnsupportedRegistryVersion and must not write the file.

Upgrade Behavior

  • User-visible behavior is always “upgrade directly to the latest supported schema”.
  • Internally, migrations are implemented as a chain of Vn -> Vn+1 steps.
  • The guaranteed automatic migration is schema_version = 3 -> schema_version = 4.
  • The existing legacy version = 2 loader also rewrites directly to schema 4.
  • Users are not expected to install intermediate codex-auth versions.

Schema History

  • version = 2
    • Email-keyed account snapshots
    • active_email
    • Email-based account identity
  • schema_version = 3
    • Record-key-based account snapshots
    • active_account_key
    • active_account_activated_at_ms
    • Per-account last_local_rollout
    • Legacy top-level api block, now ignored and omitted on rewrite
    • Per-account account_key
    • Each account also stores chatgpt_account_id and chatgpt_user_id
  • schema_version = 4
    • Same account layout as schema 3
    • Live refresh interval stored as top-level interval_seconds
    • Older live.interval_seconds and removed auto_switch blocks are omitted on rewrite
    • Adds top-level previous_active_account_key for codex-auth - and codex-auth switch -
    • Persisted plans use final product semantics rather than backend identifiers
    • Legacy team becomes business
    • Legacy business becomes enterprise
    • The same conversion applies to per-account last_usage.plan_type

When To Bump schema_version

Before bumping schema_version, ask the user whether this change should bump the schema. Do not bump it silently.

Bump the schema version whenever the persisted registry.json shape or semantics change. That includes:

  • Adding, removing, or renaming a persisted field
  • Changing a field type
  • Changing identity keys such as active_email to active_account_key
  • Changing snapshot filename conventions or any other rule needed to find persisted files
  • Reinterpreting an existing field with incompatible semantics

Do not bump the schema version for:

  • CLI output changes
  • Pure in-memory logic changes
  • Help text or documentation changes
  • Runtime behavior changes that do not alter persisted registry data

Migration Rules

  • A supported older schema must auto-migrate on load and then rewrite registry.json in the current format.
  • Supported migrations should preserve account records, active account selection, and account snapshot usability.
  • Migration rewrites create the usual registry.json.bak.* backup before replacing the file.
  • import --purge remains a manual recovery path if a registry is corrupted or too old for the current binary, but it is not the normal path between supported schemas.