Add production-ready database migration system with node-pg-migrate

[Copilot]

Replaces manual schema.sql application with a proper migration system using node-pg-migrate, idempotent bootstrap script, and protected GitHub Actions workflow.

Key Changes

Migration Infrastructure

• database/migration-config.js - node-pg-migrate configuration reading DATABASE_URL and PGSSLMODE
• database/migrations/0001_initial.js - Initial schema as JS migration with up/down support
• database/seeds/0001_seeds.sql - Idempotent seeds using ON CONFLICT DO NOTHING

Bootstrap Tooling

• scripts/bootstrap-db.sh - Executable script with dependency validation and error handling
• Package.json scripts: migrate:up, migrate:down, db:bootstrap

CI/CD

• .github/workflows/db-bootstrap.yml - Manual workflow with environment approval gates
• Only applies seeds to staging; production gets schema only

Documentation

• docs/DB_MIGRATIONS.md - Local setup, CI/CD flow, troubleshooting, security practices

Technical Decisions

pgcrypto over uuid-ossp: Uses gen_random_uuid() instead of uuid_generate_v4() for better compatibility with managed PostgreSQL providers (Supabase, RDS, etc.) that restrict extension permissions.

JavaScript migrations: Enables programmatic up/down migrations with built-in transaction support, rather than raw SQL files.

Usage

Local development:

export DATABASE_URL="postgresql://..."
./scripts/bootstrap-db.sh

Create migrations:

pnpm run migrate create add_user_preferences

Production deployment via GitHub Actions requires manual approval from protected environment reviewers.

Original prompt

But : ajouter une gestion de migrations robuste et un bootstrap idempotent pour la base de données Supabase, plus quelques fichiers d'accompagnement et adaptation du workflow CI.

Contexte :

• Repo: CorentynDevPro/StarForge
• Objectif : remplacer l'approche actuelle (schema.sql appliqué manuellement) par une solution professionnelle et reproductible utilisant node-pg-migrate (migrations up/down), script de bootstrap pour dev/CI, .env.example, et un workflow GitHub Actions manuel protégé exécutant les migrations sur la DATABASE_URL stockée en secret.

Tâches à réaliser dans la PR :

1. Ajouter node-pg-migrate et configuration
   • Créer fichier database/migration-config.js qui lit DATABASE_URL & PGSSLMODE depuis l'environnement et exporte la config attendue par node-pg-migrate.
   • Ajouter migration initiale database/migrations/0001_initial.js (JS migration) qui crée les tables, indexes, triggers et insère les roles + feature flags/guild seeds. La migration doit être idempotente (utiliser ifNotExists / createTable options) et utiliser transactions.
2. Ajouter script de bootstrap
   • scripts/bootstrap-db.sh : script shell exécutable qui vérifie psql/node-pg-migrate installés, exporte PGSSLMODE=require si non défini, exécute pnpm install --frozen-lockfile (optionnel), puis node-pg-migrate up --config database/migration-config.js, puis applique seeds SQL si présents. Le script doit proposer fallback : si la migration échoue à cause de l'extension uuid-ossp, rerun migration after enabling pgcrypto variant; implémenter logique simple : detecter l'erreur contenant 'permission denied to create extension' ou similaire.
3. Ajouter schema_pgcrypto.sql ou migration alternative si nécessaire
   • Inclure database/schema_pgcrypto.sql (comme fournie précédemment) ou ensure migration uses pgcrypto by default by creating extension IF NOT EXISTS pgcrypto first; pour robustesse, la migration initiale doit CREATE EXTENSION IF NOT EXISTS pgcrypto; et utiliser gen_random_uuid() rather than uuid_generate_v4() to avoid uuid-ossp permission issues on some managed providers. (choix : use pgcrypto/gen_random_uuid everywhere in migration)
4. Ajouter seeds
   • database/seeds/0001_seeds.sql : contains the feature_flags and guilds sample records and roles insertion if not present (INSERT ... ON CONFLICT DO NOTHING)
   • Ensure migration doesn't reinsert duplicates.
5. Add package.json scripts (patch)
   • Update package.json at repo root to add scripts: "migrate": "node-pg-migrate", "migrate:up": "node-pg-migrate up --config database/migration-config.js", "migrate:down": "node-pg-migrate down --config database/migration-config.js", "db:bootstrap": "./scripts/bootstrap-db.sh"
   • Add dev dependency in package.json: "node-pg-migrate": "^7" (or latest stable), and "pg": appropriate version if needed. Use pnpm workspace handling if monorepo -- add to root devDependencies.
6. Add .env.example
   • Template with variable names but no secrets (DATABASE_URL, REDIS_URL, JWT_SECRET, SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_KEY, DISCORD_TOKEN, DISCORD_CLIENT_ID, GOOGLE_SA_JSON placeholder, etc.).
7. Add/modify GitHub Actions workflow .github/workflows/db-bootstrap.yml
   • Use workflow_dispatch (manual). Checkout repo, install pnpm, install node-pg-migrate or use pnpm to run, set DATABASE_URL from secrets, export PGSSLMODE=require if not set, run pnpm install --frozen-lockfile, run pnpm run migrate:up (or node-pg-migrate directly), then run psql to apply seeds if necessary.
   • Protect workflow by running in an environment that requires approval; add instructions in workflow for reviewer manual approval (set environment: production). Keep workflow manual to avoid accidental runs.
8. Add README short section: docs/DB_MIGRATIONS.md explaining how to run migrations locally, how to bootstrap, and recommended flow for deploying migrations in CI/production (manual workflow, env approvals), and note about rotating keys/secrets.

Contraintes & décisions prises (à inclure dans PR description):

• J'ai choisi d'utiliser pgcrypto + gen_random_uuid() in the migration instead of uuid-ossp to improve compatibility with managed Postgres (Supabase). If you prefer uuid-ossp, we can switch it.
• Migrations are JS files (node-pg-migrate) to allow up/down and easier transactional control.
• Seeds are idempotent (INSERT ... ON CONFLICT DO NOTHING).
• The bootstrap workflow is manual to avoid accidental schema changes; it uses GitHub Environments and requires approval for production.

Livrables (liste des fichiers ajoutés/modifiés) :

• database/migration-config.js
• database/migrations/0001_initial.js
• database/seeds/0001_seeds.sql
• database/schema_pgcrypto.sql (optional backup)
• scripts/bootstrap-db.sh
• .env.example
• package.json (modified: devDependencies + scripts)
• .github/workflows/db-bootstrap.yml (new/modified)
• docs/DB_MIGRATIONS.md

Instructions post-merge :

• Run the manual workflow from Actions -> db-bootstrap -> Run workflow with branch...

This pull request was created as a result of the following prompt from Copilot chat.

But : ajouter une gestion de migrations robuste et un bootstrap idempotent pour la base de données Supabase, plus quelques fichiers d'accompagnement et adaptation du workflow CI.

Contexte :

• Repo: CorentynDevPro/StarForge
• Objectif : remplacer l'approche actuelle (schema.sql appliqué manuellement) par une solution professionnelle et reproductible utilisant node-pg-migrate (migrations up/down), script de bootstrap pour dev/CI, .env.example, et un workflow GitHub Actions manuel protégé exécutant les migrations sur la DATABASE_URL stockée en secret.

Tâches à réaliser dans la PR :

1. Ajouter node-pg-migrate et configuration
   • Créer fichier database/migration-config.js qui lit DATABASE_URL & PGSSLMODE depuis l'environnement et exporte la config attendue par node-pg-migrate.
   • Ajouter migration initiale database/migrations/0001_initial.js (JS migration) qui crée les tables, indexes, triggers et insère les roles + feature flags/guild seeds. La migration doit être idempotente (utiliser ifNotExists / createTable options) et utiliser transactions.
2. Ajouter script de bootstrap
   • scripts/bootstrap-db.sh : script shell exécutable qui vérifie psql/node-pg-migrate installés, exporte PGSSLMODE=require si non défini, exécute pnpm install --frozen-lockfile (optionnel), puis node-pg-migrate up --config database/migration-config.js, puis applique seeds SQL si présents. Le script doit proposer fallback : si la migration échoue à cause de l'extension uuid-ossp, rerun migration after enabling pgcrypto variant; implémenter logique simple : detecter l'erreur contenant 'permission denied to create extension' ou similaire.
3. Ajouter schema_pgcrypto.sql ou migration alternative si nécessaire
   • Inclure database/schema_pgcrypto.sql (comme fournie précédemment) ou ensure migration uses pgcrypto by default by creating extension IF NOT EXISTS pgcrypto first; pour robustesse, la migration initiale doit CREATE EXTENSION IF NOT EXISTS pgcrypto; et utiliser gen_random_uuid() rather than uuid_generate_v4() to avoid uuid-ossp permission issues on some managed providers. (choix : use pgcrypto/gen_random_uuid everywhere in migration)
4. Ajouter seeds
   • database/seeds/0001_seeds.sql : contains the feature_flags and guilds sample records and roles insertion if not present (INSERT ... ON CONFLICT DO NOTHING)
   • Ensure migration doesn't reinsert duplicates.
5. Add package.json scripts (patch)
   • Update package.json at repo root to add scripts: "migrate": "node-pg-migrate", "migrate:up": "node-pg-migrate up --config database/migration-config.js", "migrate:down": "node-pg-migrate down --config database/migration-config.js", "db:bootstrap": "./scripts/bootstrap-db.sh"
   • Add dev dependency in package.json: "node-pg-migrate": "^7" (or latest stable), and "pg": appropriate version if needed. Use pnpm workspace handling if monorepo -- add to root devDependencies.
6. Add .env.example
   • Template with variable names but no secrets (DATABASE_URL, REDIS_URL, JWT_SECRET, SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_KEY, DISCORD_TOKEN, DISCORD_CLIENT_ID, GOOGLE_SA_JSON placeholder, etc.).
7. Add/modify GitHub Actions workflow .github/workflows/db-bootstrap.yml
   • Use workflow_dispatch (manual). Checkout repo, install pnpm, install node-pg-migrate or use pnpm to run, set DATABASE_URL from secrets, export PGSSLMODE=require if not set, run pnpm install --frozen-lockfile, run pnpm run migrate:up (or node-pg-migrate directly), then run psql to apply seeds if necessary.
   • Protect workflow by running in an environment that requires approval; add instructions in workflow for reviewer manual approval (set environment: production). Keep workflow manual to avoid accidental runs.
8. Add README short section: docs/DB_MIGRATIONS.md explaining how to run migrations locally, how to bootstrap, and recommended flow for deploying migrations in CI/production (manual workflow, env approvals), and note about rotating keys/secrets.

Contraintes & décisions prises (à inclure dans PR description):

• J'ai choisi d'utiliser pgcrypto + gen_random_uuid() in the migration instead of uuid-ossp to improve compatibility with managed Postgres (Supabase). If you prefer uuid-ossp, we can switch it.
• Migrations are JS files (node-pg-migrate) to allow up/down and easier transactional control.
• Seeds are idempotent (INSERT ... ON CONFLICT DO NOTHING).
• The bootstrap workflow is manual to avoid accidental schema changes; it uses GitHub Environments and requires approval for production.

Livrables (liste des fichiers ajoutés/modifiés) :

• database/migration-config.js
• database/migrations/0001_initial.js
• database/seeds/0001_seeds.sql
• database/schema_pgcrypto.sql (optional backup)
• scripts/bootstrap-db.sh
• .env.example
• package.json (modified: devDependencies + scripts)
• .github/workflows/db-bootstrap.yml (new/modified)
• docs/DB_MIGRATIONS.md

Instructions post-merge :

• Run the manual workflow from Actions -> db-bootstrap -> Run workflow with branch main (will use secrets). Or run locally:
  export DATABASE_URL=...; export PGSSLMODE=require; ./scripts/bootstrap-db.sh

Merci de confirmer que je peux créer la Pull Request avec ces fichiers. Si tu veux des adaptations (préférence uuid-ossp, SQL migrations instead of JS, auto-run on push to main), dis-le maintenant et j'adapterai avant de créer la PR.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.