embeejayz-migrations

Migraciones de base de datos para la Plataforma Embeejayz. SQL puro, sin ORM, versionado por archivo con registro de lo aplicado.

---

Prerequisitos

golang-migrate

go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
migrate -version

Postgres local

docker run -d \
  --name recompensas \
  -e POSTGRES_USER=user \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=recompensas \
  -p 5432:5432 \
  postgres:18

---

Configuración

cp .env.example .env
# editar .env con la URL de tu DB local

.env.example:

MAIN_DB_URL=postgresql://user:password@localhost:5432/recompensas

---

Uso

./scripts/migrate.sh up auth        # aplica migraciones pendientes
./scripts/migrate.sh down auth     # revierte la última
./scripts/migrate.sh up another  # otro módulo

---

Estructura

sql/
  core/        ← DB principal: border, account, ticket, lck2026
  auth/        ← módulo auth

Cada módulo tiene migraciones independientes. Al activar un módulo para un tenant se corren las migraciones de esa carpeta contra su DB/schema.

---

Convención de archivos

{version}_{descripcion}.up.sql    ← aplica el cambio
{version}_{descripcion}.down.sql  ← lo revierte

• Versión siempre con 5 dígitos: 00001, 00002
• Nunca modificar un archivo ya commiteado, siempre crear uno nuevo
• Si te equivocaste en 00003, creás 00004_fix_... con el correctivo

---

Patrón expand & contract

Nunca un cambio breaking en un solo paso. Siempre en fases, cada una su propio commit:

Fase 1 — expand (no rompe lo que ya corre):

-- 00002_expand_users_add_phone.up.sql
ALTER TABLE users ADD COLUMN phone VARCHAR(20);

-- 00002_expand_users_add_phone.down.sql
ALTER TABLE users DROP COLUMN phone;

Fase 2 — contract (cuando la app ya escribe en la columna):

-- 00003_contract_users_phone_not_null.up.sql
UPDATE users SET phone = '' WHERE phone IS NULL;
ALTER TABLE users ALTER COLUMN phone SET NOT NULL;

-- 00003_contract_users_phone_not_null.down.sql
ALTER TABLE users ALTER COLUMN phone DROP NOT NULL;

---

Flujo

1. Crear el .sql en sql/{modulo}/
2. ./scripts/migrate.sh up {modulo}     ← probar local
3. Algo sale mal → down, corregir, repetir
4. Todo bien → commit + push

---

CI/CD (GitHub Actions)

El repositorio cuenta con un workflow de ejecución manual (workflow_dispatch) en .github/workflows/migrations.yml.

Configuración en GitHub:

Solo necesitas crear un Repository Secret:

1. Ve a tu repositorio en GitHub \rightarrow Settings \rightarrow Secrets and variables \rightarrow Actions.
2. Crea el secreto MAIN_DB_URL con tu cadena de conexión a la base de datos de producción: postgresql://user:password@host:5432/recompensas?sslmode=require

Cómo ejecutar manualmente:

1. Ir a la pestaña Actions en GitHub.
2. Seleccionar el workflow Database Migrations.
3. Hacer clic en Run workflow.
4. Seleccionar los parámetros:
   • Acción: up (aplicar) o down (revertir).
   • Módulo: all, core, auth, album.
   • Pasos (opcional): Cantidad de versiones a revertir (solo para down, por defecto 1).