# Template SaaS - Database

**Version:** 1.0.0
**Database:** PostgreSQL 16+
**Multi-tenancy:** Row-Level Security (RLS)

---

## Schemas

| Schema | Descripcion | RLS |
|--------|-------------|-----|
| auth | Sesiones, tokens, OAuth | Si |
| tenants | Tenants y configuracion | No* |
| users | Usuarios, roles, permisos | Si |
| billing | Subscripciones, facturas, pagos | Si |
| plans | Planes y features | No |
| audit | Logs de auditoria y actividad | Si |
| notifications | Templates y notificaciones | Si |
| feature_flags | Feature flags y evaluaciones | Si |
| storage | Archivos y metadata | Si |

*tenants.tenants no usa RLS ya que es la tabla base de multi-tenancy.

---

## Estructura de Archivos

```
database/
├── ddl/
│   ├── 00-extensions.sql     # Extensiones PostgreSQL
│   ├── 01-schemas.sql        # Creacion de schemas
│   ├── 02-enums.sql          # Tipos enum
│   ├── 03-functions.sql      # Funciones de utilidad
│   └── schemas/
│       ├── auth/tables/      # Sesiones, tokens, OAuth
│       ├── tenants/tables/   # Tenants, settings
│       ├── users/tables/     # Users, roles, invitations
│       ├── billing/tables/   # Subscriptions, invoices
│       ├── plans/tables/     # Plans, features
│       ├── audit/tables/     # Audit logs, activity
│       ├── notifications/tables/
│       └── feature_flags/tables/
├── seeds/
│   ├── prod/                 # Seeds para produccion
│   └── dev/                  # Seeds para desarrollo
└── scripts/
    ├── create-database.sh
    └── drop-and-recreate.sh
```

---

## Uso de RLS

### Establecer Contexto de Tenant

```sql
-- En cada request
SELECT auth.set_current_tenant('tenant-uuid-here');

-- Opcional: establecer usuario
SELECT auth.set_current_user('user-uuid-here');
```

### Desde el Backend

```typescript
// Middleware de tenant
async function setTenantContext(tenantId: string) {
  await dataSource.query('SELECT auth.set_current_tenant($1)', [tenantId]);
}

// En el request handler
const tenantId = req.user.tenantId;
await setTenantContext(tenantId);
// Ahora todas las queries respetan RLS
```

---

## Funciones de Utilidad

### Contexto
- `auth.set_current_tenant(uuid)` - Establece tenant para RLS
- `auth.get_current_tenant()` - Obtiene tenant actual
- `auth.set_current_user(uuid)` - Establece usuario actual
- `auth.clear_context()` - Limpia contexto

### Limites de Plan
- `plans.get_tenant_limits(tenant_id)` - Obtiene limites del plan
- `plans.check_limit(tenant_id, key, count)` - Verifica limite
- `plans.has_feature(tenant_id, feature_code)` - Verifica feature

### Usuarios
- `users.count_active_users(tenant_id)` - Cuenta usuarios activos
- `users.can_add_user(tenant_id)` - Puede agregar usuario

### Feature Flags
- `feature_flags.evaluate_flag(code, tenant_id, user_id)` - Evalua flag

### Utilidades
- `public.slugify(text)` - Genera slug
- `public.generate_token(length)` - Genera token aleatorio
- `public.hash_token(token)` - Hash SHA256

---

## Scripts

### Crear Base de Datos

```bash
cd apps/database/scripts
./create-database.sh
```

### Recrear Base de Datos

```bash
./drop-and-recreate.sh
```

### Variables de Entorno

```bash
DB_HOST=localhost
DB_PORT=5432
DB_NAME=template_saas_dev
DB_USER=template_saas_user
DB_PASSWORD=your_password
DB_ADMIN_USER=postgres
DB_ADMIN_PASSWORD=admin_password
```

---

## Orden de Ejecucion DDL

1. `00-extensions.sql`
2. `01-schemas.sql`
3. `02-enums.sql`
4. `schemas/tenants/tables/*.sql`
5. `schemas/plans/tables/*.sql`
6. `schemas/users/tables/*.sql`
7. `schemas/auth/tables/*.sql`
8. `schemas/billing/tables/*.sql`
9. `schemas/audit/tables/*.sql`
10. `schemas/notifications/tables/*.sql`
11. `schemas/feature_flags/tables/*.sql`
12. `03-functions.sql`

---

## Seeds Iniciales

### Produccion
- Planes default (Free, Starter, Pro, Enterprise)
- Roles de sistema (owner, admin, member)
- Permisos base
- Templates de notificacion

### Desarrollo
- Tenant de prueba
- Usuarios de prueba
- Datos de ejemplo

---

**Actualizado:** 2026-01-07