Skip to content

Alembic Migrations

Status: ✅ Shipped — 148 revisions on disk, one linear chain (a single historical merge point), one head: a9c2e4f71b08. (re-verified 2026-08-21 vs Sectorwars2102 HEAD 3b0a683a)

Source: services/gameserver/alembic/versions/

Current head: a9c2e4f71b08 — station_governance_votes — syndicate policy motions. Initial revision: c138b33baec4 — initial schema with stations terminology.

There is one head; no pending divergent branches. The chain is linear except for one merge revision (c1d2e3f4a5b6) that joins the genesis-formation and terraforming branches.

Chain (initial → head)

c138b33baec4  initial schema with stations terminology
   └── e86cb8130b5b  rename_all_port_columns_to_station
        └── dbbfad27a7ef  change planet population columns to bigint
             └── fe22441146b1  add personal reputation and military rank to players
                  └── c5e32c313020  update_ship_thresholds_for_balanced_gameplay
                       └── ec92f8afd44a  add_guard_personality_to_first_login_sessions
                            └── 6b1d95a38c98  tighten_scout_ship_thresholds_for_strict_consistency
                                 └── 6acc65ee7a72  add_ai_logging_fields_to_dialogue_exchange
                                      └── 2e78250f47bc  lower_scout_ship_thresholds_for_balanced_gameplay
                                           └── 5f5a988bdbb1  add current_port_id and current_planet_id to players
                                                ├── a3f7c2d91e54  add genesis formation columns to planets
                                                └── a1b2c3d4e5f6  add planet morale and siege_turns columns
                                                     └── b2c3d4e5f6a7  add terraforming columns to planets
                                                          └── (merge)
                                                               c1d2e3f4a5b6  merge genesis and terraforming heads
                                                                    └── d2e3f4a5b6c7  add attack_turn_cost and equipment_slots to ships
                                                                         └── e3f4a5b6c7d8  add citadel fields to planets
                                                                              └── f4a5b6c7d8e9  add ARIA consciousness fields to players
                                                                                   └── … further additive revisions (special-formations, bang integration, NPC runtime, contracts, warp gates, ARIA data index, ship registry, multi-account detection, pirate ecosystem, storage lockers, player trade, RBAC, NPC lodging, and more) …
                                                                                        └── f6b2d8a41c90  NPC lodging foundation — barracks/outlaw tables + sector flags + home FKs
                                                                                             └── a9c2e4f71b08  station_governance_votes — syndicate policy motions  ← HEAD

Notable revisions

148 revisions exist on disk. The table below curates the chain's structural anchors (root, the one merge, head), every revision cross-referenced by ID elsewhere in this doc set, and every revision that adds a new table. For the complete graph, run alembic history from services/gameserver.

Revision File Purpose
c138b33baec4 c138b33baec4_initial_schema_with_stations_terminology.py Initial schema; uses stations (not ports) as the primary terminology from the start.
e86cb8130b5b e86cb8130b5b_rename_all_port_columns_to_station.py Renames residual port_* columns/tables to station_* for consistency.
dbbfad27a7ef dbbfad27a7ef_change_planet_population_columns_to_.py Widens planets.population, max_population, citadel population columns to BigInteger.
fe22441146b1 fe22441146b1_add_personal_reputation_and_military_.py Adds Player.personal_reputation, reputation_tier, name_color, military_rank, rank_points.
c5e32c313020 c5e32c313020_update_ship_thresholds_for_balanced_.py Rebalances ship_rarity_configs thresholds.
ec92f8afd44a ec92f8afd44a_add_guard_personality_to_first_login_.py Adds guard personality columns (guard_name, guard_title, guard_trait, guard_base_suspicion, guard_description) to first_login_sessions.
6b1d95a38c98 6b1d95a38c98_tighten_scout_ship_thresholds_for_.py Tightens scout-ship rarity thresholds.
6acc65ee7a72 6acc65ee7a72_add_ai_logging_fields_to_dialogue_.py Adds AI provider/prompt/response/cost/tokens columns to dialogue_exchanges.
2e78250f47bc 2e78250f47bc_lower_scout_ship_thresholds_for_.py Further scout threshold rebalance.
5f5a988bdbb1 5f5a988bdbb1_add_current_port_id_and_current_planet_.py Adds Player.current_port_id and current_planet_id for docked/landed state.
a1b2c3d4e5f6 a1b2c3d4e5f6_add_planet_morale_and_siege_turns.py Adds siege state columns (under_siege, siege_started_at, siege_attacker_id) and morale-related fields to planets.
a3f7c2d91e54 a3f7c2d91e54_add_genesis_formation_columns_to_planets.py Adds genesis_created, genesis_device_id, genesis_tier, formation_status, formation_started_at, formation_complete_at on planets.
b2c3d4e5f6a7 b2c3d4e5f6a7_add_terraforming_columns_to_planets.py Adds terraforming columns to planets (parallel branch with the genesis-formation work).
c1d2e3f4a5b6 c1d2e3f4a5b6_merge_genesis_and_terraforming_heads.py Merge revision joining a3f7c2d91e54 and b2c3d4e5f6a7 back into a single head.
d2e3f4a5b6c7 d2e3f4a5b6c7_add_attack_turn_cost_and_equipment_slots.py Adds Ship.attack_turn_cost and Ship.equipment_slots; mirrors attack_turn_cost on ship_specifications.
e3f4a5b6c7d8 e3f4a5b6c7d8_add_citadel_fields_to_planets.py Adds citadel columns: citadel_level, citadel_upgrading, citadel_upgrade_started_at, citadel_upgrade_complete_at, citadel_safe_credits, citadel_safe_max, citadel_drone_capacity, citadel_max_population.
f4a5b6c7d8e9 f4a5b6c7d8e9_add_aria_fields_to_players.py Adds aria_bonus_multiplier, aria_consciousness_level, aria_relationship_score, aria_total_interactions to players.
7c2e91d6f4b8 7c2e91d6f4b8_add_special_formations_table.py Adds the special_formations table for graph-topology landmarks (Bubble/Tunnel/Dead-End/etc.) — see ./special-formations.md.
a8d1f4e6c920 a8d1f4e6c920_bang_generation_jobs.py Adds bang_generation_jobs, tracking async galaxy-generation jobs.
f8b2d4c61a35 f8b2d4c61a35_add_npc_characters_and_npc_ships.py Adds the npc_characters table and NPC-only ship-hull support.
e5f8a7c92d46 e5f8a7c92d46_pending_engagements.py Adds pending_engagements plus Sector.is_nexus_protected.
f8d3a1c9e527 f8d3a1c9e527_npc_runtime_drift_repair.py Idempotent catch-up repair for partial NPC-runtime state left by an earlier drifted migration.
c7d1e9f3a2b8 c7d1e9f3a2b8_add_migration_contracts.py Adds migration_contracts — the pioneer migration contract layer.
d3f7a91c2b84 d3f7a91c2b84_processed_webhook_events.py Adds processed_webhook_events, the idempotency ledger for payment webhooks (ADR-0058) — see ./gameplay.md#processedwebhookevent.
e7c4a1b9d602 e7c4a1b9d602_phase2_dormant_columns.py Phase-2 dormant-feature columns (region treasury + construction events), additive ahead of the features reading them.
f1a2b3c4d5e6 f1a2b3c4d5e6_adr_schema_parity_warps_naming_nexus.py ADR schema-parity pass: drops a stale galaxy-config column, adds is_latent to warps, cluster/formation naming columns.
a7c3e1f9b264 a7c3e1f9b264_adr0005_compound_sector_identity_capital.py ADR-0005: additive compound sector identity + Capital Sector columns.
a1d4f9c7b3e2 a1d4f9c7b3e2_phase4_schema_foundation.py Phase-4 schema foundation: additive columns, new tables, faction_type enum values — see ./gameplay.md.
c5a8e2f1b9d3 c5a8e2f1b9d3_adr0059_governance_real_schema.py ADR-0059 regional-governance real schema (replaces earlier stop-gap columns).
e864a8aaa392 e864a8aaa392_add_region_invites_tables.py Adds region_invites + region_invite_redemptions.
f4a9c7e21b6d f4a9c7e21b6d_add_cargo_wrecks.py Adds cargo_wrecks — see ./cargo-wrecks.md.
f1a4d7b2c9e3 f1a4d7b2c9e3_player_warp_knowledge.py Adds player_warp_knowledge, per-player latent-warp discovery state (ADR-0045) — see ./player.md#playerwarpknowledge.
e1f3a7b2c9d4 e1f3a7b2c9d4_drop_orphan_market_transactions_table.py Drops the orphaned legacy market_transactions table.
150381baa0c5 150381baa0c5_drop_faction_missions.py Drops the vestigial faction_missions table — missions are not part of the canonical loop per ADR-0032.
cdea102d345b cdea102d345b_add_route_optimization_runs.py Adds route_optimization_runs.
a3f9e1c74b28 a3f9e1c74b28_add_gate_construction_sites.py Adds gate_construction_sites (ADR-0078 staged warp-gate construction).
fea17cc334a8 fea17cc334a8_add_player_formation_knowledge.py Adds player_formation_knowledge, per-player special-formation discovery (ADR-0045) — see ./player.md.
eb772a1ab433 eb772a1ab433_add_aria_trading_observations.py Adds aria_trading_observations.
e8b619503a44 e8b619503a44_add_pirate_ecosystem_foundation.py Adds the pirate-ecosystem foundation: PirateHolding, PirateKillLog, Region.pirate_ecosystem_state — see ./pirate-holdings.md.
1aab831e9008 1aab831e9008_add_contracts_table.py Adds contracts — see ../FEATURES/economy/contracts.md.
9f1e216e2321 9f1e216e2321_phantom_table_catchup_docking_port_.py Phantom-table catch-up: commits 8 tables that previously existed only via create_all() at startup, not a tracked revision.
d4c8f6a12e93 d4c8f6a12e93_multi_account_detection_schema.py Adds the multi-account-detection schema: MultiAccountCluster, MultiAccountFlag — see ./gameplay.md#multiaccountcluster.
4c7660b879f7 4c7660b879f7_ship_registry_schema.py Adds the ShipRegistry schema-only rollout — see ./ships.md#shipregistry.
26ea004450dc 26ea004450dc_aria_data_streams.py Adds the ARIA data-index registry (aria_data_streams) — see ./aria-data-index.md.
40ce9a434884 40ce9a434884_aria_memory_type_canon_rename.py Renames aria_personal_memories.memory_type values to the canon stream keys.
86baeee81847 86baeee81847_add_message_beacons.py Adds message_beacons + Sector.message_beacons JSONB column — see ./galaxy.md#sector.
61b7e6f4ff93 61b7e6f4ff93_add_storage_locker_and_cargo_deposit.py Adds storage_lockers + contract_cargo_deposits — see ../FEATURES/economy/storage-lockers.md.
b9a7404a2c20 b9a7404a2c20_unique_locker_per_player_contract.py Adds a unique (owner_player_id, contract_id) index on storage_lockers, guarding against duplicate-locker races.
f6b2d8a41c90 f6b2d8a41c90_npc_lodging_foundation.py Adds npc_barracks / outlaw_bases, sectors.is_outlaw_zone / is_npc_barracks_sector, and nullable NPC home FKs — see ./npc-lodging.md.
a9c2e4f71b08 a9c2e4f71b08_station_governance_votes.py HEAD — Adds station_governance_votes (syndicate policy motions; revises NPC lodging head).

Pending / out-of-band

  • No pending migrations on disk (head matches the latest model state for the columns surveyed in this docs pass).
  • The services/gameserver/sql/ directory carries hand-written bootstrap scripts (init-central-nexus.sql, init-region.sql, ai-companion-schema.sql, enhanced-ai-system-schema.sql) that are run outside Alembic for multi-region database provisioning and AI/companion side-tables. These are not tracked in the alembic revision graph.
  • Side-table models that exist in code but are not visibly covered by named migrations (likely created within the initial schema or supplemental SQL): ARIAPersonalMemory, ARIAMarketIntelligence, ARIAExplorationMap, ARIATradingPattern, AIComprehensiveAssistant, PlayerTradingProfile, AIRecommendation, Translation, OAuthAccount, RefreshToken, MFASecret, MFAAttempt, PlayerCredentials. Verify against the initial migration before deploying to a fresh region.

How to extend

  1. alembic revision --autogenerate -m "<short summary>" from the gameserver service.
  2. Hand-edit the generated revision to remove noise and ensure ENUM/CHECK constraints round-trip correctly.
  3. Add a row to the table above and update the chain diagram if the new revision changes the head.