QueryBuilder para MariaDB

Un QueryBuilder poderoso y seguro para bases de datos MariaDB, compatible con el framework JERK. Proporciona una interfaz fluida para construir consultas SQL complejas de manera segura y eficiente.

Características

• Interfaz fluida: Construye consultas SQL complejas con una sintaxis intuitiva
• Seguridad: Protección contra inyección SQL mediante parámetros preparados
• Operaciones CRUD completas: Soporte para SELECT, INSERT, UPDATE, DELETE
• Funciones avanzadas: JOINs, WHERE conditions, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET
• Funciones de agregación: COUNT, MAX, MIN, SUM, AVG
• Adaptador MariaDB: Conexión robusta con sistema de pools y manejo de errores
• Manejo profesional de errores: Detección y mensajes específicos para errores de conexión y autenticación
• Configurable: Timeouts y parámetros configurables mediante variables de entorno

Instalación

npm install qbuilderjs

Uso Básico

Configuración

Configura las variables de entorno:

DB_HOST=localhost
DB_PORT=3306
DB_USER=usuario
DB_PASSWORD=contraseña
DB_NAME=nombre_de_la_base_de_datos
DB_CONNECTION_LIMIT=10
DB_CONNECT_TIMEOUT=10000
DB_EXECUTE_TIMEOUT=30000
DB_ACQUIRE_TIMEOUT=20000
DB_QUERY_TIMEOUT=30000

Ejemplo Básico

const { QueryBuilder } = require('jerkjs-querybuilder-mariadb');
const { getSharedAdapter } = require('jerkjs-querybuilder-mariadb/adapter/mariadb/dbAdapter');

// Obtener el adaptador de base de datos
const adapter = getSharedAdapter();

// Crear una instancia del QueryBuilder
const qb = new QueryBuilder(adapter, 'usuarios');

// Ejecutar una consulta SELECT
const usuarios = await qb
  .select('id', 'nombre', 'email')
  .where('activo', true)
  .orderBy('nombre', 'ASC')
  .get();

console.log(usuarios);

Ejemplos de Uso

Ejecutar ejemplos

Para ejecutar los ejemplos incluidos en el proyecto:

# Ejemplo de SELECT
node examples/ejemplo-select.js

# Ejemplo de INSERT con parámetro
node examples/ejemplo-insert.js "Nombre de Prueba"

# Ejemplo de UPDATE con parámetros
node examples/ejemplo-update.js 1 "Nuevo Nombre" "[email protected]"

# Ejemplo de DELETE con parámetro
node examples/ejemplo-delete.js 1

SELECT

// Selección simple
const resultados = await qb
  .select('campo1', 'campo2')
  .from('tabla')
  .where('condicion', '=', 'valor')
  .get();

// Obtener solo el primer resultado
const resultado = await qb
  .select('*')
  .from('tabla')
  .where('id', 1)
  .first();

INSERT

const datos = {
  nombre: 'Juan Pérez',
  email: '[email protected]',
  activo: true
};

const resultado = await qb
  .table('usuarios')
  .insert(datos);

UPDATE

const datosActualizados = {
  nombre: 'Nuevo Nombre',
  email: '[email protected]'
};

const filasAfectadas = await qb
  .table('usuarios')
  .where('id', 1)
  .update(datosActualizados);

DELETE

const filasEliminadas = await qb
  .table('usuarios')
  .where('activo', false)
  .delete();

Manejo de Errores

El adaptador proporciona mensajes específicos para diferentes tipos de errores:

• Errores de conexión: "No hay conexión disponible a la base de datos. Por favor, verifique que el servidor de base de datos esté activo y accesible."
• Errores de autenticación: "Acceso denegado a la base de datos. Por favor, verifique que el usuario y contraseña sean correctos."
• Puertos no estándar: "Puerto X no es un puerto estándar de MariaDB/MySQL (3306 o 3307), ¿es correcto?"

Configuración de Timeouts

Todos los timeouts son configurables mediante variables de entorno:

• DB_CONNECT_TIMEOUT: Timeout para establecer conexión (por defecto: 10000ms)
• DB_EXECUTE_TIMEOUT: Timeout para ejecutar consultas (por defecto: 30000ms)
• DB_ACQUIRE_TIMEOUT: Timeout para adquirir conexión del pool (por defecto: 20000ms)
• DB_QUERY_TIMEOUT: Timeout para consultas (por defecto: 30000ms)

Seguridad

El QueryBuilder utiliza parámetros preparados para prevenir inyección SQL. Además, el sistema de validación de credenciales evita el uso de valores por defecto potencialmente inseguros.

Contribución

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía un pull request en GitHub.

Licencia

MIT