Usando RETURNING pra pegar dados depois de inserir/atualizar

Hoje a gente vai adicionar mais uma parada mágica no nosso conhecimento: o comando RETURNING. Ele é uma ferramenta poderosa que deixa você pegar na hora os dados que precisa depois de inserir, atualizar ou deletar. Imagina só: você insere uma linha na tabela e já recebe o identificador único dela. Prático, né? Bora aprender!

Depois de fazer um INSERT, UPDATE ou DELETE, às vezes você precisa pegar logo os dados que foram afetados. Por exemplo, depois de inserir uma nova linha na tabela, você quer saber qual foi a chave primária (identificador único) criada automaticamente. Ao invés de mandar outra consulta só pra pegar esse dado, dá pra fazer tudo de uma vez usando o RETURNING.

Imagina que você tá adicionando um novo estudante na tabela students. Cada estudante tem um identificador único (tipo, student_id) que é gerado automaticamente. Depois de adicionar o estudante, você já quer usar esse id pra registrar o estudante em algum curso. Sem o RETURNING, você teria que primeiro adicionar o estudante, depois fazer um SELECT separado pra achar o id dele. Com o RETURNING, tudo rola numa consulta só!

Sintaxe do comando RETURNING

O comando RETURNING vai no final das operações INSERT, UPDATE e DELETE. Olha só a sintaxe geral:

-- Sintaxe do INSERT:
INSERT INTO tabela (coluna1, coluna2, ...)
VALUES (valor1, valor2, ...)
RETURNING coluna;

-- Sintaxe do UPDATE:
UPDATE tabela
SET coluna1 = valor1
WHERE condição
RETURNING coluna;

-- Sintaxe do DELETE:
DELETE FROM tabela
WHERE condição
RETURNING coluna;

Com o RETURNING você escolhe quais colunas das linhas alteradas quer receber de volta. Pode ser só uma coluna (tipo a chave primária) ou várias colunas de uma vez.

Usando RETURNING com INSERT

Vamos ver um exemplo com a tabela students:

CREATE TABLE students (
    student_id SERIAL PRIMARY KEY,
    first_name TEXT NOT NULL,
    last_name TEXT NOT NULL,
    email TEXT UNIQUE
);

Vamos adicionar um novo estudante e já pegar o id dele:

INSERT INTO students (first_name, last_name, email)
VALUES ('Otto', 'Lin', 'otto.lin@example.com')
RETURNING student_id;

A consulta vai retornar o id do estudante que acabou de ser adicionado:

Você acabou de adicionar o estudante Otto Lin, e o PostgreSQL já te mandou o student_id dele. Prático demais, né?

Agora bora inserir e pegar várias colunas de uma vez. Se você quiser não só o student_id, mas também o nome e sobrenome do estudante, é só pedir pelo RETURNING:

INSERT INTO students (first_name, last_name, email)
VALUES ('Alex', 'Ming', 'alex.ming@example.com')
RETURNING student_id, first_name, last_name;

Resultado:

Usando RETURNING com UPDATE

Às vezes, depois de atualizar os dados, você quer saber exatamente quais linhas foram alteradas. O RETURNING resolve isso de boa.

Imagina que o estudante Otto Lin resolveu trocar o email dele. Vamos atualizar e já pegar a info da linha alterada:

UPDATE students
SET email = 'lin.new@example.com'
WHERE student_id = 1
RETURNING student_id, email;

Resultado:

Agora você sabe certinho que o email do estudante com student_id = 1 foi atualizado com sucesso.

Usando RETURNING com DELETE

Quando você deleta registros da tabela, pode ser útil saber quais linhas foram removidas. Com o RETURNING você pega os dados das linhas deletadas.

Por exemplo: imagina que o estudante Peter Ming foi desligado. Vamos remover ele da tabela e pegar as infos da exclusão:

DELETE FROM students
WHERE student_id = 2
RETURNING student_id, first_name, last_name;

Resultado:

Agora você tem certeza que foi o Peter Ming que foi removido.

Dicas práticas

Usa o RETURNING sempre que precisar dos dados das linhas afetadas. Assim você evita consultas extras no banco.

Tenta pedir só o que precisa. Se só precisa da chave primária, pede só ela.

Com transações, o RETURNING fica ainda mais poderoso. Por exemplo, dá pra inserir dados em várias tabelas relacionadas, passando os ids usando o RETURNING.

Erros comuns usando RETURNING

Muita gente que tá começando esquece que o RETURNING só funciona com as linhas que foram realmente alteradas. Tipo, se o UPDATE ou DELETE não achou nenhuma linha, o RETURNING vai devolver vazio. Não se assusta, isso é normal. Só confere se sua consulta tá certa ou trata esse caso no seu código.

Outro erro comum: tentar usar RETURNING pra colunas que não existem. Sempre confere se todas as colunas que você pediu existem na tabela.

Agora você já sabe como o RETURNING pode deixar sua vida com dados muito mais fácil. É uma daquelas ferramentas que você vai curtir muito quando for criar apps de verdade. Bora pra cima!