Marraia.MySql 3.0.0

Marraia.MySql

Biblioteca para auxiliar sua conexão com o MySQL de forma fácil, segura e escalável.
Compatível com Dapper, fornece integração simples com padrões de repositório, Unit of Work e transações.

🚀 Recursos principais

• ✅ Suporte a conexões separadas para leitura e escrita (read/write)
• ✅ Controle de paralelismo seguro com SemaphoreSlim
• ✅ Total compatibilidade retroativa com o modelo anterior (IDbConnection)
• ✅ Abstração via IReadDbConnection e IWriteDbConnection para injeção de dependência (modo read/write)
• ✅ Gerenciamento automático de abertura/fechamento de conexões

🧩 Instalação

Via .NET CLI:

dotnet add package Marraia.MySql

Via Package Manager Console:

Install-Package Marraia.MySql

⚙️ Configuração no Startup / Program.cs

🔸 Modo recomendado (conexão por operação com factory)

// Registra factory para criar conexões por operação
// Este é o modo recomendado que evita problemas de descarte com MySql.Data 9.1.0+
services.AddMySql("Server=db;Database=MinhaBase;User=usuario;Password=senha;");

Vantagens:

• ✅ Sem problemas de descarte de conexões
• ✅ Melhor compatibilidade com MySql.Data 9.1.0+
• ✅ Connection pooling gerenciado pelo MySQL Connector
• ✅ Cada operação cria, usa e descarta sua própria conexão

🔹 Modo avançado (com leitura e escrita separadas)

services.AddMySql(
    connectionStringRead:  "Server=db-ro;Database=MinhaBase;User=usuario_ro;Password=senha_ro;",
    connectionStringWrite: "Server=db-rw;Database=MinhaBase;User=usuario_rw;Password=senha_rw;"
);

⚠️ Modo singleton (obsoleto)

// Obsoleto - use AddMySql em vez disso
// Mantido apenas para compatibilidade com código legado
[Obsolete]
services.AddMySqlSingleton("Server=db;Database=MinhaBase;User=usuario;Password=senha;");

⚙️ Testes de integração 🧪

• Requisitos:

  • Docker rodando localmente
  • .NET SDK 6.0

• Para executar os testes de integração:

dotnet test ./Marraia.MySql.UnitTest

Se ocorrerem erros relacionados a versões de pacotes, assegure-se de usar as versões compatíveis com .NET 6 (o projeto de teste já está configurado com versões compatíveis).

🧱 Exemplo de uso em repositório

public class ClienteRepository : RepositoryStandard<Cliente, int>
{
    // Construtor recomendado usando factory (conexão por operação)
    public ClienteRepository(IDbConnectionFactory factory, ITransactionBase tx)
        : base(factory, tx)
    {
    }

    // Exemplo de leitura - conexão criada, usada e descartada automaticamente
    public async Task<IEnumerable<Cliente>> ObterTodosAsync()
    {
        return await ExecuteSafeAsync(conn =>
            conn.QueryAsync<Cliente>("SELECT * FROM Cliente"));
    }

    // Exemplo de escrita - conexão criada, usada e descartada automaticamente
    public async Task<int> InserirAsync(Cliente cliente)
    {
        return await ExecuteSafeAsync(conn =>
            conn.ExecuteAsync("INSERT INTO Cliente (Nome, Email) VALUES (@Nome, @Email)", cliente));
    }
}

// Modo alternativo com conexões separadas (Read/Write)
public class ClienteRepositoryAdvanced : RepositoryStandard<Cliente, int>
{
    public ClienteRepositoryAdvanced(IReadDbConnection read, IWriteDbConnection write, ITransactionBase tx)
        : base(read, write, tx)
    {
    }

    // Exemplo usando conexão de leitura
    public async Task<IEnumerable<Cliente>> ObterTodosAsync()
    {
        return await ExecuteReadAsync(conn =>
            conn.QueryAsync<Cliente>("SELECT * FROM Cliente"));
    }

    // Exemplo usando conexão de escrita
    public async Task<int> InserirAsync(Cliente cliente)
    {
        return await ExecuteWriteAsync(conn =>
            conn.ExecuteAsync("INSERT INTO Cliente (Nome, Email) VALUES (@Nome, @Email)", cliente));
    }
}

💡 Sobre o RepositoryStandard

A classe base RepositoryStandard usa o padrão de conexão por operação:

Como funciona:

• Cada método (ExecuteSafeAsync, ExecuteReadAsync, ExecuteWriteAsync) cria uma nova conexão
• A conexão é aberta no início da operação
• A conexão é automaticamente descartada ao final da operação (usando using pattern)
• O MySQL Connector gerencia o connection pooling automaticamente

Benefícios:

• ✅ Elimina erros de descarte com MySql.Data 9.1.0+
• ✅ Melhor isolamento entre operações
• ✅ Compatível com async/await
• ✅ Sem necessidade de implementar IDisposable nos repositórios

🧰 Exemplo de uso com UnitOfWork

using (var uow = _unitOfWork.BeginTransaction())
{
    await _clienteRepository.InserirAsync(cliente);
    await _pedidoRepository.InserirAsync(pedido);

    uow.Commit();
}

🏗️ Compatibilidade

🧾 Histórico de versões

v3.0.0 (Breaking Changes)

• 🎯 MUDANÇA PRINCIPAL: Migração para padrão de conexão por operação usando factory
• ✅ Criada interface IDbConnectionFactory para gerenciar criação de conexões
• ✅ Atualizado AddMySql() para registrar factory em vez de conexões Scoped/Singleton
• ✅ Refatorado RepositoryStandard para criar/descartar conexões por operação
• ✅ Refatorado RepositoryBase e RepositoryCommon com mesmo padrão
• ✅ Atualizado UnitOfWork para usar factory e gerenciar ciclo de vida da conexão
• ✅ Eliminados logs de erro de descarte com MySql.Data 9.1.0+
• ✅ Melhor compatibilidade com async/await usando OpenAsync e DisposeAsync
• ⚠️ AddMySqlSingleton marcado como obsoleto
• ⚠️ Breaking: Construtores de repositórios agora esperam IDbConnectionFactory em vez de IDbConnection

Motivo da mudança:

• MySql.Data 9.1.0 apresenta problemas ao descartar conexões gerenciadas pelo DI como Scoped/Singleton
• Padrão de conexão por operação é a recomendação oficial e elimina esses problemas
• Connection pooling continua funcionando normalmente (gerenciado pelo MySQL Connector)

Migração:

// ANTES (v2.x)
public class MeuRepository : RepositoryStandard<MinhaEntity, int>
{
    public MeuRepository(IDbConnection connection, ITransactionBase tx)
        : base(connection, tx) { }
}

// DEPOIS (v3.0)
public class MeuRepository : RepositoryStandard<MinhaEntity, int>
{
    public MeuRepository(IDbConnectionFactory factory, ITransactionBase tx)
        : base(factory, tx) { }
}

v2.0.0

• Adicionado suporte a conexões de leitura e escrita.
• Implementado controle de paralelismo seguro com SemaphoreSlim.
• Mantida compatibilidade total com o modo anterior (IDbConnection).
• Adicionada separação via IReadDbConnection e IWriteDbConnection para injeção e escalabilidade.
• Adicionada a opção AddMySqlSingleton para registrar serviços como singleton quando desejado.
• Registrado MySqlGuidTypeHandler e removidos mapas de tipo para Guid/Guid? no Dapper para evitar conflitos.
• Melhor gerenciamento de conexões, evitando DataReader abertos.

v1.x

• Conexão única com IDbConnection.
• Suporte básico a Dapper e Unit of Work.

🧑‍💻 Contribuições

Contribuições são bem-vindas!
Abra um pull request ou relate problemas em GitHub Issues.

⚖️ Licença

Distribuído sob a licença MIT.
Consulte o arquivo LICENSE para mais informações.