temp-table-pg

Infraestrutura estruturada para criação e gerenciamento de tabelas temporárias (TEMP / UNLOGGED) no PostgreSQL usando Node.js.

Projetado para relatórios complexos, pipelines de dados e workloads administrativos com necessidade de performance previsível e isolamento por sessão.

---

🚀 Objetivo

Fornecer uma camada organizada para:

• Materialização de datasets intermediários
• Criação dinâmica de índices
• Execução transacional isolada
• Limpeza automática de tabelas temporárias
• Observabilidade via hooks

---

📦 Instalação

npm install temp-table-pg

Requer:

npm install pg

---

🧠 Arquitetura

O módulo é composto por:

1️⃣ TempSession

Gerencia:

• Conexão (pg PoolClient)
• Transações (BEGIN, COMMIT, ROLLBACK)
• Execução de queries
• Encerramento com limpeza automática

2️⃣ TempTable

Representa uma tabela temporária criada no banco. Permite:

• Criar a partir de query
• Criar índices
• Executar ANALYZE
• Contar registros
• Dropar tabela

3️⃣ TempTableBuilder

Builder fluente para configurar criação de tabelas.

4️⃣ TempTableRegistry

Mantém controle interno das tabelas criadas na sessão.

5️⃣ Errors

Erros customizados para falhas estruturadas.

---

🔄 Fluxo Básico

const { Pool } = require('pg');
const { createSession, createBuilder } = require('temp-table-pg');

const pool = new Pool({ /* config */ });

async function run() {
  const session = createSession(pool);

  await session.runInTransaction(async (tx) => {

    const table = await createBuilder(tx)
      .from('SELECT generate_series(1, 1000) AS number')
      .addIndex('number')
      .build();

    const result = await tx.query(
      `SELECT COUNT(*)::int AS total FROM ${table.name}`
    );

    console.log(result.rows[0].total);
  });

  await pool.end();
}

---

⚙️ Estratégias de Tabela

Estratégia	Descrição
TEMP	Tabela temporária por sessão
UNLOGGED	Sem WAL, mais rápida para escrita

---

📊 Hooks (Observabilidade)

Você pode monitorar:

const session = createSession(pool, {
  hooks: {
    onQuery: ({ sql, duration, rowCount }) => {},
    onCreateTable: ({ name, duration }) => {},
    onIndex: ({ table, columns }) => {}
  }
});

---

🔹 Importando

import {
  TempSession,
  TempTable,
  TempTableBuilder,
  TempTableRegistry,
  errors
} from 'temp_table_pg';

---

🔹 Exemplo de uso completo

import { Pool } from 'pg';
import { TempSession, TempTableBuilder } from 'temp_table_pg';

// 1. Cria pool do PostgreSQL
const pool = new Pool({
  user: 'postgres',
  host: 'localhost',
  database: 'mydb',
  password: 'password',
  port: 5432,
});

async function run() {
  // 2. Cria uma sessão temporária
  const session = new TempSession(pool, {
    id: 'report_session',
    autoRollbackOnError: true,
    hooks: {
      onQuery: ({ sql, duration, rowCount }) => {
        console.log(`Executed: ${sql} (${rowCount} rows in ${duration}ms)`);
      },
    },
  });

  // 3. Executa tudo dentro de uma transação
  await session.runInTransaction(async (sess) => {

    // 4. Cria tabela temporária a partir de SELECT
    const ordersTable = await TempTable.fromQuery(sess, `SELECT * FROM orders WHERE created_at > now() - interval '30 days'`);

    // 5. Cria índices para otimizar consultas
    await ordersTable.createIndex(['customer_id']);
    await ordersTable.createIndex(['status']);

    // 6. Analisa a tabela para estatísticas
    await ordersTable.analyze();

    // 7. Consulta todos os registros
    const rows = await ordersTable.selectAll();
    console.log(`Found ${rows.length} recent orders.`);

    // 8. Usando TempTableBuilder para criar tabela com índices e análise automática
    const recentOrdersBuilder = new TempTableBuilder(sess)
      .from(`SELECT * FROM orders WHERE total > 100`)  // base query
      .addIndex('customer_id')                        // índice
      .addIndex(['status', 'created_at'])            // índice composto
      .analyze();                                   // habilita ANALYZE

    const highValueOrders = await recentOrdersBuilder.build();

    // Consulta dados
    const highRows = await highValueOrders.selectAll();
    console.log(`High value orders: ${highRows.length}`);

    // 9. Drop manual se necessário (normalmente será feito automaticamente ao finalizar a sessão)
    await highValueOrders.drop();
  });

  // 10. Finaliza sessão, dropando todas tabelas temporárias criadas
  await session.end();
}

run().catch(console.error);

---

🔹 Funcionalidades principais

• Criação de tabelas temporárias (TEMP ou UNLOGGED).
• Criação de índices simples ou compostos, inclusive CONCURRENTLY (fora de transação).
• Analise automática (ANALYZE) para otimização de consultas.
• Sessão com transações seguras (runInTransaction).
• Registro central de tabelas temporárias (TempTableRegistry).
• Hooks para monitoramento de queries, criação de tabelas e índices.
• Erros especializados para facilitar debugging (TempTableError, UnsafeIdentifierError, etc.).

---

🔹 Casos de uso

• Relatórios temporários e agregações de dados.
• ETL em memória usando tabelas temporárias.
• Testes automatizados com tabelas temporárias isoladas.
• Dashboards dinâmicos com dados filtrados e agregados.

---

🔹 Erros mais comuns

• SessionNotStartedError - quando tenta usar a sessão antes de start().
• TransactionStateError - operação inválida dentro/fora de transação.
• InvalidTableDefinitionError - tabela temporária mal definida.
• TableNotFoundError - tabela não registrada.
• UnsafeIdentifierError - coluna ou tabela com nome inseguro.

---

📈 Benefícios Técnicos

• Materialização de joins pesados
• Índices intermediários
• Redução de recalculo
• Execução previsível
• Debug facilitado
• Isolamento por requisição

---

🛡 Segurança

• Validação básica de identificadores SQL
• Use sempre parâmetros ($1, $2, ...)
• Nunca injete entrada do usuário diretamente em SQL

---

🎯 Quando Usar

Ideal para:

• Relatórios administrativos
• Exportações grandes (CSV)
• BI interno
• Sistemas com filtros dinâmicos

Evite para:

• CRUD simples
• Queries triviais

---

🧪 Desenvolvimento

Build:

npm run build

Test:

node test.js

---

🏗 Extensões Futuras

• Telemetria estruturada
• Sanitização avançada
• Estratégia automática baseada em volume
• Exportadores integrados
• Suporte a particionamento temporário

---

📄 Licença

MIT