CRUD no PostgreSQL com SQL e RETURNING

CRUD também aparece no banco relacional: create, read, update e delete correspondem a inserir, ler, atualizar e remover linhas. Nesta aula, você vai realizar o ciclo de um pedido e usar RETURNING como prova. O hábito central é consultar o alvo antes de executar uma mudança ampla.

Pense num sistema de estoque. Dar entrada, consultar, corrigir e retirar um item são ações diferentes, e cada comprovante precisa identificar o registro. No SQL, o comando escolhe a ação e WHERE escolhe as linhas. A analogia termina aí: uma única instrução pode afetar milhares de linhas, e o banco não pergunta “tem certeza?” quando o comando é válido e autorizado.

Insira uma linha e capture o identificador

INSERT INTO pedidos (cliente_id, status, total_centavos)
VALUES (12, 'pendente', 8990)
RETURNING id, status, total_centavos;

O banco valida tipos e restrições antes de confirmar. Guardar dinheiro em centavos como inteiro evita parte das surpresas de ponto flutuante; outra opção adequada é numeric com escala definida. Nunca use um tipo por aparência: a escolha precisa preservar as operações do domínio.

Na aplicação, valores enviados pelo usuário devem usar parâmetros. A ideia é:

INSERT INTO pedidos (cliente_id, status, total_centavos)
VALUES ($1, $2, $3)
RETURNING id;

O driver transmite valores separadamente do texto SQL. Concatenar entrada em uma string abre espaço para SQL injection e problemas de conversão. Os marcadores variam conforme o driver, mas o princípio permanece.

Leia antes de atualizar

Use a chave e o estado esperado:

SELECT id, status, total_centavos
FROM pedidos
WHERE id = 101;

UPDATE pedidos
SET status = 'pago'
WHERE id = 101 AND status = 'pendente'
RETURNING id, status;

Se outra ação já cancelou o pedido, o UPDATE retorna zero linhas. Isso é diferente de erro de conexão. O estado no WHERE torna a pré-condição parte da escrita e reduz atualizações silenciosas sobre dados que mudaram.

Para alterar várias linhas, UPDATE continua sendo o comando, mas o filtro deve expressar uma regra coletiva, como pedidos vencidos antes de uma data. Primeiro faça um SELECT com o mesmo WHERE, conte e examine uma amostra.

Uma leitura seguida de escrita também pode enfrentar concorrência. Colocar o estado esperado no próprio WHERE transforma a verificação em parte do UPDATE. Quando várias tabelas precisam mudar como uma unidade, use uma transação e trate falhas com rollback. Isso não substitui a escolha do nível de isolamento, mas evita confirmar metade de um fluxo.

Remova somente quando a regra pedir remoção

DELETE FROM pedidos
WHERE id = 101 AND status = 'cancelado'
RETURNING id, status;

Sem WHERE, UPDATE altera todas as linhas e DELETE remove todas. Esse é o erro controlado desta aula. Em um banco descartável, comece uma transação, execute UPDATE pedidos SET status = 'pago';, veja a contagem e use ROLLBACK. Você reproduz o alcance sem preservar o dano. Nunca faça esse ensaio em dados reais.

Arquivamento pode ser mais apropriado que exclusão quando há histórico fiscal, financeiro ou de atendimento. Acrescentar apagado_em muda a consulta: toda leitura ativa precisa filtrar o estado. Essa decisão deve ser explícita, não um atalho automático chamado “soft delete”.

O laboratório é um simulador de SELECT básico sobre JSON local. Ele não executa INSERT, UPDATE, DELETE, parâmetros, restrições ou transações e não é um servidor PostgreSQL. Consulte pendentes e espere duas linhas. Depois filtre por id = 103 e espere uma antes de escrever o UPDATE real no papel.

Sua missão é executar o ciclo completo num banco de prática e registrar as linhas devolvidas por RETURNING. Se alguma etapa devolver zero, explique se o filtro não encontrou a linha ou se o estado esperado mudou. Na próxima aula, vamos construir leituras mais precisas com filtros, ordem e limite.