@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

bash

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



$3

mermaid

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)];

$3

mermaid

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)

$3

mermaid

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



$3



Importa el

PrismaModule

 en tu módulo principal:

typescript:/Users/alejandroperez/tupay/packages/prisma-client/README.md

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:

typescript:/Users/alejandroperez/tupay/packages/prisma-client/README.md

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();

  }

}





$3



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.

typescript:/Users/alejandroperez/tupay/packages/prisma-client/README.md

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 o node dist/scripts/.js después de compilar (npm run build

).



$3



Migra datos desde

SOURCE_DATABASE_URL a los esquemas de tenants en DATABASE_URL

bash

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





$3



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".

bash

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/.js después de npm run build

.



$3



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

SOURCE_DATABASE_URL

).

bash

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





$3



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.

bash

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





$3



Genera un script SQL para sincronizar esquemas (potencialmente entre

public

 y tenants, o entre tenants). Revisa el script antes de aplicarlo.

bash

Compilar el proyecto si no está compilado

npm run build



Generar el script SQL de sincronización

node dist/scripts/schema-sync.js





$3



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

bash

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





$3



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

bash

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

bash

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

@javalabs/prisma-client

Instalación

bash

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



$3

mermaid

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)];

$3

mermaid

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)

$3

mermaid

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



$3



Importa el

PrismaModule

 en tu módulo principal:

typescript:/Users/alejandroperez/tupay/packages/prisma-client/README.md

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:

typescript:/Users/alejandroperez/tupay/packages/prisma-client/README.md

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();

  }

}





$3



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.

typescript:/Users/alejandroperez/tupay/packages/prisma-client/README.md

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 o node dist/scripts/.js después de compilar (npm run build

).



$3



Migra datos desde

SOURCE_DATABASE_URL a los esquemas de tenants en DATABASE_URL

bash

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





$3



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".

bash

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/.js después de npm run build

.



$3



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

SOURCE_DATABASE_URL

).

bash

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





$3



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.

bash

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





$3



Genera un script SQL para sincronizar esquemas (potencialmente entre

public

 y tenants, o entre tenants). Revisa el script antes de aplicarlo.

bash

Compilar el proyecto si no está compilado

npm run build



Generar el script SQL de sincronización

node dist/scripts/schema-sync.js





$3



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

bash

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





$3



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

bash

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

bash

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