MariaDB Pool Cuenti 🗄️

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

• Pool de conexiones dinámico para múltiples bases de datos
• Multi-tenant con configuración automática por empresa
• Reconexión automática con backoff exponencial
• Verificación de salud automática de conexiones
• Manejo robusto de errores con timeouts configurables
• Cleanup automático de recursos
• 🔥 NUEVO: Cierre sincronizado - La librería se cierra automáticamente cuando el proceso principal termina
• Memory leak prevention con detección automática
• Soporte para conexiones directas (proxy) y pools
• Logging detallado para debugging
• TypeScript con tipado completo

📦 Instalación

1npm install mariadb-pool-cuenti@1.4.0

🛠️ Configuración

Variables de Entorno

1# Configuración del ambiente (dev o pro)
2ENVIRONMENT_DATA_BASE=dev
3
4# Configuración de la base de datos principal - DESARROLLO
5DB_HOST_DEV=localhost
6DB_USER_DEV=root
7DB_PWD_DEV=tu_password_aqui
8DATABASE_DEV=nombre_base_datos_dev
9DB_PORT_DEV=3306
10POOL_SIZE_BASE_DEV=5
11
12# Configuración de la base de datos principal - PRODUCCIÓN
13DB_HOST_PRO=host_produccion
14DB_USER_PRO=usuario_produccion
15DB_PWD_PRO=password_produccion
16DATABASE_PRO=nombre_base_datos_pro
17DB_PORT_PRO=3306
18POOL_SIZE_BASE_PRO=15
19
20# Configuración de la aplicación
21ID_APPLICATION=1
22
23# Configuración de pools de tenant (opcional)
24TENANT_POOL_SIZE=10

🔧 Uso Básico

1. Importar y usar

1import dbManager from "mariadb-pool-cuenti";
2
3// Obtener conexión para una empresa específica
4const conn = await dbManager.getConnectionEmpresa(12345);
5
6// Ejecutar consulta
7const resultado = await conn.query("SELECT * FROM tabla WHERE id = ?", [1]);
8
9// Liberar conexión (importante!)
10await conn.safeRelease();

2. Método simplificado (recomendado)

1import dbManager from "mariadb-pool-cuenti";
2
3// Ejecutar consulta con manejo automático de conexiones
4const resultado = await dbManager.executeQuery(
5  12345, // ID de empresa
6  "SELECT * FROM usuarios WHERE activo = :activo",
7  { activo: 1 }
8);
9
10console.log(resultado);

3. Manejo de cierre sincronizado 🔥

1import dbManager, { shutdown, isShuttingDown } from "mariadb-pool-cuenti";
2
3// La librería se cierra automáticamente cuando el proceso principal termina
4// Pero también puedes controlar el cierre manualmente:
5
6// Cerrar manualmente la librería
7await shutdown();
8
9// Verificar si está cerrando
10if (isShuttingDown()) {
11  console.log("La librería se está cerrando...");
12}
13
14// Ejemplo de uso en tu aplicación principal
15process.on("SIGINT", async () => {
16  console.log("Cerrando aplicación...");
17
18  // Tu código de cierre aquí
19  await miServidor.close();
20
21  // La librería se cerrará automáticamente
22  // O puedes forzar el cierre si necesitas control explícito:
23  // await shutdown();
24
25  process.exit(0);
26});

4. Manejo completo con Express

1import express from "express";
2import dbManager, { shutdown } from "mariadb-pool-cuenti";
3
4const app = express();
5
6app.get("/usuarios/:empresaId", async (req, res) => {
7  try {
8    const empresaId = parseInt(req.params.empresaId);
9
10    const usuarios = await dbManager.executeQuery(
11      empresaId,
12      "SELECT id, nombre, email FROM usuarios WHERE activo = :activo",
13      { activo: 1 }
14    );
15
16    res.json(usuarios);
17  } catch (error) {
18    console.error("Error:", error);
19    res.status(500).json({ error: "Error interno del servidor" });
20  }
21});
22
23const server = app.listen(3000, () => {
24  console.log("Servidor iniciado en puerto 3000");
25});
26
27// Manejo de cierre sincronizado
28process.on("SIGINT", async () => {
29  console.log("Cerrando servidor...");
30
31  server.close(() => {
32    console.log("Servidor cerrado");
33    // La librería se cerrará automáticamente
34    process.exit(0);
35  });
36});
37
38process.on("SIGTERM", async () => {
39  console.log("Cerrando aplicación por SIGTERM...");
40
41  server.close(() => {
42    console.log("Aplicación cerrada");
43    // La librería se cerrará automáticamente
44    process.exit(0);
45  });
46});

🔍 Monitoreo

Verificar estado del servicio

1// Verificar si está listo
2if (dbManager.isReady()) {
3  console.log("Servicio listo para usar");
4}
5
6// Obtener estadísticas de pools
7const stats = dbManager.getPoolStats();
8console.log("Estadísticas:", stats);

🚨 Manejo de Errores

La librería maneja automáticamente:

• Sin timeouts artificiales - Permite consultas extremadamente largas
• Motor MariaDB nativo - Maneja sus propios timeouts optimizados
• Reconexiones automáticas con backoff exponencial
• Errores de configuración con mensajes descriptivos
• Cleanup automático al terminar el proceso

Ejemplo de manejo de errores:

1try {
2  const resultado = await dbManager.executeQuery(
3    empresaId,
4    "SELECT * FROM tabla_grande WHERE condicion = :valor",
5    { valor: "algún_valor" }
6  );
7} catch (error) {
8  if (error.message.includes("timeout")) {
9    console.error("La consulta tardó demasiado - considera optimizar");
10  } else if (error.message.includes("Variables de entorno")) {
11    console.error("Problema de configuración:", error.message);
12  } else {
13    console.error("Error inesperado:", error);
14  }
15}

📊 Configuración Avanzada

Para Bases de Datos Muy Grandes

1# La librería v1.3.0+ NO usa timeouts artificiales
2# Esto permite consultas que tomen horas si es necesario
3
4# Pools más grandes para alta concurrencia
5POOL_SIZE_BASE_PRO=20
6TENANT_POOL_SIZE=25
7
8# Configuración recomendada en tu servidor MariaDB
9# wait_timeout = 28800          # 8 horas
10# interactive_timeout = 28800   # 8 horas
11# max_execution_time = 0        # Sin límite (solo para consultas SELECT)

Para Desarrollo

1# Configuración más pequeña para desarrollo
2POOL_SIZE_BASE_DEV=3
3TENANT_POOL_SIZE=5

🆕 Novedades en v1.1.3

✅ Cierre Sincronizado Automático

• Problema resuelto: La librería ahora se cierra automáticamente cuando tu aplicación termina
• Señales soportadas: SIGINT, SIGTERM, SIGQUIT, disconnect
• Timeout de cierre: 10 segundos máximo para garantizar terminación
• Manejo robusto: Captura errores no controlados y promesas rechazadas
• Control manual: Funciones shutdown() e isShuttingDown() para control granular

✅ Sin Timeouts Artificiales (v1.3.0+)

• Conexión: Sin límite artificial - usa configuración de MariaDB
• Consulta: Sin límite artificial - permite consultas de horas/días
• Motor nativo: MariaDB maneja sus propios timeouts optimizados
• Cierre: 10 segundos con timeout forzado (solo para cleanup)

✅ Variables de Entorno Correctas

• Configuración por ambiente: ENVIRONMENT_DATA_BASE=dev/pro
• Variables consistentes: DB_HOST_DEV/PRO, DB_PWD_DEV/PRO, DATABASE_DEV/PRO
• Mensajes de error claros: Identifica exactamente qué variable falta

🔧 Migración desde versiones anteriores

Cambios en Variables de Entorno

1# ANTES (v1.1.1 y anteriores)
2DB_HOST=localhost
3DB_USER=root
4DB_PASSWORD=password
5DB_NAME=database
6
7# AHORA (v1.1.3)
8ENVIRONMENT_DATA_BASE=dev
9DB_HOST_DEV=localhost
10DB_USER_DEV=root
11DB_PWD_DEV=password
12DATABASE_DEV=database

Código sin cambios necesarios

1// Tu código existente sigue funcionando igual
2import dbManager from "mariadb-pool-cuenti";
3
4const resultado = await dbManager.executeQuery(empresaId, sql, params);
5// ¡Sin cambios necesarios!

📋 Ejemplos de Configuración

Desarrollo Local

1ENVIRONMENT_DATA_BASE=dev
2DB_HOST_DEV=localhost
3DB_USER_DEV=root
4DB_PWD_DEV=mi_password
5DATABASE_DEV=mi_app_dev
6DB_PORT_DEV=3306
7POOL_SIZE_BASE_DEV=5
8ID_APPLICATION=1
9TENANT_POOL_SIZE=10

Producción

1ENVIRONMENT_DATA_BASE=pro
2DB_HOST_PRO=192.168.1.100
3DB_USER_PRO=app_user
4DB_PWD_PRO=password_seguro_123
5DATABASE_PRO=mi_app_produccion
6DB_PORT_PRO=3306
7POOL_SIZE_BASE_PRO=15
8ID_APPLICATION=1
9TENANT_POOL_SIZE=20

🎯 Casos de Uso

1. Aplicación SaaS Multi-tenant

1// Cada cliente (empresa) tiene su propia base de datos
2const clienteId = req.user.empresaId;
3const datos = await dbManager.executeQuery(clienteId, sql, params);

2. Consultas a Bases de Datos Extremadamente Grandes

1// Sin timeouts artificiales - permite consultas que tomen horas
2const reporteCompleto = await dbManager.executeQuery(
3  empresaId,
4  `SELECT 
5     t.id, t.fecha, t.monto, c.nombre, p.descripcion
6   FROM transacciones t 
7   JOIN clientes c ON t.cliente_id = c.id
8   JOIN productos p ON t.producto_id = p.id
9   WHERE t.fecha BETWEEN :inicio AND :fin
10   ORDER BY t.fecha`,
11  { inicio: "2020-01-01", fin: "2024-12-31" }
12);
13// Esta consulta puede tomar 30 minutos, 2 horas, o el tiempo que necesite
14console.log(`Procesadas ${reporteCompleto.length} transacciones`);

3. Microservicios con Cleanup Automático

1// La librería se cierra automáticamente cuando el microservicio termina
2const app = express();
3// ... tu código ...
4// No necesitas código adicional de cleanup

🛡️ Seguridad

• Consultas parametrizadas por defecto
• Conexiones SSL soportadas
• Timeouts para prevenir ataques DoS
• Validación de configuración antes de inicializar
• Manejo seguro de errores sin exposición de detalles internos

📈 Rendimiento

• Pools dinámicos solo cuando se necesitan
• Conexiones reutilizadas entre consultas
• Health checks automáticos
• Reconexión inteligente con backoff
• Memory leak prevention

🔍 Troubleshooting

Error: "Variables de entorno faltantes"

1# Asegúrate de tener todas las variables requeridas
2ENVIRONMENT_DATA_BASE=dev  # o 'pro'
3DB_HOST_DEV=tu_host
4DB_USER_DEV=tu_usuario
5# etc...

Consultas muy largas (horas/días)

1# ✅ v1.3.0+ NO tiene timeouts artificiales
2# Las consultas pueden tomar todo el tiempo que necesiten
3
4# Si tu consulta falla por timeout, revisa tu configuración de MariaDB:
5# wait_timeout = 28800          # 8 horas
6# interactive_timeout = 28800   # 8 horas
7# max_execution_time = 0        # Sin límite para SELECT
8
9# La librería esperará indefinidamente hasta que MariaDB responda

La librería no se cierra con tu aplicación

1// Esto ya está solucionado en v1.1.3
2// Pero si necesitas control manual:
3import { shutdown } from "mariadb-pool-cuenti";
4await shutdown();

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/mi-feature)
3. Commit tus cambios (git commit -am 'Agregar mi feature')
4. Push a la rama (git push origin feature/mi-feature)
5. Crea un Pull Request

📄 Licencia

MIT License - ver archivo LICENSE para más detalles.

🏷️ Versión

v1.4.0 - Versión crítica con cierre sincronizado y SIN timeouts artificiales para bases de datos extremadamente grandes

---

¿Problemas o preguntas? Abre un issue en GitHub.