coder13 / coder13/LetsCube

Add the PostgreSQL Room and RaceSession schema

Open
#203 0 comments 0 reactions 0 assignees View on GitHub
area: data area: results enhancement priority: P1
Dominant language
JavaScript
Stars
30
Forks
9
PR merge metrics
No merged PRs in 30d

Description

Part of #199.

## Goal

Reshape the canonical Prisma/PostgreSQL model so rooms can own multiple independent race sessions without changing production read ownership yet.

## Schema direction

- Keep room identity, access, lifecycle, ownership, and optional competition association on `app.rooms`.
- Add `app.race_sessions` with room, event, format/mode, scramble source, state, scheduled times, and actual start/end times.
- Move current racing fields such as `cube_event`, `started`, and `next_solve_at` from their conceptual ownership on Room to RaceSession.
- Add session-level participant state for competing, waiting, and eligibility/registration where required by the domain contract.
- Make attempts reference `race_session_id`.
- Keep solves related through attempts; remove or deprecate redundant `room_id` only through an expand-and-contract migration.
- Preserve existing stable solve, attempt, room, and user identifiers.
- Add the minimal competition association defined by the domain contract.

## Migration requirements

- Use additive Prisma migrations first.
- Do not perform a destructive migration in application startup.
- Keep the currently deployed application compatible during the expansion phase.
- Add appropriate foreign keys, uniqueness constraints, and indexes for:
- active sessions by room;
- session attempt ordering;
- user solve history;
- competition-room session lookup;
- migration reconciliation.
- Define explicit delete/archive behavior. Historical solves must not cascade away because a room is hidden or archived.

## Acceptance criteria

- [ ] Prisma models and committed migrations represent the approved domain contract.
- [ ] Existing PostgreSQL data remains readable during rollout.
- [ ] A fresh PostgreSQL 17 database applies every migration with zero drift.
- [ ] Upgrade tests run from the current production schema.
- [ ] Foreign-key and uniqueness constraints reject invalid cross-room/session relationships.
- [ ] Indexes cover active room/session and history read paths.
- [ ] No migration deletes historical attempts or solves.
- [ ] Rollback compatibility and the later contract phase are documented.

## Dependencies

- The contract in #199 and its dedicated domain-contract issue must be settled first.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.