@groundbrick/db-mysql

@groundbrick/db-mysql

Cliente MySQL para o microframework TypeScript, implementando o contrato @groundbrick/db-core (espelho do @groundbrick/db-postgres): connection pooling, gerenciamento de transações, monitoramento de saúde e sistema de migrações.

Features

• Connection Pooling — usando mysql2 com pool configurável
• Singleton Factory — gerenciamento centralizado de instâncias de clientes
• Transaction Management — transações automáticas e manuais via BaseTransaction
• Health Monitoring — verificações de saúde com métricas de timing
• Migration System — migrações com seções UP/DOWN e checksum
• TypeScript Support — tipagem completa para queries e configurações
• Error Handling — tipos de erro específicos (ConnectionError, QueryError, etc.)

Instalação

npm install @groundbrick/db-mysql

Peer Dependencies

npm install mysql2

Quick Start

1. Configuração

// src/database.ts
import { MysqlFactory, MysqlConfig } from '@groundbrick/db-mysql';
import { createLogger } from '@groundbrick/logger';

const config: MysqlConfig = {
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '3306'),
  database: process.env.DB_NAME || 'myapp',
  user: process.env.DB_USER || 'root',
  password: process.env.DB_PASSWORD || 'secret',

  // Pool de conexões
  connectionLimit: 10,
  connectTimeout: 60000,
};

const logger = createLogger({ context: 'database' });
export const dbClient = MysqlFactory.getInstance(config, logger);

2. Inicialização e Queries

import { dbClient } from './database.js';

await dbClient.initialize();

const users = await dbClient.query<{ id: number; name: string; email: string }>(
  'SELECT id, name, email FROM users WHERE active = ?',
  [true]
);

console.log(`Found ${users.rowCount} users:`, users.rows);

process.on('SIGTERM', async () => {
  await dbClient.close();
  process.exit(0);
});

3. Transações

// Transação automática (recomendado)
const result = await dbClient.transaction(async (trx) => {
  await trx.query('INSERT INTO audit_logs (action, user_id) VALUES (?, ?)',
    ['USER_CREATED', 123]);

  const insert = await trx.query(
    'INSERT INTO users (name, email) VALUES (?, ?)',
    ['João Silva', 'joao@example.com']
  );

  return insert;
});

Sistema de Migrações

import { MysqlMigrator } from '@groundbrick/db-mysql';

const migrator = new MysqlMigrator(dbClient, './migrations', logger.child('migrator'));

await migrator.migrate();        // aplica pendentes
await migrator.rollback(2);      // desfaz as últimas 2
const status = await migrator.getStatus();

Formato de arquivo de migração

-- Criar tabela de usuários
CREATE TABLE users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  email VARCHAR(100) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- DOWN
DROP TABLE IF EXISTS users;

Regras: seção UP antes de -- DOWN, seção DOWN depois; primeira linha -- vira a descrição; arquivos aplicados em ordem lexicográfica; rollback executa DOWN em ordem reversa.

Error Handling

import { ConnectionError, QueryError, TransactionError, MigrationError } from '@groundbrick/db-core';

try {
  await dbClient.query('SELECT * FROM users');
} catch (error) {
  if (error instanceof ConnectionError) {
    // reconectar / fallback
  } else if (error instanceof QueryError) {
    // erro na query
  }
}

API

Exporta MysqlClient, MysqlTransaction, MysqlDatabaseFactory, MysqlFactory, MysqlMigrator, MysqlSqlAdapter, normalizeResult e o tipo MysqlConfig. A superfície segue o contrato DatabaseClient/QueryResult de @groundbrick/db-core, idêntica ao @groundbrick/db-postgres (apenas placeholders ? em vez de $1).

Dependencies

• @groundbrick/db-core — abstrações de banco de dados
• @groundbrick/logger — sistema de logging
• peer: mysql2 — driver MySQL para Node.js (^3.11.0)

License

MIT