# Migración PostgreSQL → MySQL/MariaDB

## Requisitos

| Componente | Versión mínima |
|-----------|---------------|
| Node.js | 18.x |
| MySQL | 5.7+ |
| MariaDB | 10.6+ |
| npm | 9+ |

---

## 1. Crear la base de datos en MySQL/MariaDB

Conéctate a tu servidor MySQL como root y ejecuta:

```sql
CREATE DATABASE empadronamiento_vfb
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE USER 'vfb_user'@'localhost' IDENTIFIED BY 'tu_password_seguro';
GRANT ALL PRIVILEGES ON empadronamiento_vfb.* TO 'vfb_user'@'localhost';
FLUSH PRIVILEGES;
```

> En cPanel puedes usar el asistente **"Bases de datos MySQL"** del panel para crear la base de datos y el usuario sin necesidad de CLI.

---

## 2. Configurar variables de entorno

Copia `.env.example` como `.env` y rellena los valores:

```bash
cp .env.example .env
```

Edita `.env`:

```env
DATABASE_URL="mysql://vfb_user:tu_password_seguro@localhost:3306/empadronamiento_vfb"
NEXTAUTH_URL="https://tudominio.com"
NEXTAUTH_SECRET="genera-con-openssl-rand-base64-32"
UPLOAD_DIR="/home/usuario/empadronamiento-uploads"
NODE_ENV="production"
SEED_ADMIN_EMAIL="admin@tudominio.com"
SEED_ADMIN_PASSWORD="CambiaMeEnProduccion1!"
```

---

## 3. Instalar dependencias

```bash
npm install
```

Esto también ejecuta `prisma generate` automáticamente (via `postinstall`).

---

## 4. Ejecutar migraciones

```bash
npm run prisma:migrate:deploy
```

Este comando aplica la migración `20260531000000_init_mysql` que crea todas las tablas con:
- `CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci` (soporte completo Unicode/emoji)
- Tipos `ENUM` para todos los campos enumerados
- Tipos `TEXT` para campos de texto largo
- Tipo `JSON` para `metadata` (AuditLog) y `etiquetas` (BitacoraHito)
- Todas las claves foráneas con `ON DELETE CASCADE` / `ON DELETE SET NULL` según corresponde

---

## 5. Ejecutar el seed (primer despliegue)

```bash
npm run prisma:seed
```

Esto crea:
- Los 4 roles del sistema: `ADMIN`, `DIGITADOR`, `VALIDADOR`, `CONSULTA`
- El usuario administrador inicial (usando `SEED_ADMIN_EMAIL` y `SEED_ADMIN_PASSWORD` del `.env`)

---

## 6. Verificar la instalación

```bash
# Verifica que el cliente Prisma esté generado
npm run prisma:generate

# Construye la aplicación (detecta errores de TypeScript/compilación)
npm run build
```

---

## Diferencias técnicas respecto a la versión PostgreSQL

### 1. `etiquetas` — de `String[]` a `Json`

**PostgreSQL:** `etiquetas TEXT[] DEFAULT ARRAY[]::TEXT[]`  
**MySQL:** `etiquetas JSON NOT NULL DEFAULT '[]'`

Las etiquetas se almacenan como array JSON en lugar de array nativo de PostgreSQL.

**Lectura en código:**

```typescript
// El campo etiquetas ahora es de tipo `JsonValue` en TypeScript
// Para usarlo como string[], castear:
const etiquetas = hito.etiquetas as string[];
```

**Búsqueda por etiquetas (MySQL/MariaDB):** Usa `JSON_CONTAINS`:

```sql
SELECT id FROM BitacoraHito
WHERE JSON_CONTAINS(etiquetas, JSON_QUOTE('nombre-etiqueta'), '$');
```

Esto ya está implementado en `src/server/queries/bitacora.ts`.

### 2. Búsqueda case-insensitive

**PostgreSQL:** `{ contains: q, mode: "insensitive" }` → genera `ILIKE`  
**MySQL:** `{ contains: q }` → genera `LIKE` — MySQL con `utf8mb4_unicode_ci` es case-insensitive por defecto.

No se requiere cambio de comportamiento para el usuario final.

### 3. Funciones de base de datos (`configuracion.ts`)

| PostgreSQL | MySQL/MariaDB |
|-----------|--------------|
| `current_database()` | `DATABASE()` |
| `version()` | `VERSION()` |

### 4. Driver Prisma

**PostgreSQL:** `@prisma/adapter-pg` + `PrismaPg` (driver adapter Prisma 7)  
**MySQL:** `PrismaClient` estándar sin adapter (Prisma usa su motor integrado con `mysql2`)

### 5. Tipos de columna

| Campo | PostgreSQL | MySQL |
|-------|-----------|-------|
| Texto largo | `TEXT` (auto) | `TEXT` (via `@db.Text`) |
| JSON | `JSONB` | `JSON` |
| Arrays | `TEXT[]` | `JSON` |
| Fechas | `TIMESTAMP` | `DATETIME(3)` |

---

## Compatibilidad MariaDB 10.6+

Todos los tipos utilizados son compatibles con MariaDB 10.6+:
- `JSON`: soportado desde MariaDB 10.2 (alias de `LONGTEXT` con validación)
- `JSON_CONTAINS()`: soportado desde MariaDB 10.2
- `ENUM`: soportado nativamente
- `utf8mb4`: soportado desde MariaDB 10.0
- Foreign keys con `ON DELETE CASCADE`: InnoDB (engine por defecto)

> **Nota MariaDB:** `JSON_CONTAINS` en MariaDB 10.2-10.5 puede tener diferencias
> menores de comportamiento respecto a MySQL 8. En MariaDB 10.6+ el comportamiento
> es equivalente. Si usas MariaDB < 10.6, verifica la búsqueda por etiquetas.

---

## Backup de migraciones PostgreSQL

Las migraciones originales de PostgreSQL están preservadas en:

```
prisma/migrations-pg-backup/
```

No eliminar este directorio si necesitas referencia histórica.

---

## Scripts disponibles

```bash
npm run prisma:generate        # Regenerar cliente Prisma
npm run prisma:migrate         # Nueva migración (desarrollo)
npm run prisma:migrate:deploy  # Aplicar migraciones (producción)
npm run prisma:seed            # Poblar datos iniciales
npm run build                  # Compilar aplicación
npm run dev                    # Servidor de desarrollo
npm start                      # Servidor de producción
```