drizzle-multitenant 1.0.3 → 1.0.5

package/proposals/improvements-from-primesys.md

@@ -0,0 +1,385 @@
+# Proposal: Melhorias Identificadas no PrimeSys-v2
+
+> **Status**: Proposta
+> **Origem**: Integração com PrimeSys-v2
+> **Data**: 2024-12-23
+
+## Contexto
+
+Durante a integração do `drizzle-multitenant` no projeto PrimeSys-v2 (multi-tenant SaaS para gestão industrial), foram identificadas melhorias que beneficiariam o pacote e outros usuários.
+
+---
+
+## 1. CLI: Flag `--mark-applied`
+
+### Problema
+
+Projetos que já têm migrations aplicadas (via scripts legados) precisam sincronizar o tracking sem re-executar as migrations.
+
+### Solução
+
+Adicionar flag `--mark-applied` ao comando `migrate`:
+
+```bash
+# Marca migrations como aplicadas sem executar SQL
+npx drizzle-multitenant migrate --all --mark-applied
+
+# Para tenant específico
+npx drizzle-multitenant migrate --tenant=abc --mark-applied
+```
+
+### Implementação
+
+```typescript
+// src/cli/commands/migrate.ts
+.option('--mark-applied', 'Mark migrations as applied without executing SQL')
+
+// No handler
+if (options.markApplied) {
+  await migrator.markAllAsApplied(tenantIds);
+} else {
+  await migrator.migrateAll({ concurrency, dryRun });
+}
+```
+
+### Benefício
+
+- Facilita migração de projetos existentes
+- Útil para sincronizar ambientes de staging/produção
+- Evita necessidade de scripts manuais
+
+---
+
+## 2. CLI: Comando `sync`
+
+### Problema
+
+Detectar e corrigir divergências entre migrations em disco e tracking no banco.
+
+### Solução
+
+Novo comando `sync` com opções:
+
+```bash
+# Mostrar divergências
+npx drizzle-multitenant sync --status
+
+# Marcar migrations faltantes como aplicadas
+npx drizzle-multitenant sync --mark-missing
+
+# Remover registros órfãos (migrations que não existem mais em disco)
+npx drizzle-multitenant sync --clean-orphans
+```
+
+### Casos de Uso
+
+1. **Migration renomeada**: Arquivo renomeado, mas registro antigo no banco
+2. **Migration deletada**: Arquivo removido, registro ainda existe
+3. **Ambiente dessincronizado**: Migrations aplicadas manualmente
+
+---
+
+## 3. Compatibilidade com Tabelas de Tracking Legadas
+
+### Problema
+
+Projetos podem usar estruturas de tabela diferentes:
+- Hash-based: `id, hash, created_at`
+- Name-based: `id, name, applied_at` (padrão drizzle-multitenant)
+
+### Solução
+
+Suportar múltiplos formatos ou migração automática:
+
+```typescript
+// tenant.config.ts
+migrations: {
+  tenantFolder: "./drizzle/tenant",
+  tenantDiscovery: discoverTenants,
+  migrationsTable: "__drizzle_migrations",
+
+  // NOVO: Formato da tabela
+  tableFormat: "name", // "name" | "hash" | "auto-detect"
+
+  // NOVO: Migrar formato automaticamente
+  autoMigrateFormat: true,
+}
+```
+
+### Alternativa
+
+Script de migração incluído no pacote:
+
+```bash
+npx drizzle-multitenant migrate-tracking-format --from=hash --to=name
+```
+
+---
+
+## 4. Health Check API
+
+### Problema
+
+Aplicações precisam verificar saúde dos pools para load balancers e monitoring.
+
+### Solução
+
+Método `healthCheck()` no TenantManager:
+
+```typescript
+const manager = createTenantManager(config);
+
+const health = await manager.healthCheck();
+// {
+//   healthy: true,
+//   pools: [
+//     { tenantId: 'abc', status: 'ok', connections: 5, idle: 3 },
+//     { tenantId: 'def', status: 'degraded', connections: 1, idle: 0 },
+//   ],
+//   sharedDb: { status: 'ok', connections: 10 },
+//   timestamp: '2024-12-23T10:30:00Z'
+// }
+
+// Endpoint para load balancers
+app.get('/health/db', async (req, res) => {
+  const health = await manager.healthCheck();
+  res.status(health.healthy ? 200 : 503).json(health);
+});
+```
+
+### Já no Roadmap
+
+Previsto para v1.1.0 (Resiliência e Observabilidade).
+
+---
+
+## 5. Métricas Prometheus
+
+### Problema
+
+Monitoramento de pools e queries é essencial para produção.
+
+### Solução
+
+Exportar métricas no formato Prometheus:
+
+```typescript
+// Configuração
+const config = defineConfig({
+  metrics: {
+    enabled: true,
+    prefix: 'drizzle_multitenant',
+  },
+});
+
+// Endpoint
+app.get('/metrics', (req, res) => {
+  res.set('Content-Type', 'text/plain');
+  res.send(manager.getPrometheusMetrics());
+});
+```
+
+**Métricas sugeridas:**
+```
+drizzle_multitenant_pool_count 15
+drizzle_multitenant_pool_connections_active{tenant="abc"} 3
+drizzle_multitenant_pool_connections_idle{tenant="abc"} 7
+drizzle_multitenant_pool_evictions_total 42
+drizzle_multitenant_query_duration_seconds_bucket{le="0.1"} 1024
+```
+
+### Já no Roadmap
+
+Previsto para v1.1.0 (Resiliência e Observabilidade).
+
+---
+
+## 6. NestJS: `@TenantId()` Parameter Decorator
+
+### Problema
+
+Extrair `tenantId` do request requer código boilerplate:
+
+```typescript
+@Get()
+async getData(@Param('empresaId') empresaId: string) {
+  return this.service.getData(empresaId);
+}
+```
+
+### Solução
+
+Decorator que extrai automaticamente baseado na config:
+
+```typescript
+import { TenantId } from 'drizzle-multitenant/nestjs';
+
+@Get()
+async getData(@TenantId() tenantId: string) {
+  return this.service.getData(tenantId);
+}
+```
+
+### Implementação
+
+```typescript
+// src/integrations/nestjs/decorators/tenant-id.decorator.ts
+export const TenantId = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext): string => {
+    const request = ctx.switchToHttp().getRequest();
+    // Usa extractTenantId configurado no TenantModule
+    return request.tenantId; // Setado pelo middleware
+  },
+);
+```
+
+---
+
+## 7. Pool Warmup
+
+### Problema
+
+Primeiro request para um tenant tem latência maior (cold start do pool).
+
+### Solução
+
+API para pré-aquecer pools:
+
+```typescript
+// Warmup de tenants específicos
+await manager.warmup(['tenant-1', 'tenant-2', 'tenant-3']);
+
+// Warmup de todos (usar com cuidado)
+const tenants = await discoverTenants();
+await manager.warmup(tenants.slice(0, 20)); // Top 20 mais ativos
+
+// No bootstrap da aplicação NestJS
+@Injectable()
+export class WarmupService implements OnApplicationBootstrap {
+  constructor(@InjectTenantManager() private manager: TenantManager) {}
+
+  async onApplicationBootstrap() {
+    const topTenants = await this.getTopTenants();
+    await this.manager.warmup(topTenants);
+  }
+}
+```
+
+---
+
+## 8. Debug Mode Aprimorado
+
+### Problema
+
+Debugar queries multi-tenant é difícil sem contexto.
+
+### Solução
+
+Modo debug que loga queries com tenant context:
+
+```typescript
+const config = defineConfig({
+  debug: {
+    enabled: process.env.NODE_ENV === 'development',
+    logQueries: true,
+    logPoolEvents: true,
+    slowQueryThreshold: 1000, // ms
+  },
+});
+
+// Output
+// [drizzle-multitenant] tenant=abc query="SELECT * FROM produtos" duration=45ms
+// [drizzle-multitenant] tenant=abc SLOW_QUERY query="SELECT..." duration=1523ms
+```
+
+---
+
+## 9. Retry Logic para Conexões
+
+### Problema
+
+Conexões podem falhar temporariamente (network issues, DB restart).
+
+### Solução
+
+Retry automático com backoff exponencial:
+
+```typescript
+const config = defineConfig({
+  connection: {
+    url: process.env.DATABASE_URL!,
+    retry: {
+      maxAttempts: 3,
+      initialDelayMs: 100,
+      maxDelayMs: 5000,
+      backoffMultiplier: 2,
+    },
+  },
+});
+```
+
+### Já no Roadmap
+
+Previsto para v1.1.0 (Resiliência e Observabilidade).
+
+---
+
+## 10. Cross-Schema Query Improvements
+
+### Problema
+
+Queries que juntam tenant + shared tables são verbosas.
+
+### Solução Atual (v1.0)
+
+```typescript
+const query = createCrossSchemaQuery({
+  tenantDb: tenants.getDb('tenant-123'),
+  sharedDb: tenants.getSharedDb(),
+  tenantSchema: 'tenant_123',
+  sharedSchema: 'public',
+});
+```
+
+### Solução Proposta
+
+Helper mais simples:
+
+```typescript
+// Usando TenantDbFactory
+const db = this.dbFactory.getDb(tenantId);
+
+// Novo: withShared() helper
+const result = await db
+  .withShared(this.sharedDb)
+  .select({
+    pedidoId: pedido.id,
+    workflowNome: workflowStep.nome, // da tabela public
+  })
+  .from(pedido)
+  .leftJoin(workflowStep, eq(pedido.workflowStepId, workflowStep.id));
+```
+
+---
+
+## Priorização Sugerida
+
+| Melhoria | Esforço | Impacto | Prioridade |
+|----------|---------|---------|------------|
+| `--mark-applied` flag | 2h | Alto | P0 |
+| `@TenantId()` decorator | 1h | Médio | P1 |
+| Pool warmup | 2h | Médio | P1 |
+| Health check API | 4h | Alto | P1 |
+| Debug mode | 3h | Médio | P2 |
+| Retry logic | 4h | Alto | P2 |
+| Métricas Prometheus | 6h | Alto | P2 |
+| Sync command | 4h | Médio | P2 |
+| Tabela legada compat | 4h | Baixo | P3 |
+| Cross-schema helper | 6h | Médio | P3 |
+
+---
+
+## Referências
+
+- [PrimeSys-v2 Migration Proposal](../../PrimeSys-v2/proposals/backlog/drizzle-multitenant-migration.md)
+- [drizzle-multitenant Roadmap](../roadmap.md)

package/roadmap.md

@@ -42,6 +42,14 @@
 - [x] 148 testes passando
 - [x] Licença MIT
 
+### v1.0.3 - NestJS DX Improvements
+- [x] `TenantDbFactory` para singleton services (cron jobs, event handlers)
+- [x] `@InjectTenantDbFactory()` decorator
+- [x] Debug utilities para proxies (`__debug`, `__tenantId`, `__isProxy`)
+- [x] `console.log(tenantDb)` mostra informações úteis
+- [x] CLI `migrationsTable` config support
+- [x] 154 testes passando
+
 ---
 
 ## Próximas Versões
@@ -792,13 +800,103 @@ const stats = await adminQuery
 
 ## Quick Wins (Podem entrar em qualquer versão)
 
-| Feature | Esforço | Versão |
-|---------|---------|--------|
-| Health check API | 2h | v1.1.0 |
-| Schema name sanitization | 1h | v1.2.0 |
-| CLI interativo básico | 4h | v1.5.0 |
-| Structured logging hook | 2h | v1.1.0 |
-| Tenant clone (schema only) | 4h | v1.5.0 |
+| Feature | Esforço | Versão | Status |
+|---------|---------|--------|--------|
+| Health check API | 2h | v1.1.0 | Pendente |
+| Schema name sanitization | 1h | v1.2.0 | Pendente |
+| CLI interativo básico | 4h | v1.5.0 | Pendente |
+| Structured logging hook | 2h | v1.1.0 | Pendente |
+| Tenant clone (schema only) | 4h | v1.5.0 | Pendente |
+| ~~CLI migrationsTable config~~ | 1h | v1.0.3 | **Concluído** |
+| ~~TenantDbFactory para singletons~~ | 2h | v1.0.3 | **Concluído** |
+| ~~Debug utilities para proxies~~ | 1h | v1.0.3 | **Concluído** |
+
+---
+
+## v1.0.4 - CLI migrationsTable Support
+
+### Problema
+
+A CLI do `drizzle-multitenant` usa a tabela `__drizzle_migrations` para tracking de migrations, mas não permite configurar um nome diferente. Isso causa incompatibilidade com projetos que já usam outra tabela de tracking (ex: `__drizzle_tenant_migrations`).
+
+### Solução
+
+Ler o campo `migrationsTable` do objeto `migrations` na config e passá-lo para o `Migrator`.
+
+### Mudanças Necessárias
+
+#### 1. Atualizar `loadConfig` em `src/cli/utils.ts`
+
+```typescript
+export async function loadConfig(configPath?: string) {
+  // ... código existente ...
+
+  return {
+    config: exported,
+    migrationsFolder: exported.migrations?.tenantFolder,
+    tenantDiscovery: exported.migrations?.tenantDiscovery,
+    migrationsTable: exported.migrations?.migrationsTable, // NOVO
+  };
+}
+```
+
+#### 2. Atualizar comandos em `src/cli/commands/`
+
+Passar `migrationsTable` para o `createMigrator`:
+
+```typescript
+// migrate.ts, status.ts, tenant-create.ts, tenant-drop.ts
+const { config, migrationsFolder, tenantDiscovery, migrationsTable } = await loadConfig(options.config);
+
+const migrator = createMigrator(config, {
+  migrationsFolder: folder,
+  tenantDiscovery: discoveryFn,
+  migrationsTable, // NOVO - passa undefined se não configurado (usa default)
+});
+```
+
+#### 3. Atualizar tipos
+
+```typescript
+// types.ts ou onde apropriado
+interface MigrationsConfig {
+  tenantFolder: string;
+  tenantDiscovery: () => Promise<string[]>;
+  migrationsTable?: string; // NOVO
+}
+```
+
+### Exemplo de Uso
+
+```typescript
+// tenant.config.ts
+export default {
+  ...config,
+  migrations: {
+    tenantFolder: "./drizzle/tenant",
+    tenantDiscovery: discoverTenants,
+    migrationsTable: "__drizzle_tenant_migrations", // NOVO - usa tabela customizada
+  },
+};
+```
+
+### Compatibilidade
+
+- **Backward compatible**: Se não configurado, usa `__drizzle_migrations` (comportamento atual)
+- **Migration path**: Projetos existentes podem:
+  1. Configurar a tabela antiga na config
+  2. Ou renomear a tabela no banco para o novo padrão
+
+### Checklist
+
+- [x] Atualizar `loadConfig` para extrair `migrationsTable`
+- [x] Atualizar `migrate` command
+- [x] Atualizar `status` command
+- [x] Atualizar `tenant:create` command
+- [x] Atualizar `tenant:drop` command
+- [x] Adicionar teste unitário
+- [x] Atualizar README com exemplo
+- [x] ~~Publicar v1.0.4~~ (incluído em v1.0.3)
 
 ---