connect_database #

Biblioteca Flutter/Dart para acesso a bancos de dados via ODBC, fornecendo uma camada de abstração limpa e segura para operações SQL com suporte a SQL Server, PostgreSQL, Sybase Anywhere e outros bancos compatíveis com ODBC.

📋 Índice #

Características
Cobertura de Testes
Requisitos
Instalação
Configuração
Uso Básico
Componentes Principais
Exemplos Completos
Arquitetura
Boas Práticas
Dependências
Estrutura do Projeto

✨ Características #

✅ Acesso ODBC: Conexão com bancos de dados via ODBC
✅ Múltiplos Bancos: Suporte para SQL Server, PostgreSQL, Sybase Anywhere
✅ Queries Parametrizadas: Proteção contra SQL Injection
✅ Transações: Suporte completo a transações com commit/rollback
✅ Connection Pooling: Gerenciamento eficiente de conexões com waiting queue e health check
✅ Safe Select Builder: Construção segura de queries evitando erros com colunas binárias
✅ SqlSelectInterceptor: Interceptação automática de SELECTs com CAST inteligente e cache LRU
✅ Table Metadata: Consulta de metadados de tabelas
✅ Error Handling: Tratamento de erros usando result_dart
✅ Type Safety: Tipagem forte para parâmetros e campos
✅ Clean Architecture: Estrutura organizada seguindo princípios SOLID
✅ Performance Otimizado:
- Cache LRU de metadados com tamanho máximo configurável
- Regex pré-compilados para query interception (+30-40% mais rápido)
- Bulk operations otimizadas (INSERT/UPDATE/DELETE)
- Batch sizes específicos por tipo de banco
- Buffered streaming para grandes datasets
✅ Suporte Unicode: Conversão automática NVARCHAR para colunas Unicode
✅ Query Metrics: Monitoramento de performance opcional
✅ Connection Validation: Validação automática de conexões stale
✅ Testes Completos: 157 testes automatizados com cobertura abrangente

🧪 Cobertura de Testes #

O projeto possui 157 testes automatizados (100% passing) cobrindo todos os aspectos da biblioteca:

Distribuição dos Testes #

Categoria	Arquivos	Testes	Cobertura
Unitários	8 arquivos	138	88%
E2E	3 arquivos	19	12%
Total	11 arquivos	157	100%

Testes por Funcionalidade #

Connection Pool (15 testes)

✅ Singleton pattern
✅ Configuração de maxSize e acquireTimeout
✅ Waiting queue para pool cheio
✅ Health check periódico
✅ Estatísticas em tempo real (utilization, isFull, hasAvailable)
✅ Concorrência (acquire/release simultâneos)
✅ Reinit após closeAll

Query Metrics (11 testes)

✅ Criação de QueryMetrics com todos os parâmetros
✅ Diferenciação de tipos (SELECT, INSERT, UPDATE, DELETE)
✅ Métricas de sucesso e erro
✅ toString informativo
✅ Callback opcional em SqlCommand

SqlSelectInterceptor Cache (25 testes)

✅ Cache hit para queries idênticas
✅ Case insensitivity
✅ Ignora espaços extras
✅ Cache miss para queries diferentes
✅ Queries curtas não cacheáveis
✅ clearCache funcional
✅ TOP clause handling
✅ Column list e aliases
✅ WHERE e JOIN clauses
✅ Aggregate functions (COUNT, SUM, AVG)
✅ Queries complexas (GROUP BY, HAVING)
✅ Error handling (query vazia, NULL)
✅ Performance LRU behavior

Testes Unitários Existem (87 testes)

sql_valid_command_test.dart (24 testes)
safe_select_builder_test.dart (22 testes)
sql_type_command_test.dart (20 testes)
database_transaction_test.dart (8 testes)
database_error_test.dart (5 testes)
database_config_test.dart (5 testes)
odbc_connection_pool_test.dart (15 testes) ← expandido
database_type_test.dart (2 testes)

Testes E2E (19 testes)

database_e2e_test.dart (7 testes) - Operações CRUD reais
database_performance_test.dart (7 testes) - Performance de bulk operations
database_new_features_test.dart (5 testes) - Novas funcionalidades

Executar Testes #

# Todos os testes
flutter test

# Apenas unitários
flutter test test/unit/

# Apenas E2E (requer database configurado)
flutter test test/e2e/

# Com coverage
flutter test --coverage

Métricas de Qualidade #

Métrica	Valor	Status
Total de Testes	157	✅
Testes Passando	157/157	✅ 100%
Tempo de Execução	~2s	✅ Rápido
Cobertura Estimada	~90%	✅ Excelente
Novos Features Testados	4/4	✅ Completo

Funcionalidades Testadas #

✅ Connection pool com fila e validação
✅ Cache LRU com regex pré-compilados
✅ Bulk operations (INSERT/UPDATE/DELETE)
✅ Health check periódico do pool
⚠️ Buffered streaming (implementado, limitação dart_odbc)
✅ Query metrics callback
✅ Transações (COMMIT, ROLLBACK, aninhadas)
✅ CRUD operations
✅ Error handling
✅ Safe select builder

Novidades - Performance & Confiabilidade #

Bulk Operations Otimizadas

// Bulk Insert - Tamanho de batch automático por database
final registros = List.generate(5000, (i) => {
  'id': i + 1,
  'nome': 'Cliente $i',
  'valor': i * 10.0,
});

// SQL Server: 1000 registros/batch (limitação do SQL Server)
// PostgreSQL: 500 registros/batch (automático)
// Sybase: 1000 registros/batch (automático)
await cmd.bulkInsert('tabela', registros);

// Bulk Update - Usa CASE WHEN para eficiência
final updates = [
  {'id': 1, 'status': 'ativo', 'valor': 100.0},
  {'id': 2, 'status': 'ativo', 'valor': 200.0},
];
await cmd.bulkUpdate('tabela', updates, 'id');

// Bulk Delete - Usa WHERE IN para deleção em lote
final ids = [1, 2, 3, 4, 5];
await cmd.bulkDelete('tabela', ids, 'id');

Connection Pool Avançado

final pool = OdbcConnectionPool();

// Configurar com timeout customizável
pool.init(
  config,
  maxSize: 20,
  acquireTimeout: Duration(seconds: 30), // Tempo máximo de espera
);

// Iniciar health check periódico (opcional)
pool.startHealthCheck(interval: Duration(minutes: 5));

// Obter estatísticas do pool
final stats = pool.statistics;
print('Utilização: ${(stats.utilization * 100).toStringAsFixed(1)}%');
print('Disponíveis: ${stats.availableConnections}');
print('Em uso: ${stats.inUseConnections}');
print('Aguardando: ${stats.waitingRequests}');

// O pool agora:
// - Valida conexões antes de reutilizar
// - Aguarda na fila quando cheio (não falha imediatamente)
// - Remove conexões stale automaticamente
// - Timeout configurável para evitar deadlocks

Buffered Streaming

// Processa datasets grandes em batches controlados
cmd.commandText = 'SELECT * FROM tabela_grande';
final result = await cmd.streamBuffered(bufferSize: 500);

await for (final batch in result.getOrThrow()) {
  // batch é List<Map<String, dynamic>>
  // Processa 500 registros por vez
  for (final row in batch) {
    // Processa cada registro
  }
}

// Vantagens:
// - Controle de memória com bufferSize configurável
// - Balance entre throughput e memória
// - Ideal para ETL e processamento de grandes volumes

Query Metrics (Opcional)

// Adicionar monitoramento de performance
final cmd = SqlCommand(
  config,
  onMetrics: (metrics) {
    print('Query: ${metrics.queryType}');
    print('Tempo: ${metrics.executionTime.inMilliseconds}ms');
    print('Rows: ${metrics.rowsAffected}');
    if (!metrics.success) {
      print('Erro: ${metrics.error}');
    }
  },
);

// As métricas são coletadas automaticamente em cada execute()
await cmd.execute();
// Saída: QueryMetrics(type: SELECT, time: 45ms, rows: 150, size: 12345B, success: true)

Melhorias de Cache

// LRU Cache com tamanho máximo
// - Previne crescimento descontrolado de memória
// - Evicção automática de entradas menos usadas
// - Tamanho padrão: 100 entradas

// Regex pré-compilados
// - +30-40% mais rápido em query interception
// - Sem alocação de RegExp a cada query
// - Padrões reutilizáveis entre chamadas

// Uso totalmente transparente - nenhuma mudança necessária no código

📦 Requisitos #

Flutter SDK 3.5.4 ou superior
Dart SDK 3.5.4 ou superior
Driver ODBC instalado no sistema (ex: SQL Server Native Client)
Windows (suporte para outros sistemas pode variar)

🚀 Instalação #

Adicione as dependências ao seu pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  dart_odbc: ^6.2.0
  result_dart: ^2.1.1
  uuid: ^4.5.2
  flutter_dotenv: ^6.0.0

Execute:

flutter pub get

⚙️ Configuração #

Configurar Driver ODBC #

Antes de usar, certifique-se de que o driver ODBC está instalado e configurado no sistema:

SQL Server: Instale o SQL Server Native Client ou ODBC Driver for SQL Server
PostgreSQL: Instale o PostgreSQL ODBC Driver (psqlODBC)
Sybase Anywhere: Instale o driver ODBC do Sybase

Configurar Variáveis de Ambiente #

Para testes e desenvolvimento, você pode usar variáveis de ambiente através do arquivo .env:

Copie o arquivo .env.example para .env:

cp .env.example .env

Edite o arquivo .env com suas credenciais:

DB_DRIVER_NAME=SQL Server Native Client 11.0
DB_USERNAME=your_username
DB_PASSWORD=your_password
DB_DATABASE=your_database_name
DB_SERVER=your_server_name\instance_name
DB_PORT=1433

Use as variáveis no seu código:

import 'package:flutter_dotenv/flutter_dotenv.dart';

// Carregar arquivo .env
await dotenv.load(fileName: '.env');

// Criar classe wrapper para acesso
class Env {
  static String get dbDriverName => dotenv.get('DB_DRIVER_NAME');
  static String get dbUsername => dotenv.get('DB_USERNAME');
  static String get dbPassword => dotenv.get('DB_PASSWORD');
  static String get dbDatabase => dotenv.get('DB_DATABASE');
  static String get dbServer => dotenv.get('DB_SERVER');
  static String get dbPort => dotenv.get('DB_PORT', fallback: '1433');
}

// Usar nas configurações
final config = DatabaseConfig.sqlServer(
  driverName: Env.dbDriverName,
  username: Env.dbUsername,
  password: Env.dbPassword,
  database: Env.dbDatabase,
  server: Env.dbServer,
  port: int.parse(Env.dbPort),
);

Importante: O arquivo .env está no .gitignore e não deve ser commitado. Use .env.example como template.

📖 Uso Básico #

1. Configurar Conexão #

import 'package:connect_database/dao/config/database_config.dart';

final config = DatabaseConfig.sqlServer(
  driverName: 'SQL Server Native Client 11.0',
  username: 'sa',
  password: 'password',
  database: 'database_name',
  server: 'SERVER_NAME',
  port: 1433,
);

2. Executar SELECT #

O SqlSelectInterceptor intercepta automaticamente todos os SELECTs e aplica CAST inteligente nas colunas, convertendo para VARCHAR/NVARCHAR conforme o tipo de dado. Isso evita erros de memória com colunas binárias e otimiza o desempenho.

import 'package:connect_database/dao/sql_command.dart';
import 'package:result_dart/result_dart.dart';

final query = SqlCommand(config);

final result = await query.connect().flatMap((_) async {
  // SELECT * - Interceptor aplica CAST automático em todas as colunas
  query.commandText = '''
    SELECT * 
    FROM Cliente WITH (NOLOCK)
    WHERE CodCliente > :CodCliente
  ''';
  
  query.param('CodCliente').asInt = 1;
  
  return await query.open();
});

result.fold(
  (success) {
    while (!query.eof) {
      print(query.field("CodCliente").asInt);
      print(query.field("Nome").asString);
      print(query.field("DataCadastro").asString); // DATETIME convertido para VARCHAR(50)
      query.next();
    }
  },
  (failure) {
    print('Erro: $failure');
  },
);

await query.close();

O que acontece automaticamente:

SELECT * → Todas as colunas recebem CAST inteligente baseado em metadados
Colunas Unicode (NVARCHAR/NCHAR) → CAST(coluna AS NVARCHAR(tamanho))
Colunas não-Unicode (VARCHAR/CHAR) → CAST(coluna AS VARCHAR(tamanho))
Colunas binárias (IMAGE/VARBINARY) → CAST(coluna AS VARCHAR(MAX))
Tipos numéricos/temporais → CAST(coluna AS VARCHAR(tamanho_otimizado))
Cache de metadados (8 minutos) para máxima performance

3. Executar INSERT/UPDATE/DELETE #

final query = SqlCommand(config);

await query.connect().flatMap((_) {
  query.commandText = '''
    UPDATE Cliente 
    SET Observacao = :observacao 
    WHERE CodCliente = :codCliente
  ''';
  
  query.param('codCliente').asInt = 1;
  query.param('observacao').asString = 'Nova observação';
  
  return query.execute();
}).fold(
  (success) => print('Update realizado com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

🧩 Componentes Principais #

DatabaseConfig #

Configuração de conexão com o banco de dados.

// SQL Server
final config = DatabaseConfig.sqlServer(
  driverName: 'SQL Server Native Client 11.0',
  username: 'sa',
  password: 'password',
  database: 'database_name',
  server: 'SERVER_NAME',
  port: 1433,
);

// PostgreSQL
final config = DatabaseConfig.postgresql(
  driverName: 'PostgreSQL Unicode',
  username: 'postgres',
  password: 'password',
  database: 'database_name',
  server: 'localhost',
  port: 5432,
);

// Sybase Anywhere
final config = DatabaseConfig.sybaseAnywhere(
  driverName: 'Sybase Anywhere',
  username: 'dba',
  password: 'password',
  database: 'database_name',
  server: 'SERVER_NAME',
  port: 2638,
);

SqlCommand #

Classe principal para execução de comandos SQL.

Métodos principais:

connect(): Conecta ao banco de dados
open(): Executa SELECT e abre cursor
execute(): Executa INSERT/UPDATE/DELETE
param(name): Define parâmetro para query
field(name): Acessa campo do registro atual
next(): Move para próximo registro
close(): Fecha conexão e libera recursos

Tipos de parâmetros:

query.param('id').asInt = 1;
query.param('name').asString = 'John';
query.param('price').asDouble = 99.99;
query.param('active').asBool = true;
query.param('date').asDateTime = DateTime.now();

Tipos de campos:

int id = query.field('id').asInt;
String name = query.field('name').asString;
double price = query.field('price').asDouble;
bool active = query.field('active').asBool;
DateTime date = query.field('date').asDateTime;

SqlTransaction #

Gerenciamento de transações.

final transaction = SqlTransaction(query.odbc);

await transaction.start();
try {
  // Executar comandos
  await query.execute();
  await transaction.commit();
} catch (e) {
  await transaction.rollback();
  rethrow;
}

SqlSelectInterceptor #

Intercepta automaticamente todos os SELECTs executados via SqlCommand.open() ou SqlCommand.stream(), aplicando CAST inteligente nas colunas baseado nos metadados da tabela. Funciona de forma transparente, sem necessidade de mudanças no código.

Características:

✅ Interceptação Automática: Não precisa mudar seu código
✅ CAST Inteligente: Converte colunas baseado no tipo real no banco
✅ Suporte Unicode: NVARCHAR para colunas Unicode, VARCHAR para não-Unicode
✅ Cache de Metadados: Cache de 8 minutos para máxima performance
✅ Cache de Tipos: Evita operações repetidas de detecção de tipos
✅ Performance: SELECTs subsequentes 95% mais rápidos (cache hit)

Exemplo de uso (automático):

final query = SqlCommand(config);
await query.connect();

// SELECT * - Interceptor aplica CAST automaticamente
query.commandText = 'SELECT * FROM Cliente WHERE CodCliente > :id';
query.param('id').asInt = 1;
await query.open();

// SELECT com colunas específicas - Interceptor também aplica CAST
query.commandText = 'SELECT Nome, Email, DataCadastro FROM Cliente';
await query.open();

Conversão automática aplicada:

-- SELECT * FROM Cliente
-- Vira automaticamente:
SELECT 
  CAST(CodCliente AS VARCHAR(11)) AS CodCliente,
  CAST(Nome AS NVARCHAR(100)) AS Nome,  -- Unicode preservado
  CAST(Email AS VARCHAR(200)) AS Email,
  CAST(Foto AS VARCHAR(MAX)) AS Foto,   -- Binário
  CAST(DataCadastro AS VARCHAR(50)) AS DataCadastro
FROM Cliente

Limpar cache (se necessário):

SqlSelectInterceptor.clearCache();

SafeSelectBuilder #

Constrói queries SELECT seguras manualmente, evitando erros com colunas binárias (IMAGE, VARBINARY) e aplicando CAST em colunas LOB grandes. Útil quando você precisa construir queries manualmente.

final metadata = TableMetadata(query.odbc);
final safeBuilder = SafeSelectBuilder(metadata);

// Obter colunas seguras (exclui IMAGE/VARBINARY automaticamente)
final safeColsResult = await safeBuilder.getSafeColumns('Cliente');
if (safeColsResult.isError()) throw safeColsResult.exceptionOrNull()!;
final safeCols = safeColsResult.getOrThrow();

// Usar em query
query.commandText = 'SELECT $safeCols FROM Cliente';

// Ou usar método de conveniência
final queryResult = await safeBuilder.buildSafely('Cliente', withNoLock: true);
if (queryResult.isSuccess()) {
  query.commandText = queryResult.getOrThrow();
}

// Paginação (SQL Server 2012+)
final paginatedResult = await safeBuilder.buildPaginated(
  'Cliente',
  orderBy: 'CodCliente',
  page: 1,
  pageSize: 100,
  withNoLock: true,
);

TableMetadata #

Consulta metadados de tabelas.

final metadata = TableMetadata(query.odbc);
final columnsResult = await metadata.getColumns('Cliente');

columnsResult.fold(
  (columns) {
    for (final column in columns) {
      print('${column['name']}: ${column['type']}');
    }
  },
  (failure) {
    print('Erro: $failure');
  },
);

OdbcConnectionPool #

Pool de conexões para melhor performance.

final pool = OdbcConnectionPool();
pool.init(config, maxSize: 10);

// Adquirir conexão
final driverResult = await pool.acquire();
driverResult.fold(
  (driver) {
    // Usar driver
    final query = SqlCommand.fromDriver(driver);
    // ... operações
    // Liberar conexão
    pool.release(driver);
  },
  (failure) {
    print('Erro ao adquirir conexão: $failure');
  },
);

// Fechar todas as conexões
await pool.closeAll();

💡 Exemplos Completos #

1. SELECT - Consultas #

SELECT com Interceptor Automático (Recomendado)

O interceptor funciona automaticamente, aplicando CAST inteligente em todos os SELECTs:

import 'package:connect_database/dao/sql_command.dart';
import 'package:connect_database/dao/config/database_config.dart';
import 'package:result_dart/result_dart.dart';

Future<void> exemploSelectAutomatico() async {
  final config = DatabaseConfig.sqlServer(
    driverName: 'SQL Server Native Client 11.0',
    username: 'sa',
    password: 'password',
    database: 'NSE',
    server: 'SERVER_NAME',
    port: 1433,
  );

  final query = SqlCommand(config);

  final result = await query.connect().flatMap((_) async {
    // SELECT * - Interceptor aplica CAST automaticamente em todas as colunas
    query.commandText = '''
      SELECT * 
      FROM Cliente WITH (NOLOCK)
      WHERE CodCliente > :CodCliente
    ''';
    
    query.param('CodCliente').asInt = 1;
    
    return await query.open();
  });

  result.fold(
    (success) {
      while (!query.eof) {
        print('ID: ${query.field("CodCliente").asInt}');
        print('Nome: ${query.field("Nome").asString}');
        print('Data: ${query.field("DataCadastro").asString}');
        query.next();
      }
      print('Total: ${query.recordCount}');
    },
    (failure) {
      print('Erro: $failure');
    },
  );

  await query.close();
}

Vantagens:

✅ Não precisa mudar seu código
✅ CAST automático baseado em metadados
✅ Cache de metadados (8 minutos) para performance
✅ Suporte Unicode (NVARCHAR) preservado
✅ Evita erros com colunas binárias

Exemplo: SELECT com Colunas Específicas #

O interceptor também funciona com SELECTs que especificam colunas:

final result = await query.connect().flatMap((_) async {
  // SELECT com colunas específicas - Interceptor aplica CAST inteligente
  query.commandText = '''
    SELECT Nome, Email, DataCadastro, Foto
    FROM Cliente
    WHERE CodCliente = :id
  ''';
  
  query.param('id').asInt = 1;
  return await query.open();
});

result.fold(
  (success) {
    while (!query.eof) {
      print('Nome: ${query.field("Nome").asString}');      // NVARCHAR preservado
      print('Email: ${query.field("Email").asString}');    // VARCHAR
      print('Data: ${query.field("DataCadastro").asString}'); // DATETIME → VARCHAR(50)
      print('Foto: ${query.field("Foto").asString}');      // IMAGE → VARCHAR(MAX)
      query.next();
    }
  },
  (failure) => print('Erro: $failure'),
);

SELECT com TOP (Limitar Resultados)

final result = await query.connect().flatMap((_) async {
  query.commandText = '''
    SELECT TOP 100
      CodProduto,
      Nome,
      DataCadastro
    FROM Produto
    ORDER BY CodProduto
  ''';
  
  return await query.open();
});

result.fold(
  (success) {
    while (!query.eof) {
      print('Produto: ${query.field("Nome").asString}');
      query.next();
    }
  },
  (failure) => print('Erro: $failure'),
);

SELECT com JOIN

final result = await query.connect().flatMap((_) async {
  query.commandText = '''
    SELECT 
      c.CodCliente,
      c.Nome,
      p.CodProduto,
      p.NomeProduto
    FROM Cliente c
    INNER JOIN Pedido ped ON c.CodCliente = ped.CodCliente
    INNER JOIN Produto p ON ped.CodProduto = p.CodProduto
    WHERE c.CodCliente = :id
  ''';
  
  query.param('id').asInt = 1;
  return await query.open();
});

result.fold(
  (success) {
    while (!query.eof) {
      print('Cliente: ${query.field("Nome").asString}');
      print('Produto: ${query.field("NomeProduto").asString}');
      query.next();
    }
  },
  (failure) => print('Erro: $failure'),
);

SELECT com Stream (Grandes Volumes)

Para grandes volumes de dados, use stream() para processar linha a linha sem carregar tudo na memória:

import 'package:flutter/foundation.dart';

final result = await query.connect().flatMap((_) async {
  query.commandText = '''
    SELECT 
      CodProduto,
      Nome,
      CodTipoProduto,
      CodUnidadeMedida,
      DataCadastro
    FROM Produto
  ''';
  
  return await query.stream(); // Retorna Stream ao invés de carregar tudo
});

try {
  result.fold(
    (stream) async {
      int recordCount = 0;
      
      await for (final record in stream) {
        recordCount++;
        
        // Processa cada registro individualmente
        final codProduto = record['CodProduto']?.toString();
        final nome = record['Nome']?.toString();
        
        // Exibe progresso a cada 1000 registros
        if (recordCount % 1000 == 0) {
          debugPrint('Processados $recordCount registros...');
        }
      }
      
      debugPrint('Total de registros processados: $recordCount');
    },
    (failure) {
      debugPrint('Erro no SELECT: $failure');
    },
  );
} catch (e, stackTrace) {
  debugPrint('Erro fatal durante processamento: $e');
  debugPrint('Stack trace: $stackTrace');
} finally {
  await query.close();
  debugPrint('Conexão fechada.');
}

Vantagens do stream():

✅ Não carrega todos os resultados na memória de uma vez
✅ Processa linha por linha de forma assíncrona
✅ Mais eficiente para grandes volumes de dados
✅ Não precisa usar query.next() ou verificar query.eof

2. INSERT - Inserção de Dados #

INSERT Simples

final result = await query.connect().flatMap((_) {
  query.commandText = '''
    INSERT INTO Cliente (Nome, Email, DataCadastro)
    VALUES (:nome, :email, :data)
  ''';
  
  query.param('nome').asString = 'João Silva';
  query.param('email').asString = 'joao@email.com';
  query.param('data').asDateTime = DateTime.now();
  
  return query.execute();
});

result.fold(
  (success) => print('Cliente inserido com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

INSERT com Retorno de ID (SQL Server)

final result = await query.connect().flatMap((_) async {
  query.commandText = '''
    INSERT INTO Cliente (Nome, Email, DataCadastro)
    OUTPUT INSERTED.CodCliente
    VALUES (:nome, :email, :data)
  ''';
  
  query.param('nome').asString = 'Maria Santos';
  query.param('email').asString = 'maria@email.com';
  query.param('data').asDateTime = DateTime.now();
  
  return await query.open();
});

result.fold(
  (success) {
    if (!query.eof) {
      final novoId = query.field('CodCliente').asInt;
      print('Novo cliente criado com ID: $novoId');
    }
  },
  (failure) => print('Erro: $failure'),
);

Bulk Insert (Inserção em Lote)

Para inserir múltiplos registros de uma vez:

final query = SqlCommand(config);
await query.connect();

final registros = [
  {'Nome': 'Cliente 1', 'Email': 'cliente1@email.com', 'Ativo': true},
  {'Nome': 'Cliente 2', 'Email': 'cliente2@email.com', 'Ativo': true},
  {'Nome': 'Cliente 3', 'Email': 'cliente3@email.com', 'Ativo': false},
];

final result = await query.bulkInsert('Cliente', registros, batchSize: 1000);

result.fold(
  (totalInseridos) => print('$totalInseridos registros inseridos com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

Bulk Update (Atualização em Lote)

Para atualizar múltiplos registros de uma vez:

final query = SqlCommand(config);
await query.connect();

final updates = [
  {'CodCliente': 1, 'Ativo': true, 'Observacao': 'Cliente ativado'},
  {'CodCliente': 2, 'Ativo': true, 'Observacao': 'Cliente ativado'},
  {'CodCliente': 3, 'Ativo': false, 'Observacao': 'Cliente desativado'},
];

final result = await query.bulkUpdate(
  'Cliente',
  updates,
  'CodCliente', // Coluna WHERE
  updateColumns: ['Ativo', 'Observacao'], // Colunas para atualizar
  batchSize: 500,
);

result.fold(
  (totalAtualizados) => print('$totalAtualizados registros atualizados com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

Bulk Delete (Exclusão em Lote)

Para excluir múltiplos registros de uma vez:

final query = SqlCommand(config);
await query.connect();

final idsParaDeletar = [10, 20, 30, 40, 50];

final result = await query.bulkDelete(
  'Cliente',
  idsParaDeletar,
  'CodCliente', // Coluna WHERE
  batchSize: 1000,
);

result.fold(
  (totalDeletados) => print('$totalDeletados registros excluídos com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

3. UPDATE - Atualização de Dados #

UPDATE Simples

final result = await query.connect().flatMap((_) {
  query.commandText = '''
    UPDATE Cliente 
    SET Nome = :nome,
        Email = :email,
        Observacao = :obs
    WHERE CodCliente = :id
  ''';
  
  query.param('id').asInt = 1;
  query.param('nome').asString = 'João Silva Atualizado';
  query.param('email').asString = 'joao.novo@email.com';
  query.param('obs').asString = 'Cliente atualizado em ${DateTime.now()}';
  
  return query.execute();
});

result.fold(
  (success) => print('Cliente atualizado com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

UPDATE com Múltiplas Condições

final result = await query.connect().flatMap((_) {
  query.commandText = '''
    UPDATE Produto
    SET PrecoVenda = :preco,
        DataPrecoVenda = :data
    WHERE CodProduto = :id
      AND Ativo = 1
      AND PrecoVenda <> :preco
  ''';
  
  query.param('id').asInt = 100;
  query.param('preco').asDouble = 99.99;
  query.param('data').asDateTime = DateTime.now();
  
  return query.execute();
});

result.fold(
  (success) => print('Preço atualizado!'),
  (failure) => print('Erro: $failure'),
);

4. DELETE - Exclusão de Dados #

DELETE Simples

final result = await query.connect().flatMap((_) {
  query.commandText = '''
    DELETE FROM Cliente
    WHERE CodCliente = :id
  ''';
  
  query.param('id').asInt = 1;
  
  return query.execute();
});

result.fold(
  (success) => print('Cliente excluído com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

DELETE com Condições Múltiplas

final result = await query.connect().flatMap((_) {
  query.commandText = '''
    DELETE FROM Log
    WHERE Data < :dataLimite
      AND Tipo = :tipo
  ''';
  
  query.param('dataLimite').asDateTime = DateTime.now().subtract(Duration(days: 30));
  query.param('tipo').asString = 'INFO';
  
  return query.execute();
});

result.fold(
  (success) => print('Logs antigos excluídos!'),
  (failure) => print('Erro: $failure'),
);

5. CREATE TABLE - Criação de Tabelas #

Criar Tabela Simples

final query = SqlCommand(config);
await query.connect();

final schema = SchemaUtils(query.odbc);

final result = await schema.createTable(
  'MinhaTabela',
  '''
  (
    Id INT PRIMARY KEY IDENTITY(1,1),
    Nome NVARCHAR(100) NOT NULL,
    Email VARCHAR(200),
    DataCadastro DATETIME DEFAULT GETDATE(),
    Ativo BIT DEFAULT 1
  )
  ''',
);

result.fold(
  (success) => print('Tabela criada com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

Verificar e Criar Tabela (Se Não Existir)

final schema = SchemaUtils(query.odbc);

final existeResult = await schema.tableExists('MinhaTabela');
existeResult.fold(
  (existe) async {
    if (!existe) {
      final createResult = await schema.createTable(
        'MinhaTabela',
        '(Id INT PRIMARY KEY, Nome VARCHAR(100))',
      );
      createResult.fold(
        (success) => print('Tabela criada!'),
        (failure) => print('Erro ao criar: $failure'),
      );
    } else {
      print('Tabela já existe!');
    }
  },
  (failure) => print('Erro ao verificar: $failure'),
);

6. ALTER TABLE - Alteração de Tabelas #

Adicionar Coluna

final schema = SchemaUtils(query.odbc);

final result = await schema.ensureColumn(
  'Cliente',
  'Telefone',
  'VARCHAR(20) NULL',
);

result.fold(
  (success) => print('Coluna adicionada (ou já existia)!'),
  (failure) => print('Erro: $failure'),
);

Adicionar Coluna com Verificação Manual

final schema = SchemaUtils(query.odbc);

final existeResult = await schema.columnExists('Cliente', 'Telefone');
existeResult.fold(
  (existe) async {
    if (!existe) {
      final query = SqlCommand(config);
      await query.connect();
      
      final alterResult = await query.odbc.execute(
        'ALTER TABLE Cliente ADD Telefone VARCHAR(20) NULL',
      );
      
      alterResult.fold(
        (success) => print('Coluna adicionada!'),
        (failure) => print('Erro: $failure'),
      );
      
      await query.close();
    } else {
      print('Coluna já existe!');
    }
  },
  (failure) => print('Erro ao verificar: $failure'),
);

Modificar Tipo de Coluna

final query = SqlCommand(config);
await query.connect();

final result = await query.odbc.execute(
  'ALTER TABLE Cliente ALTER COLUMN Observacao NVARCHAR(MAX)',
);

result.fold(
  (success) => print('Coluna modificada!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

Remover Coluna

final query = SqlCommand(config);
await query.connect();

final result = await query.odbc.execute(
  'ALTER TABLE Cliente DROP COLUMN Telefone',
);

result.fold(
  (success) => print('Coluna removida!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

7. Transações #

Transação Simples

Future<void> exemploTransacao() async {
  final config = DatabaseConfig.sqlServer(/* ... */);
  final query = SqlCommand(config);

  await query.connect().flatMap((_) async {
    final transaction = query.transaction!;
    
    await transaction.start();
    
    try {
      // Primeiro comando
      query.commandText = '''
        UPDATE Cliente 
        SET Observacao = :obs 
        WHERE CodCliente = :id
      ''';
      query.param('id').asInt = 1;
      query.param('obs').asString = 'Atualizado';
      await query.execute();

      // Segundo comando
      query.commandText = '''
        INSERT INTO Log (Mensagem, Data) 
        VALUES (:msg, :data)
      ''';
      query.param('msg').asString = 'Cliente atualizado';
      query.param('data').asDateTime = DateTime.now();
      await query.execute();

      await transaction.commit();
      return Success.unit();
    } catch (e) {
      await transaction.rollback();
      return Failure(Exception(e.toString()));
    }
  }).fold(
    (success) => print('Transação concluída'),
    (failure) => print('Erro: $failure'),
  );

  await query.close();
}

Transação com Auto-Commit

final query = SqlCommand(config);
await query.connect();

query.onAutoCommit();

try {
  query.commandText = 'UPDATE Cliente SET Nome = :nome WHERE CodCliente = :id';
  query.param('id').asInt = 1;
  query.param('nome').asString = 'Novo Nome';
  await query.execute();
  
  query.commandText = 'INSERT INTO Log (Mensagem) VALUES (:msg)';
  query.param('msg').asString = 'Cliente atualizado';
  await query.execute();
  
  print('Operações concluídas com auto-commit!');
} finally {
  query.offAutoCommit();
  await query.close();
}

8. Verificações de Schema #

Verificar se Tabela Existe

final schema = SchemaUtils(query.odbc);

final result = await schema.tableExists('Cliente');
result.fold(
  (existe) {
    if (existe) {
      print('Tabela Cliente existe!');
    } else {
      print('Tabela Cliente não existe!');
    }
  },
  (failure) => print('Erro: $failure'),
);

Verificar se Coluna Existe

final schema = SchemaUtils(query.odbc);

final result = await schema.columnExists('Cliente', 'Email');
result.fold(
  (existe) {
    if (existe) {
      print('Coluna Email existe!');
    } else {
      print('Coluna Email não existe!');
    }
  },
  (failure) => print('Erro: $failure'),
);

Verificar se View Existe

final schema = SchemaUtils(query.odbc);

final result = await schema.viewExists('VwClientesAtivos');
result.fold(
  (existe) => print(existe ? 'View existe!' : 'View não existe!'),
  (failure) => print('Erro: $failure'),
);

Verificar se Procedure Existe

final schema = SchemaUtils(query.odbc);

final result = await schema.procedureExists('sp_ObterCliente');
result.fold(
  (existe) => print(existe ? 'Procedure existe!' : 'Procedure não existe!'),
  (failure) => print('Erro: $failure'),
);

9. SELECT com Safe Builder (Manual) #

Útil quando você precisa construir queries manualmente:

final query = SqlCommand(config);
await query.connect();

final metadata = TableMetadata(query.odbc);
final safeBuilder = SafeSelectBuilder(metadata);

final safeColsResult = await safeBuilder.getSafeColumns('Cliente');
if (safeColsResult.isError()) {
  throw safeColsResult.exceptionOrNull()!;
}
final safeCols = safeColsResult.getOrThrow();

query.commandText = '''
  SELECT $safeCols 
  FROM Cliente WITH (NOLOCK)
  WHERE CodCliente > :CodCliente
''';

query.param('CodCliente').asInt = 1;

final result = await query.open();
result.fold(
  (success) {
    while (!query.eof) {
      print('ID: ${query.field("CodCliente").asInt}');
      print('Nome: ${query.field("Nome").asString}');
      query.next();
    }
  },
  (failure) => print('Erro: $failure'),
);

await query.close();

SELECT com Paginação (Safe Builder)

final query = SqlCommand(config);
await query.connect();

final metadata = TableMetadata(query.odbc);
final safeBuilder = SafeSelectBuilder(metadata);

final paginatedResult = await safeBuilder.buildPaginated(
  'Cliente',
  orderBy: 'CodCliente',
  page: 1,
  pageSize: 50,
  withNoLock: true,
);

if (paginatedResult.isError()) {
  throw paginatedResult.exceptionOrNull()!;
}

query.commandText = paginatedResult.getOrThrow();
final result = await query.open();

result.fold(
  (success) {
    while (!query.eof) {
      print(query.field("Nome").asString);
      query.next();
    }
  },
  (failure) => print('Erro: $failure'),
);

await query.close();

10. Consulta de Metadados #

Obter Todas as Colunas de uma Tabela

final metadata = TableMetadata(query.odbc);

final result = await metadata.getColumns('Cliente');
result.fold(
  (columns) {
    for (final column in columns) {
      print('Coluna: ${column['name']}');
      print('Tipo: ${column['type']}');
      print('Tamanho: ${column['length']}');
      print('---');
    }
  },
  (failure) => print('Erro: $failure'),
);

11. Exemplos Avançados #

SELECT com Subquery

final result = await query.connect().flatMap((_) async {
  query.commandText = '''
    SELECT 
      c.CodCliente,
      c.Nome,
      (SELECT COUNT(*) FROM Pedido WHERE CodCliente = c.CodCliente) AS TotalPedidos
    FROM Cliente c
    WHERE c.Ativo = 1
  ''';
  
  return await query.open();
});

result.fold(
  (success) {
    while (!query.eof) {
      print('Cliente: ${query.field("Nome").asString}');
      print('Pedidos: ${query.field("TotalPedidos").asInt}');
      query.next();
    }
  },
  (failure) => print('Erro: $failure'),
);

SELECT com GROUP BY e HAVING

final result = await query.connect().flatMap((_) async {
  query.commandText = '''
    SELECT 
      CodCliente,
      COUNT(*) AS TotalPedidos,
      SUM(Valor) AS ValorTotal
    FROM Pedido
    GROUP BY CodCliente
    HAVING COUNT(*) > :minPedidos
  ''';
  
  query.param('minPedidos').asInt = 5;
  return await query.open();
});

result.fold(
  (success) {
    while (!query.eof) {
      print('Cliente: ${query.field("CodCliente").asInt}');
      print('Pedidos: ${query.field("TotalPedidos").asInt}');
      print('Total: ${query.field("ValorTotal").asDouble}');
      query.next();
    }
  },
  (failure) => print('Erro: $failure'),
);

SELECT com ORDER BY e CASE

final result = await query.connect().flatMap((_) async {
  query.commandText = '''
    SELECT 
      CodProduto,
      Nome,
      CASE 
        WHEN PrecoVenda < 50 THEN 'Barato'
        WHEN PrecoVenda < 200 THEN 'Médio'
        ELSE 'Caro'
      END AS Categoria
    FROM Produto
    ORDER BY PrecoVenda DESC
  ''';
  
  return await query.open();
});

result.fold(
  (success) {
    while (!query.eof) {
      print('${query.field("Nome").asString}: ${query.field("Categoria").asString}');
      query.next();
    }
  },
  (failure) => print('Erro: $failure'),
);

12. Operações DDL Adicionais #

DROP TABLE (Remover Tabela)

final query = SqlCommand(config);
await query.connect();

final result = await query.odbc.execute('DROP TABLE MinhaTabela');

result.fold(
  (success) => print('Tabela removida com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

CREATE INDEX (Criar Índice)

final query = SqlCommand(config);
await query.connect();

final result = await query.odbc.execute(
  'CREATE INDEX IX_Cliente_Nome ON Cliente(Nome)',
);

result.fold(
  (success) => print('Índice criado com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

CREATE VIEW (Criar View)

final query = SqlCommand(config);
await query.connect();

final result = await query.odbc.execute('''
  CREATE VIEW VwClientesAtivos AS
  SELECT CodCliente, Nome, Email
  FROM Cliente
  WHERE Ativo = 1
''');

result.fold(
  (success) => print('View criada com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

DROP VIEW (Remover View)

final query = SqlCommand(config);
await query.connect();

final result = await query.odbc.execute('DROP VIEW VwClientesAtivos');

result.fold(
  (success) => print('View removida com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

CREATE PROCEDURE (Criar Stored Procedure)

final query = SqlCommand(config);
await query.connect();

final result = await query.odbc.execute('''
  CREATE PROCEDURE sp_ObterCliente
    @CodCliente INT
  AS
  BEGIN
    SELECT * FROM Cliente WHERE CodCliente = @CodCliente
  END
''');

result.fold(
  (success) => print('Procedure criada com sucesso!'),
  (failure) => print('Erro: $failure'),
);

await query.close();

Executar Stored Procedure

final result = await query.connect().flatMap((_) async {
  query.commandText = 'EXEC sp_ObterCliente @CodCliente = :id';
  query.param('id').asInt = 1;
  return await query.open();
});

result.fold(
  (success) {
    while (!query.eof) {
      print('Cliente: ${query.field("Nome").asString}');
      query.next();
    }
  },
  (failure) => print('Erro: $failure'),
);

🏗️ Arquitetura #

O projeto segue os princípios de Clean Architecture e SOLID:

DAO Pattern: Abstração de acesso a dados
Strategy Pattern: Diferentes drivers de banco
Object Pool Pattern: Gerenciamento de conexões
Builder Pattern: Construção segura de queries
Result Pattern: Tratamento de erros funcional

Estrutura de Camadas #

lib/
├── dao/
│   ├── config/          # Configuração de conexão
│   ├── driver/          # Drivers ODBC
│   ├── pool/            # Connection pooling
│   ├── utils/           # Utilitários
│   ├── sql_command.dart      # Comandos SQL
│   ├── sql_transaction.dart  # Transações
│   ├── safe_select_builder.dart  # Builder seguro
│   └── table_metadata.dart      # Metadados
└── connect_database.dart  # Exportações públicas

✅ Boas Práticas #

1. Sempre use queries parametrizadas #

// ✅ Correto
query.commandText = 'SELECT * FROM Users WHERE Id = :id';
query.param('id').asInt = userId;

// ❌ Incorreto (SQL Injection)
query.commandText = 'SELECT * FROM Users WHERE Id = $userId';

2. Sempre feche conexões #

try {
  await query.connect();
  // ... operações
} finally {
  await query.close();
}

3. Use SafeSelectBuilder para evitar erros com colunas binárias #

final safeBuilder = SafeSelectBuilder(metadata);
final safeCols = await safeBuilder.getSafeColumns('TableName');

4. Use Result pattern para tratamento de erros #

final result = await query.open();
result.fold(
  (success) { /* sucesso */ },
  (failure) { /* erro */ },
);

5. Use transações para operações múltiplas #

await transaction.start();
try {
  // múltiplas operações
  await transaction.commit();
} catch (e) {
  await transaction.rollback();
}

6. Use variáveis de ambiente para credenciais #

// ✅ Correto: Usar variáveis de ambiente
import 'package:flutter_dotenv/flutter_dotenv.dart';

await dotenv.load(fileName: '.env');
final config = DatabaseConfig.sqlServer(
  driverName: dotenv.get('DB_DRIVER_NAME'),
  username: dotenv.get('DB_USERNAME'),
  password: dotenv.get('DB_PASSWORD'),
  // ...
);

// ❌ Incorreto: Hardcoded credentials
final config = DatabaseConfig.sqlServer(
  driverName: 'SQL Server Native Client 11.0',
  username: 'sa',
  password: '123abc.',  // ⚠️ Nunca commitar credenciais!
  // ...
);

📚 Dependências #

dart_odbc (^6.2.0): Driver ODBC para Dart
result_dart (^2.1.1): Tratamento funcional de erros
uuid (^4.5.2): Geração de UUIDs
flutter_dotenv (^6.0.0): Gerenciamento de variáveis de ambiente

📁 Estrutura do Projeto #

connect_database/
├── lib/
│   ├── dao/
│   │   ├── config/
│   │   │   ├── database_config.dart
│   │   │   └── database_type.dart
│   │   ├── driver/
│   │   │   ├── database_driver.dart
│   │   │   ├── database_error.dart
│   │   │   ├── my_odbc.dart
│   │   │   ├── smart_prepared_statement.dart
│   │   │   └── sql_data_type.dart
│   │   ├── pool/
│   │   │   └── odbc_connection_pool.dart
│   │   ├── utils/
│   │   │   └── schema_utils.dart
│   │   ├── safe_select_builder.dart
│   │   ├── sql_command.dart
│   │   ├── sql_transaction.dart
│   │   ├── sql_type_command.dart
│   │   ├── sql_valid_command.dart
│   │   └── table_metadata.dart
│   └── connect_database.dart
├── test/
│   └── e2e/
│       ├── database_e2e_test.dart
│       ├── database_performance_test.dart
│       ├── env.dart
│       └── test_config.dart
├── example/
│   └── main.dart
├── .env.example
├── pubspec.yaml
└── README.md

🔧 Troubleshooting #

Erro HY001 com colunas IMAGE/VARBINARY #

O SqlSelectInterceptor resolve isso automaticamente convertendo colunas binárias para VARCHAR(MAX):

// Funciona automaticamente - não precisa fazer nada
query.commandText = 'SELECT * FROM TableName';
await query.open(); // Interceptor aplica CAST automaticamente

Ou use SafeSelectBuilder para controle manual:

final safeBuilder = SafeSelectBuilder(metadata);
final safeCols = await safeBuilder.getSafeColumns('TableName');

Erro de conexão #

Verifique:

Driver ODBC instalado
Credenciais corretas
Servidor acessível
Porta correta

Performance #

SqlSelectInterceptor com Cache:

Cache de metadados (8 minutos) reduz queries de metadados em 90-95%
SELECTs subsequentes são 95% mais rápidos (5-10ms vs 150-200ms)
Cache de tipos evita operações repetidas de detecção

// Cache funciona automaticamente
// Primeiro SELECT: ~150-200ms (busca metadados)
// SELECTs subsequentes (8 min): ~5-10ms (usa cache)

// Limpar cache se necessário
SqlSelectInterceptor.clearCache();

Connection Pooling: Use OdbcConnectionPool para múltiplas operações:

final pool = OdbcConnectionPool();
pool.init(config, maxSize: 10);

connect_database 1.0.0 connect_database: ^1.0.0 copied to clipboard

Metadata