@javalabs/prisma-client

Cliente Prisma compartido para los microservicios de Tupay. Este paquete proporciona una capa de abstracción sobre Prisma ORM con soporte para multi-tenancy (usando esquemas de base de datos separados por tenant) y utilidades de migración y gestión de base de datos.

Instalación

npm i @javalabs/prisma-client

Características

• Cliente Prisma Singleton: Implementación eficiente del cliente Prisma () para el esquema public.
• Soporte Multi-tenant: Conexión a diferentes esquemas de base de datos para diferentes inquilinos a través de . Los tenants suelen identificarse por su API Key, que se usa como nombre del esquema.
• Integración con NestJS: Módulo global () para facilitar la inyección en aplicaciones NestJS.
• Utilidades de Migración: Scripts para migración de esquemas y datos entre entornos.
• Herramientas de Gestión de BD: Scripts para crear esquemas de tenants, sincronizar estructuras, resetear bases de datos y corregir tipos de datos.

Diagramas

Arquitectura Multi-tenant

graph TD
    A[Aplicación] --> B(PrismaFactoryService);
    B -- Obtener cliente para Tenant X --> C{Cliente Prisma - Tenant X};
    B -- Obtener cliente para Tenant Y --> D{Cliente Prisma - Tenant Y};
    C --> E[(Base de Datos - Schema Tenant X)];
    D --> F[(Base de Datos - Schema Tenant Y)];
    A --> G(PrismaService);
    G -- Cliente por defecto --> H{Cliente Prisma - Public};
    H --> I[(Base de Datos - Schema Public)];

Flujo de Migración de Datos

sequenceDiagram
    participant S as Base de Datos Origen (SOURCE_DATABASE_URL)
    participant M as Script de Migración (`migrate:data`)
    participant T as Base de Datos Destino (DATABASE_URL - Tenants)

    M->>S: Consulta datos de origen
    S-->>M: Retorna datos
    M->>M: Procesa y transforma datos (considerando dependencias)
    M->>T: Migra datos a esquemas de tenants en destino
    T-->>M: Confirma migración

    Note over M: Ordenamiento por dependencias (ForeignKeyManager)
    Note over M: Manejo de tipos de datos
    Note over M: Migración por fases (si aplica)

Estructura del Proyecto

graph LR
    A[@javalabs/prisma-client] --> B[src];
    A --> C[prisma];
    B --> D[scripts];
    B --> E[index.ts];
    B --> F[prisma.module.ts];
    B --> G[prisma.service.ts];
    B --> H[prisma-factory.service.ts];
    D --> I[data-migration];
    D --> J[reset-database.ts];
    D --> K[schema-sync.ts];
    D --> L[create-tenant-schemas.ts];
    D --> M[migrate-schema-structure.ts];
    D --> N[fix-data-types.ts];
    I --> O[dependency-manager.ts];
    I --> P[schema-utils.ts];
    I --> Q[migration-phases.ts];

Uso Básico

En aplicaciones NestJS

Importa el PrismaModule en tu módulo principal:

import { Module } from "@nestjs/common";
import { PrismaModule } from "@javalabs/prisma-client"; // <--- Updated import path

@Module({
  imports: [PrismaModule],
})
export class AppModule {}

Luego, inyecta los servicios donde los necesites:

import { Injectable } from "@nestjs/common";
import { PrismaService, PrismaFactoryService } from "@javalabs/prisma-client"; // <--- Updated import path

@Injectable()
export class MyService {
  constructor(
    private prismaService: PrismaService, // Cliente para el schema 'public'
    private prismaFactoryService: PrismaFactoryService // Fábrica para clientes de tenants
  ) {}

  // Usar el cliente principal (schema public)
  async findAllPublicData() {
    // Asume que tienes un modelo 'PublicData' en tu schema.prisma
    // return this.prismaService.client.publicData.findMany();
    return "Ejemplo: Accediendo a datos públicos";
  }

  // Usar un cliente específico para un tenant
  async findTenantUsers(tenantId: string) {
    // tenantId suele ser la API Key que identifica al schema
    const tenantClient = this.prismaFactoryService.getClient(tenantId);
    // Asume que tienes un modelo 'users' en tu schema.prisma
    return tenantClient.users.findMany();
  }
}

En aplicaciones no-NestJS (o scripts)

Puedes importar directamente la instancia prisma (cliente para el schema public). Para acceder a tenants, necesitarías instanciar PrismaFactoryService manualmente o usar los scripts proporcionados.

import { prisma } from "@javalabs/prisma-client"; // <--- Updated import path

async function main() {
  // Ejemplo: Acceder a datos del schema 'public'
  // const publicData = await prisma.publicData.findMany();
  // console.log(publicData);
  console.log("Ejemplo: Accediendo a datos públicos desde script");
}

main()
  .catch(console.error)
  .finally(async () => {
      await prisma.$disconnect();
  });

Scripts de Utilidad

Estos scripts se ejecutan generalmente con npm run <script_name> o node dist/scripts/<script_file>.js después de compilar (npm run build).

Migración de Datos

Migra datos desde SOURCE_DATABASE_URL a los esquemas de tenants en DATABASE_URL.

# Migrar datos (requiere confirmación)
npm run migrate:data

# Migrar datos forzando la operación (sin confirmación)
npm run migrate:data:force

# Migrar datos con confirmación automática 'yes'
npm run migrate:data:yes

Gestión de Esquemas (Prisma Migrate)

Gestiona la evolución del esquema de la base de datos usando Prisma Migrate. Estos comandos aplican los cambios definidos en prisma/migrations al schema public. Para aplicar a tenants, ver "Scripts Avanzados".

# Generar cliente Prisma basado en schema.prisma
npm run generate

# Crear una nueva migración SQL basada en cambios al schema.prisma (desarrollo)
npm run migrate:dev

# Aplicar migraciones pendientes a la base de datos (producción/despliegue)
npm run migrate:deploy

Scripts Avanzados

Scripts para tareas más complejas de administración multi-tenant. Ejecutar con node dist/scripts/<script_file>.js después de npm run build.

Creación de Esquemas para Tenants

Crea los esquemas de base de datos para cada tenant (basado en API Keys encontradas en SOURCE_DATABASE_URL).

# Compilar el proyecto si no está compilado
npm run build

# Ejecutar el script para crear esquemas de tenant
node dist/scripts/create-tenant-schemas.js

Migración de Estructura de Esquemas (Tenants)

Aplica la estructura definida en prisma/schema.prisma a todos los esquemas de tenants existentes en DATABASE_URL usando prisma db push. Útil para asegurar que todos los tenants tengan la misma estructura base.

# Compilar el proyecto si no está compilado
npm run build

# Ejecutar el script para aplicar la estructura a los schemas de tenants
node dist/scripts/migrate-schema-structure.js

Sincronización de Esquemas

Genera un script SQL para sincronizar esquemas (potencialmente entre public y tenants, o entre tenants). Revisa el script antes de aplicarlo.

# Compilar el proyecto si no está compilado
npm run build

# Generar el script SQL de sincronización
node dist/scripts/schema-sync.js

Reseteo de Base de Datos

Resetea la base de datos (¡CUIDADO: Borra datos!).

# Compilar el proyecto si no está compilado
npm run build

# Resetear la base de datos (schema public y potencialmente tenants, revisar script)
node dist/scripts/reset-database.js

# Resetear y recrear la base de datos
node dist/scripts/reset-database.js --recreate

Corrección de Tipos de Datos

Intenta corregir inconsistencias en tipos de datos (ej. numéricos almacenados como texto, valores de enums inválidos) en los esquemas de los tenants.

# Compilar el proyecto si no está compilado
npm run build

# Ejecutar el script para corregir tipos de datos
node dist/scripts/fix-data-types.js

Variables de Entorno

El paquete y sus scripts dependen de las siguientes variables de entorno (generalmente definidas en un archivo .env):

• DATABASE_URL: URL de conexión a la base de datos principal (PostgreSQL) donde residen los esquemas public y de los tenants.
  • Ejemplo: postgresql://user:password@host:port/database
• SOURCE_DATABASE_URL: URL de conexión a la base de datos de origen, utilizada principalmente por los scripts de migración de datos y creación de esquemas.
  • Ejemplo: postgresql://user:password@source_host:port/source_database

Desarrollo

# Instalar dependencias
npm install

# Compilar el proyecto (genera archivos en dist/)
npm run build

# Generar cliente Prisma (después de cambios en schema.prisma)
npm run generate

Licencia

ISC