Skip to content

Migrate pre-existing catalog tables to UUIDv7 primary keys #219

@GitAddRemote

Description

@GitAddRemote

User Story

As a backend engineer, I want all pre-existing station_* and uex_* catalog table primary keys converted from BIGSERIAL to UUIDv7, so that externally-exposed IDs are opaque, time-ordered, and safe to use in URLs and API responses without leaking row count or insertion order.

Background

Issue #194 introduced UUIDv7 PKs for station_jump_point (a new table). All pre-existing catalog tables still use BIGSERIAL:

station_* tables (ETL-synced, no API endpoints yet):

  • station_star_system, station_orbit, station_planet, station_moon
  • station_city, station_space_station, station_outpost, station_poi
  • station_faction, station_jurisdiction, station_company
  • station_terminal, station_orbit_distance

uex_* tables (exposed via /api/uex/* endpoints today):

  • uex_star_system, uex_planet, uex_moon, uex_city
  • uex_space_station, uex_outpost, uex_poi, uex_commodity
  • uex_company, uex_category, uex_item

Definition of Done

  • All tables listed above have id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY
  • All BIGINT FK columns referencing the old BIGSERIAL PKs updated to UUID
  • station_terminal FK columns (star_system_id, planet_id, orbit_id, moon_id, space_station_id, outpost_id, poi_id, city_id, faction_id, company_id) converted to UUID
  • TypeORM entity files updated to use uuid column type where applicable
  • ETL step upserts updated to supply UUIDv7 (via uuidv7() from the uuid package, already declared as a dependency) on insert, preserve existing UUID on conflict
  • Migration has working up() and down() methods
  • All unit tests pass
  • Migration tested with pnpm migration:revert in development

Technical Notes

  • The uuid package (^11.1.0) is already declared as a backend dependency
  • UUIDv7 is time-ordered — B-tree indexes on UUID PKs will not fragment more than BIGSERIAL
  • ETL steps currently use raw SQL upserts (ON CONFLICT (uex_id) DO UPDATE) — the id column is not part of those conflict targets, so the ETL upsert strategy is unaffected; only the insert path needs uuidv7() supplied
  • The uex_* entity files use @PrimaryGeneratedColumn({ type: 'bigint' }) — these need to change to @PrimaryGeneratedColumn('uuid') or @Column({ type: 'uuid', primary: true })
  • Do the migration in a single coordinated up() to avoid FK constraint violations mid-migration

Acceptance Criteria

  • SELECT id FROM station_star_system LIMIT 1 returns a UUID, not an integer
  • SELECT id FROM uex_star_system LIMIT 1 returns a UUID, not an integer
  • GET /api/uex/star-systems returns id fields as UUIDs
  • Re-running the ETL after migration produces no errors

Metadata

Metadata

Assignees

No one assigned

    Labels

    backendBackend services and logicdatabaseSchema, migrations, indexingenhancementNew feature or requesttech-storyTechnical implementation story

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions