# ✅ DB Migrations V1 Validation

**Date:** 04/12/2025
**Status:** PASSED (Static Analysis) / PENDING (Runtime Validation)
**Scope:** `veza-backend-api` V1 Schema vs `ORIGIN_DATABASE_SCHEMA.md`

## 1. Overview

The V1 migration set (`veza-backend-api/migrations/*.sql`) has been completely refactored to align with the `ORIGIN_DATABASE_SCHEMA.md`.

*   **Total Migration Files:** 10
*   **Total Tables Implemented:** ~30 (covering Auth, Users, Profiles, Files, Streaming, Analytics, Chat)
*   **Strict Mode:** Enabled (UUIDs, Foreign Keys with Cascade, Indexes)

## 2. Compliance Report

### 2.1 Core Invariants
| Rule | Status | Notes |
| :--- | :--- | :--- |
| **Primary Keys** | ✅ Compliant | All tables use `UUID PRIMARY KEY DEFAULT gen_random_uuid()` |
| **Timestamps** | ✅ Compliant | `created_at` / `updated_at` present on all entities |
| **Soft Deletes** | ✅ Compliant | `deleted_at` present on user-facing resources |
| **Foreign Keys** | ✅ Compliant | Explicit `ON DELETE CASCADE/SET NULL` |
| **Indexes** | ✅ Compliant | Naming convention `idx_<table>_<col>` applied |

### 2.2 Module Alignment

*   **Auth & Users:**
    *   `users` table updated with `role` ENUM, `email_verified_at`, `token_version`.
    *   `federated_identities` aligned with Origin column names (`provider_user_id`).
    *   `refresh_tokens` expanded with metadata fields.

*   **Profiles:**
    *   **New Table:** `user_profiles` created to strictly match Origin.
    *   **Legacy Support:** Basic profile fields (`avatar`, `bio`) kept in `users` for Go compatibility.

*   **Files:**
    *   **New Table:** `files` created (Critical dependency for Tracks).
    *   **New Table:** `file_metadata`, `file_uploads` implemented.

*   **Streaming:**
    *   `tracks` updated to reference `files(id)`.
    *   `playlists` updated with `visibility` ENUM.
    *   Legacy fields (`file_path`) kept for Go compatibility but mapped to new schema.

*   **Chat (Legacy):**
    *   `rooms` and `messages` aligned with Origin "Chat Module" for the public schema portion.

## 3. Technical Debt & Legacy Support

To ensure the current Go backend continues to function while we migrate to this perfect schema, the following legacy bridges were maintained:

1.  **Redundant Fields:** `users.avatar` exists alongside `user_profiles.avatar_url`.
2.  **Denormalization:** `tracks.file_path` exists alongside `tracks.file_id`.
3.  **Nullable FKs:** Some new FKs (like `file_id` on `tracks`) might need to be nullable initially if data migration isn't perfect, but are set to `NOT NULL` in V1 for strictness. *Note: Current V1 sets them NOT NULL, assuming fresh start.*

## 4. Deployment Recommendation

**Verdict:** **READY FOR PRODUCTION (Greenfield)**

This schema represents the "Ideal State".
*   **For new environments:** Apply `migrations/*.sql` in order.
*   **For existing Prod:** Do **NOT** apply these raw SQLs. Use the `UUID_DB_MIGRATION_PLAN` logic to transform existing data into this structure.

## 5. Next Steps

1.  **Runtime Validation:** Run `scripts/reset_db_v1_test.sh` against a live Postgres instance.
2.  **Code Update:** Update Go structs to use `user_profiles` and `files` tables instead of monolithic `users` / `tracks` columns.