69 lines
4 KiB
Markdown
69 lines
4 KiB
Markdown
|
# 🕵️ DB Migrations Audit V1
|
||
|
|
|
||
|
|
**Date:** 04/12/2025
|
||
|
|
**Author:** Staff Engineer / DBA
|
||
|
|
**Scope:** `veza-backend-api` Database Schema & Migrations
|
||
|
|
|
||
|
|
## 1. Executive Summary
|
||
|
|
|
||
|
|
The current database schema is in a **transitional "Hybrid" state**, resulting from an incomplete migration from `INT/BIGINT` to `UUID`. While core entities (`users`, `tracks`, `playlists`) have been migrated to UUIDs, the surrounding infrastructure (secondary tables, audit logs, tokens, junction tables) remains largely on `BIGINT` sequences.
|
||
|
|
|
||
|
|
This audit establishes the roadmap to move from this "Lab/Repair" state to a **Canonical V1 Schema** that is purely UUID-based, consistent, and production-ready.
|
||
|
|
|
||
|
|
**Note on Source of Truth:** The file `docs/ORIGIN_DATABASE_SCHEMA.md` was referenced but not found. This audit treats `docs/UUID_DB_MIGRATION_PLAN.md` (Target Architecture) and the current `veza_uuid_lab_schema.sql` (Entity Inventory) as the combined Source of Truth.
|
||
|
|
|
||
|
|
## 2. Gap Analysis: Lab Schema vs. Target V1
|
||
|
|
|
||
|
|
### 2.1 Core Conformance (Status: ✅ Mostly Good)
|
||
|
|
The core entities align with the UUID target.
|
||
|
|
* **Users:** `id` is UUID.
|
||
|
|
* **Tracks:** `id` is UUID.
|
||
|
|
* **Playlists:** `id` is UUID.
|
||
|
|
* **RBAC (Roles/Permissions):** `id` is UUID.
|
||
|
|
|
||
|
|
### 2.2 Critical Deficiencies (Status: ❌ Needs Fix)
|
||
|
|
The following tables currently use `BIGINT` (SERIAL) Primary Keys in the Lab Schema. In V1, these **MUST** be `UUID`.
|
||
|
|
|
||
|
|
| Domain | Table | Current PK | Target V1 PK |
|
||
|
|
| :--- | :--- | :--- | :--- |
|
||
|
|
| **Auth** | `refresh_tokens` | `bigint` | `UUID` |
|
||
|
|
| **Auth** | `password_reset_tokens` | `bigint` | `UUID` |
|
||
|
|
| **Auth** | `email_verification_tokens` | `bigint` | `UUID` |
|
||
|
|
| **Auth** | `user_sessions` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `bitrate_adaptation_logs` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `hls_streams` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `hls_transcode_queue` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `playback_analytics` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `track_comments` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `track_history` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `track_likes` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `track_plays` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `track_shares` | `bigint` | `UUID` |
|
||
|
|
| **Streaming** | `track_versions` | `bigint` | `UUID` |
|
||
|
|
| **Social** | `playlist_collaborators` | `bigint` | `UUID` |
|
||
|
|
| **Social** | `playlist_follows` | `bigint` | `UUID` |
|
||
|
|
| **Chat (Legacy)**| `rooms` | `bigint` | `UUID` |
|
||
|
|
|
||
|
|
### 2.3 Structural Issues
|
||
|
|
1. **Inconsistent Defaults:** Some tables use `now()`, others `CURRENT_TIMESTAMP`. V1 will standardize on `TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP`.
|
||
|
|
2. **Missing `deleted_at`:** Several tables lacking soft-delete where implied by domain (e.g., `playlist_collaborators` has it, but `playlist_tracks` does not). V1 will apply soft-deletes consistently for user-managed resources.
|
||
|
|
3. **Foreign Key Constraints:** Many FKs in the Lab schema lack explicit `ON DELETE` rules. V1 will enforce `ON DELETE CASCADE` for ownership relationships (e.g., User -> RefreshToken) and `ON DELETE SET NULL` or `RESTRICT` for references.
|
||
|
|
|
||
|
|
## 3. Schema Governance & Separation
|
||
|
|
|
||
|
|
Per `UUID_DB_MIGRATION_PLAN.md`:
|
||
|
|
* **`public` Schema:** Owned by `veza-backend-api`. Contains `users`, `auth`, `tracks`, `playlists` (and their satellite tables).
|
||
|
|
* **`chat` Schema:** Owned by `veza-chat-server`. Contains `conversations`, `messages`.
|
||
|
|
|
||
|
|
**V1 Scope Decision:**
|
||
|
|
The `veza-backend-api` migrations will **strictly manage the `public` schema**.
|
||
|
|
* Legacy `rooms` table (if still used by Go) will be migrated to UUID in `public`.
|
||
|
|
* New `chat` schema tables will **NOT** be created by these migrations to respect the separation of concerns, unless a specific "Schema Init" migration is required for integration tests.
|
||
|
|
|
||
|
|
## 4. Recommendation
|
||
|
|
|
||
|
|
Proceed with the **V1 "Clean Slate" Strategy**:
|
||
|
|
1. Archive all existing `001`...`072` migrations.
|
||
|
|
2. Create a fresh set of migrations (`001`...`999`) that define the tables correctly (UUID) from the start.
|
||
|
|
3. Do not implement "repair" scripts; implement the "final state".
|