Depois de entender o que é SQL e aprender a criar tabelas robustas com o CREATE TABLE, o próximo passo lógico é dar vida ao nosso banco de dados. Afinal, uma estrutura sem dados é apenas um esqueleto vazio.

Hoje vamos falar sobre o comando INSERT. No dia a dia de dados e DevOps, inserir registros vai muito além de preencher um formulário simples; envolve automação, ingestão de dados em lote (bulk insert) e garantia de que a operação não vai falhar caso um dado duplicado apareça.

Vamos ver como o PostgreSQL lida com isso de forma eficiente.

A Sintaxe Básica do INSERT

A estrutura padrão do comando exige que você informe o nome da tabela, as colunas que deseja preencher e, em seguida, os valores correspondentes.

INSERT INTO nome_da_tabela (coluna1, coluna2, coluna3)
VALUES (valor1, valor2, valor3);

Exemplos Práticos no PostgreSQL

Para os nossos exemplos, vamos imaginar uma tabela de logs de deploy ou eventos de infraestrutura, bem comum em cenários de automação e DevOps.

1. Inserindo um Registro Único

Se você precisa salvar apenas um evento que acabou de acontecer:

INSERT INTO eventos_infra (nome_servico, tipo_evento, criticidade)
VALUES ('api-gateway', 'restart_pod', 'alta');

Nota: Se a tabela tiver colunas com valores padrões (DEFAULT) ou IDs auto-incrementáveis (SERIAL), você não precisa listá-las no comando. O Postgres resolve isso sozinho.

2. Inserindo Múltiplos Registros (Bulk Insert)

Fazer um comando INSERT para cada linha é um erro grave de performance que sobrecarrega a rede e o banco. Se você está criando um script (em Python, por exemplo) para parsear logs e salvar no banco, envie vários registros de uma só vez separados por vírgula:

INSERT INTO eventos_infra (nome_servico, tipo_evento, criticidade)
VALUES 
('auth-service', 'login_timeout', 'media'),
('payment-api', 'db_connection_error', 'critica'),
('frontend-web', 'page_not_found', 'baixa');

3. O Recurso Secreto do Postgres: RETURNING

Em outros bancos de dados, após inserir um registro, você precisa fazer uma nova consulta para descobrir qual foi o ID gerado para aquela linha. No PostgreSQL, você pode resolver isso em uma única operação usando a cláusula RETURNING:

INSERT INTO eventos_infra (nome_servico, tipo_evento)
VALUES ('worker-queue', 'queue_cleared')
RETURNING id, criado_em;

Boas Práticas e Cuidados em Produção

1. Sempre Liste as Colunas Explicitamente

O SQL permite que você faça um insert omitindo o nome das colunas, passando apenas os valores na ordem exata da tabela (ex: INSERT INTO tabela VALUES (1, 'nome', 'ativo')). Evite isso a todo custo. Se no futuro você ou sua equipe rodarem um ALTER TABLE para adicionar uma coluna no meio da tabela, todos os seus scripts de insert antigos vão quebrar imediatamente.

2. Previna Erros com o UPSERT (ON CONFLICT)

Imagine que seu pipeline de dados tenta inserir um servidor que já está cadastrado. Em vez de estourar um erro de chave duplicada e quebrar o script, o Postgres permite que você trate o conflito de forma elegante.

• Ignorar se já existir:

INSERT INTO servidores (ip_codigo, nome)
VALUES ('192.168.1.50', 'staging-api')
ON CONFLICT (ip_codigo) DO NOTHING;

• Atualizar se já existir (O verdadeiro Upsert):

INSERT INTO servidores (ip_codigo, nome, status)
VALUES ('192.168.1.50', 'staging-api', 'ativo')
ON CONFLICT (ip_codigo) 
DO UPDATE SET status = EXCLUDED.status;

3. Cuidado com Transações Grandes

Se for inserir milhares de linhas de uma vez através de um script de migração ou automação de CI/CD, envolva a operação em uma transação (BEGIN; ... COMMIT;). Isso garante que ou todos os dados entram com sucesso, ou nada entra, evitando que o banco fique em um estado parcialmente corrompido caso a conexão caia no meio do processo.

Conclusão

O comando INSERT é a porta de entrada dos dados no seu ecossistema. Dominar variações como o multi-row insert, o uso do RETURNING e a cláusula ON CONFLICT diferencia quem apenas “escreve código” de quem realmente projeta sistemas resilientes e de alta performance.

No próximo post, vamos falar sobre como extrair inteligência desses dados usando o comando mais utilizado do SQL: o SELECT.

Você já conhecia a cláusula RETURNING do PostgreSQL ou ainda faz duas consultas na aplicação para pegar o ID inserido? Deixe seu comentário aqui embaixo!