Pular para conteúdo

POSTGRESQL INSERT - Inserir Registro

O que é este Node?

O POSTGRESQL INSERT é o node responsável por inserir novos registros em tabelas PostgreSQL de forma segura usando prepared statements.

Por que este Node existe?

Inserir dados é operação fundamental em bancos de dados. O POSTGRESQL INSERT existe para:

  1. Segurança: Usa prepared statements prevenindo SQL injection
  2. Simplicidade: Interface estruturada sem escrever SQL manualmente
  3. Auto-commit: Commit automático da transação
  4. RETURNING: Retorna registro inserido com valores gerados (id, timestamps)
  5. Validação: Valida campos antes de executar
  6. Performance: Otimizado para inserções únicas

Como funciona internamente?

Quando o POSTGRESQL INSERT é executado, o sistema:

  1. Valida config: Verifica credenciais PostgreSQL
  2. Substitui variáveis: Troca {{variavel}} por valores do contexto em values
  3. Monta SQL: Cria INSERT com placeholders ($1, $2, ...) seguros
  4. Executa: Envia para PostgreSQL com valores parametrizados
  5. Retorna: Devolve registro inserido (com ID gerado) e rowCount
  6. Fecha conexão: Encerra pool
  7. Se erro: Lança exceção (constraint violation, tipo inválido, etc.)

Código interno (postgresql.executor.ts:104-124): 

private async insertRow(
  pool: Pool,
  table: string,
  fields: string[],
  values: Record<string, any>,
  context: ExecutionContext,
): Promise<any> {
  const replacedValues = this.replaceObjectVariables(values, context.variables);

  const columns = Object.keys(replacedValues).join(', ');
  const placeholders = Object.keys(replacedValues).map((_, i) => `$${i + 1}`).join(', ');
  const valueArray = Object.values(replacedValues);

  const query = `INSERT INTO ${table} (${columns}) VALUES (${placeholders}) RETURNING *`;
  const result = await pool.query(query, valueArray);

  return {
    insertedRow: result.rows[0],
    rowCount: result.rowCount,
  };
}

Quando você DEVE usar este Node?

Use POSTGRESQL INSERT quando precisar inserir registros estruturados:

Casos de uso

  1. Cadastro de usuário: "Salvar dados de novo cliente"
  2. Registro de pedido: "Criar novo pedido no sistema"
  3. Log de evento: "Gravar ação do usuário"
  4. Criação de produto: "Adicionar produto ao catálogo"
  5. Inserção simples: "Adicionar linha única em tabela"

Quando NÃO usar POSTGRESQL INSERT

  • Query complexa: Use POSTGRESQL EXECUTEQUERY para INSERT com subconsultas
  • Múltiplas inserções: Execute múltiplos nodes ou use EXECUTEQUERY com VALUES múltiplos
  • Insert ou Update: Use POSTGRESQL INSERTORUPDATE (upsert)
  • Condicional: Se precisa verificar existência antes, use INSERTORUPDATE

Parâmetros Detalhados

config (object, obrigatório)

O que é: Configuração de conexão com PostgreSQL.

Estrutura: 

{
  "host": "localhost",
  "port": 5432,
  "database": "nome_database",
  "user": "usuario",
  "password": "senha",
  "ssl": false
}

table (string, obrigatório)

O que é: Nome da tabela onde será inserido o registro.

Formato: Nome válido de tabela PostgreSQL (sem schema usa public)

Com schema: Use "schema_name.table_name" se tabela está em schema específico

values (object, obrigatório)

O que é: Objeto com pares campo: valor a serem inseridos.

Formato: { "campo1": "valor1", "campo2": 123, "campo3": true }

Suporte a variáveis: Use {{variavel}} para valores dinâmicos

Flow completo para testar:

{
  "name": "Teste PostgreSQL - Insert",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Qual seu nome completo?",
          "variable": "nome"
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Seu email:",
          "variable": "email"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "message": "Seu telefone:",
          "variable": "telefone"
        }
      }
    },
    {
      "id": "postgres_1",
      "type": "postgresql",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Salvar Cliente",
        "parameters": {
          "operation": "insert",
          "config": {
            "host": "localhost",
            "port": 5432,
            "database": "crm",
            "user": "app_user",
            "password": "secure_password",
            "ssl": false
          },
          "table": "clientes",
          "values": {
            "nome": "{{nome}}",
            "email": "{{email}}",
            "telefone": "{{telefone}}",
            "data_cadastro": "NOW()",
            "ativo": true
          },
          "responseVariable": "clienteInserido"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "Cliente cadastrado com sucesso!\n\nID: {{clienteInserido.insertedRow.id}}\nNome: {{nome}}\nEmail: {{email}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "email_1" },
    { "source": "email_1", "target": "phone_1" },
    { "source": "phone_1", "target": "postgres_1" },
    { "source": "postgres_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Registro é inserido e ID gerado é retornado.

responseVariable (string, opcional)

O que é: Nome da variável para armazenar resultado no contexto.

Conteúdo: Objeto com insertedRow (registro completo inserido) e rowCount

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Deve ser "insert"
config object Sim Configuração de conexão PostgreSQL
config.host string Sim Endereço do servidor PostgreSQL
config.port number Não Porta (padrão: 5432)
config.database string Sim Nome do database
config.user string Sim Usuário PostgreSQL
config.password string Sim Senha do usuário
config.ssl boolean Não Usar SSL (padrão: false)
table string Sim Nome da tabela
values object Sim Pares campo:valor a inserir
responseVariable string Não Variável para armazenar resultado

Exemplo 1: Cadastro Completo de Cliente

Objetivo: Coletar dados do cliente e inserir no banco

JSON para Importar

{
  "name": "PostgreSQL - Cadastro Cliente",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Boas-vindas",
        "parameters": {
          "message": "Bem-vindo ao cadastro de clientes! Vamos coletar seus dados."
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Nome completo:",
          "variable": "nome"
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Email:",
          "variable": "email"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "message": "Telefone:",
          "variable": "telefone"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Cidade",
        "parameters": {
          "message": "Cidade:",
          "variable": "cidade"
        }
      }
    },
    {
      "id": "postgres_1",
      "type": "postgresql",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Salvar no DB",
        "parameters": {
          "operation": "insert",
          "config": {
            "host": "localhost",
            "port": 5432,
            "database": "crm",
            "user": "app_user",
            "password": "secure_password",
            "ssl": false
          },
          "table": "clientes",
          "values": {
            "nome": "{{nome}}",
            "email": "{{email}}",
            "telefone": "{{telefone}}",
            "cidade": "{{cidade}}",
            "data_cadastro": "CURRENT_TIMESTAMP",
            "origem": "whatsapp",
            "ativo": true
          },
          "responseVariable": "resultado"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1500, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "Cadastro realizado com sucesso!\n\nID: {{resultado.insertedRow.id}}\nNome: {{nome}}\nEmail: {{email}}\nTelefone: {{telefone}}\nCidade: {{cidade}}\n\nObrigado pelo cadastro!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "input_1" },
    { "source": "input_1", "target": "email_1" },
    { "source": "email_1", "target": "phone_1" },
    { "source": "phone_1", "target": "input_2" },
    { "source": "input_2", "target": "postgres_1" },
    { "source": "postgres_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Bem-vindo ao cadastro de clientes! Vamos coletar seus dados.
Sistema: Nome completo:
Usuário: José Roberto Silva
Sistema: Email:
Usuário: jose@example.com
Sistema: Telefone:
Usuário: 11987654321
Sistema: Cidade:
Usuário: São Paulo
Sistema: Cadastro realizado com sucesso!

ID: 42
Nome: José Roberto Silva
Email: jose@example.com
Telefone: 11987654321
Cidade: São Paulo

Obrigado pelo cadastro!

Exemplo 2: Registro de Pedido

Objetivo: Criar pedido vinculado a cliente existente

JSON para Importar

{
  "name": "PostgreSQL - Criar Pedido",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "ID Cliente",
        "parameters": {
          "message": "ID do cliente:",
          "variable": "clienteId"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Produto",
        "parameters": {
          "message": "Nome do produto:",
          "variable": "produto"
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Quantidade",
        "parameters": {
          "message": "Quantidade:",
          "variable": "quantidade",
          "min": 1
        }
      }
    },
    {
      "id": "number_2",
      "type": "number",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Valor Unitário",
        "parameters": {
          "message": "Valor unitário (R$):",
          "variable": "valorUnitario",
          "decimals": 2,
          "min": 0.01
        }
      }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Calcular Total",
        "parameters": {
          "assignments": [
            {
              "variable": "valorTotal",
              "value": "{{quantidade}} * {{valorUnitario}}"
            }
          ]
        }
      }
    },
    {
      "id": "postgres_1",
      "type": "postgresql",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Inserir Pedido",
        "parameters": {
          "operation": "insert",
          "config": {
            "host": "localhost",
            "port": 5432,
            "database": "ecommerce",
            "user": "app_user",
            "password": "secure_password",
            "ssl": false
          },
          "table": "pedidos",
          "values": {
            "cliente_id": "{{clienteId}}",
            "produto": "{{produto}}",
            "quantidade": "{{quantidade}}",
            "valor_unitario": "{{valorUnitario}}",
            "valor_total": "{{valorTotal}}",
            "status": "pendente",
            "data_pedido": "CURRENT_TIMESTAMP"
          },
          "responseVariable": "pedido"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1500, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "Pedido criado com sucesso!\n\nNúmero do Pedido: {{pedido.insertedRow.id}}\nProduto: {{produto}}\nQuantidade: {{quantidade}}\nValor Total: R$ {{valorTotal}}\nStatus: Pendente"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "input_2" },
    { "source": "input_2", "target": "number_1" },
    { "source": "number_1", "target": "number_2" },
    { "source": "number_2", "target": "variable_1" },
    { "source": "variable_1", "target": "postgres_1" },
    { "source": "postgres_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ID do cliente:
Usuário: 42
Sistema: Nome do produto:
Usuário: Notebook Dell
Sistema: Quantidade:
Usuário: 2
Sistema: Valor unitário (R$):
Usuário: 2500.00
Sistema: Pedido criado com sucesso!

Número do Pedido: 15
Produto: Notebook Dell
Quantidade: 2
Valor Total: R$ 5000.00
Status: Pendente

Resposta do Node

{
  "insertedRow": {
    "id": 42,
    "nome": "José Roberto Silva",
    "email": "jose@example.com",
    "telefone": "11987654321",
    "cidade": "São Paulo",
    "data_cadastro": "2025-01-15T14:30:00.000Z",
    "origem": "whatsapp",
    "ativo": true
  },
  "rowCount": 1
}

Boas Práticas

✅ SIM:

  • Use prepared statements (implementado automaticamente)
  • Valide dados antes de inserir
  • Trate campos obrigatórios (NOT NULL)
  • Use DEFAULT no banco para timestamps
  • Capture ID gerado em responseVariable
  • Verifique unicidade antes (email, CPF, etc.) com query prévia

❌ NÃO:

  • Não insira sem validar formato (email, telefone, CPF)
  • Não ignore constraints do banco
  • Não use INSERT para atualizar (use UPDATE ou UPSERT)
  • Não insira dados sensíveis sem criptografia
  • Não ignore valores de retorno (ID gerado)

Dicas

💡 RETURNING: PostgreSQL retorna registro completo com valores gerados (id, timestamps, defaults)

💡 SERIAL/IDENTITY: Não inclua campo auto-increment em values (banco gera automaticamente)

💡 Timestamps: Use CURRENT_TIMESTAMP ou NOW() para data/hora atual

💡 JSON: PostgreSQL suporta tipo jsonb para campos com estrutura flexível

💡 Arrays: Use ARRAY['val1', 'val2'] para campos tipo array

💡 Constraints: Trate erros de UNIQUE, FOREIGN KEY e CHECK constraints

💡 Bulk Insert: Para múltiplos registros, use EXECUTEQUERY com múltiplos VALUES

Próximo Node

→ POSTGRESQL UPDATE - Atualizar registros → POSTGRESQL DELETE - Deletar registros → POSTGRESQL INSERTORUPDATE - Upsert (Insert ou Update) → POSTGRESQL EXECUTEQUERY - Consultas personalizadas