MariaDB Pool Cuenti

Un gestor inteligente de pools de conexiones para MariaDB/MySQL que maneja múltiples bases de datos de empresas (multi-tenant) de forma dinámica y eficiente.

🌟 Características

• Multi-tenant: Maneja conexiones a múltiples bases de datos de empresas
• Pool dinámico: Crea y gestiona pools de conexiones bajo demanda
• Inicialización perezosa: Solo inicializa conexiones cuando se necesitan
• Configuración centralizada: Almacena configuración de servidores en base de datos
• Soporte para proxy: Maneja tanto conexiones directas como pools
• Query helpers: Métodos auxiliares para consultas SQL con parámetros nombrados
• TypeScript: Completamente tipado para mejor experiencia de desarrollo

📦 Instalación

1npm install mariadb-pool-cuenti

🔧 Configuración

Variables de entorno

Crea un archivo .env en tu proyecto con las siguientes variables:

1# Configuración de la base de datos principal
2DB_HOST=localhost
3DB_USER=root
4DB_PASSWORD=tu_password_aqui
5DB_NAME=nombre_base_datos
6DB_PORT=3306
7DB_POOL_SIZE=5
8
9# Configuración de pools de tenant (opcional)
10TENANT_POOL_SIZE=10

Estructura de base de datos requerida

El paquete necesita estas tablas en tu base de datos principal:

1-- Tabla de servidores
2CREATE TABLE Servidores (
3    id INT PRIMARY KEY AUTO_INCREMENT,
4    ip VARCHAR(255) NOT NULL,
5    puerto INT NOT NULL DEFAULT 3306,
6    usuario VARCHAR(255) NOT NULL,
7    clave VARCHAR(255) NOT NULL,
8    es_proxy TINYINT(1) DEFAULT 0,
9    initialSize INT DEFAULT 5,
10    maxActive INT DEFAULT 10,
11    maxIdle INT DEFAULT 5,
12    maxTiempoInatividad INT DEFAULT 300,
13    maxTiempoEsperaEntregarConecion INT DEFAULT 60
14);
15
16-- Tabla de aplicaciones por empresa
17CREATE TABLE aplicaciones_empresa (
18    id INT PRIMARY KEY AUTO_INCREMENT,
19    id_empresa INT NOT NULL,
20    id_servidor INT NOT NULL,
21    nombreBaseDatos VARCHAR(255) NOT NULL,
22    FOREIGN KEY (id_servidor) REFERENCES Servidores(id)
23);

🚀 Uso básico

Importación

1import dbManager from "mariadb-pool-cuenti";
2// o
3import { DBManager } from "mariadb-pool-cuenti";

Obtener conexión de empresa

1// Obtener conexión para una empresa específica
2const conn = await dbManager.getConnectionEmpresa(123);
3
4try {
5  // Realizar consultas
6  const usuarios = await conn.query("SELECT * FROM usuarios");
7  console.log(usuarios);
8} finally {
9  // Siempre liberar la conexión
10  conn.release();
11}

Usando el pool principal

1// Para consultas en la base de datos principal
2const conn = await dbManager.getPoolBases();
3
4try {
5  const empresas = await conn.query("SELECT * FROM aplicaciones_empresa");
6  console.log(empresas);
7} finally {
8  conn.release();
9}

📚 API Detallada

DBManager.getInstance()

Obtiene la instancia singleton del gestor.

1const dbManager = DBManager.getInstance();

getConnectionEmpresa(idEmpresa: number): Promise<ExtendedConnection>

Obtiene una conexión a la base de datos de una empresa específica.

Parámetros:

• idEmpresa: ID numérico de la empresa

Retorna: Promise<ExtendedConnection> - Conexión extendida con métodos auxiliares

Ejemplo:

1const conn = await dbManager.getConnectionEmpresa(123);
2// La conexión ya está configurada para usar la BD de la empresa 123

getPoolBases(): Promise<ExtendedConnection>

Obtiene una conexión al pool principal (base de datos de configuración).

Retorna: Promise<ExtendedConnection> - Conexión al pool principal

borrarEmpresaServer(idEmpresa: number): void

Elimina una empresa del cache interno, forzando reconfiguración en próximo acceso.

Parámetros:

• idEmpresa: ID de la empresa a eliminar del cache

isReady(): boolean

Verifica si el servicio está inicializado y listo para usar.

Retorna: boolean - true si está listo

closeAll(): Promise<void>

Cierra todas las conexiones y pools de manera ordenada.

🔍 ExtendedConnection

Las conexiones retornadas incluyen métodos auxiliares adicionales:

queryFormat(query: string, params?: QueryParams): string

Formatea una consulta SQL reemplazando parámetros nombrados.

1const sql = conn.queryFormat(
2  "SELECT * FROM usuarios WHERE id = :id AND activo = :activo",
3  { id: 123, activo: 1 }
4);
5// Resultado: "SELECT * FROM usuarios WHERE id = 123 AND activo = 1"

query2<T>(query: string, params?: QueryParams): Promise<T>

Ejecuta una consulta SQL con parámetros nombrados.

1const usuarios = await conn.query2<Usuario[]>(
2  "SELECT * FROM usuarios WHERE edad > :edad AND ciudad = :ciudad",
3  { edad: 18, ciudad: "Madrid" }
4);

💡 Ejemplos avanzados

Manejo completo de conexiones

1import dbManager from "mariadb-pool-cuenti";
2
3async function obtenerDatosEmpresa(idEmpresa: number) {
4  let conn;
5
6  try {
7    // Verificar que el servicio esté listo
8    if (!dbManager.isReady()) {
9      console.log("Servicio inicializándose...");
10    }
11
12    // Obtener conexión
13    conn = await dbManager.getConnectionEmpresa(idEmpresa);
14
15    // Consulta con parámetros nombrados
16    const usuarios = await conn.query2<any[]>(
17      "SELECT * FROM usuarios WHERE activo = :activo",
18      { activo: 1 }
19    );
20
21    return usuarios;
22  } catch (error) {
23    console.error("Error al obtener datos:", error);
24    throw error;
25  } finally {
26    // Siempre liberar la conexión
27    if (conn) {
28      conn.release();
29    }
30  }
31}

Usando con Express.js

1import express from "express";
2import dbManager from "mariadb-pool-cuenti";
3
4const app = express();
5
6app.get("/empresas/:id/usuarios", async (req, res) => {
7  const idEmpresa = parseInt(req.params.id);
8
9  try {
10    const conn = await dbManager.getConnectionEmpresa(idEmpresa);
11
12    const usuarios = await conn.query2(
13      "SELECT id, nombre, email FROM usuarios WHERE activo = :activo",
14      { activo: 1 }
15    );
16
17    res.json(usuarios);
18    conn.release();
19  } catch (error) {
20    console.error("Error:", error);
21    res.status(500).json({ error: "Error interno del servidor" });
22  }
23});
24
25// Graceful shutdown
26process.on("SIGTERM", async () => {
27  console.log("Cerrando conexiones...");
28  await dbManager.closeAll();
29  process.exit(0);
30});

Transacciones

1async function transferirFondos(
2  idEmpresa: number,
3  fromUser: number,
4  toUser: number,
5  amount: number
6) {
7  const conn = await dbManager.getConnectionEmpresa(idEmpresa);
8
9  try {
10    await conn.beginTransaction();
11
12    // Debitar cuenta origen
13    await conn.query2(
14      "UPDATE cuentas SET saldo = saldo - :amount WHERE usuario_id = :userId",
15      { amount, userId: fromUser }
16    );
17
18    // Acreditar cuenta destino
19    await conn.query2(
20      "UPDATE cuentas SET saldo = saldo + :amount WHERE usuario_id = :userId",
21      { amount, userId: toUser }
22    );
23
24    await conn.commit();
25    console.log("Transferencia completada");
26  } catch (error) {
27    await conn.rollback();
28    console.error("Error en transferencia:", error);
29    throw error;
30  } finally {
31    conn.release();
32  }
33}

🏗️ Arquitectura

Flujo de funcionamiento

1. Inicialización perezosa: El servicio no se conecta hasta que se solicite una conexión
2. Consulta de configuración: Al solicitar una empresa, consulta su configuración en la BD principal
3. Creación de pool: Si es la primera vez, crea un pool para ese servidor
4. Cache interno: Mantiene cache de configuraciones para evitar consultas repetidas
5. Conexión optimizada: Reutiliza pools existentes para empresas del mismo servidor

Tipos de conexión

• Pool (es_proxy = 0): Crea un pool de conexiones reutilizables
• Directa (es_proxy = 1): Crea conexiones directas sin pool

🔒 Mejores prácticas

1. Siempre liberar conexiones

1// ✅ Correcto
2const conn = await dbManager.getConnectionEmpresa(123);
3try {
4  // usar conexión
5} finally {
6  conn.release(); // Siempre liberar
7}
8
9// ❌ Incorrecto - puede causar memory leaks
10const conn = await dbManager.getConnectionEmpresa(123);
11const data = await conn.query("SELECT * FROM tabla");
12// Conexión no liberada

2. Manejo de errores

1try {
2  const conn = await dbManager.getConnectionEmpresa(123);
3  // operaciones
4  conn.release();
5} catch (error) {
6  if (error.message.includes("no configurada")) {
7    console.log("Empresa no existe en configuración");
8  }
9  throw error;
10}

3. Graceful shutdown

1// En tu aplicación principal
2process.on("SIGTERM", async () => {
3  await dbManager.closeAll();
4  process.exit(0);
5});

4. Validación de empresas

1// Verificar si una empresa existe antes de usarla
2async function validarEmpresa(idEmpresa: number): Promise<boolean> {
3  try {
4    const conn = await dbManager.getConnectionEmpresa(idEmpresa);
5    conn.release();
6    return true;
7  } catch (error) {
8    if (error.message.includes("no configurada")) {
9      return false;
10    }
11    throw error;
12  }
13}

🐛 Debugging

Logs del sistema

El paquete emite logs detallados para debugging:

[BASE] Inicializando pool de conexiones principal...
[BASE] Pool principal inicializado correctamente
[TENANT] Obteniendo conexión para empresa 123
[TENANT] Consultando configuración para empresa 123
[TENANT] Creando nuevo servidor 1 para empresa 123
[TENANT] Conexión establecida para empresa 123 en BD: empresa_123

Variables de entorno para debugging

1# Para más logs de MariaDB
2DEBUG=mariadb:*

📄 Licencia

MIT

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature
3. Commit tus cambios
4. Push a tu rama
5. Abre un Pull Request

📞 Soporte

Para reportar bugs o solicitar features, por favor abre un issue en el repositorio.

---

Nota: Este paquete está diseñado para aplicaciones multi-tenant que requieren gestión dinámica de conexiones a bases de datos por empresa.