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

Research direction

Start with the contract in #199 and its dedicated domain-contract issue, which must be settled before changing the canonical Prisma/PostgreSQL model. Review the current production schema, then use additive Prisma migrations and upgrade tests; done means PostgreSQL 17 applies every migration without drift, preserves historical data, and satisfies the listed constraints and indexes.

Written by the indexing model from the issue text.

Assessment

Tech stack
postgresql
Domain
backend-api-design, databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.