Digite para filtrar os verbetes do Glossário.

    Banco de dados · Vibe Coding: Do Zero ao MVP

    O que é upsert?

    O upsert insere um registro ou atualiza o existente pela correspondência definida. No PostgreSQL, ON CONFLICT usa a unicidade para identificar esse caso.

    Também chamado de: insert or update

    StayCloudVPS Agêntica

    O mesmo ambiente do SetupVibe, agora numa VPS

    Os atalhos, o shell e as CLIs de IA que você já usa no computador rodam numa VPS da StayCloud com servidor no Brasil.

    Criar minha VPS na StayCloud

    Link de parceiro da Promovaweb.

    Black Friday até 30/11

    30%off

    nos 2 primeiros meses do plano mensal da VPS

    • Backup diário grátis para sempre
    • Servidores em São Paulo no datacenter da Ascenty
    • Datacenter Tier III manutenção sem parada
    • Acesso root com disco SSD NVMe
    • Réplica do backup em Ashburn, nos EUA

    Inserção com atualização do registro existente

    O upsert é uma gravação que insere um registro novo ou atualiza um registro existente conforme uma correspondência definida. O nome reúne update e insert. A sintaxe varia entre bancos e interfaces, por isso é preciso saber como cada implementação identifica o registro que será atualizado.

    No PostgreSQL, o comando INSERT ... ON CONFLICT DO UPDATE usa um conflito de unicidade para escolher a atualização. Quando a inserção tenta repetir uma chave que deveria ser única, o banco executa a alteração especificada em DO UPDATE sobre a linha existente.

    Atualizar a descrição de um código

    Neste exemplo didático, a tabela produtos tem uma chave primária em codigo e uma coluna de texto chamada descricao. O comando envia o código 42 com uma nova descrição:

    INSERT INTO produtos (codigo, descricao)
    VALUES (42, 'Teclado USB')
    ON CONFLICT (codigo)
    DO UPDATE SET descricao = EXCLUDED.descricao
    RETURNING codigo, descricao;

    Se o código 42 ainda não existir, o banco insere a linha. Caso exista, a cláusula SET atualiza sua descrição com o valor proposto pela inserção, disponível em EXCLUDED.descricao. A cláusula RETURNING devolve o código e a descrição da linha inserida ou atualizada para você conferir o resultado.

    O conflito tratado tem um alvo específico

    Esse comando exige uma restrição de unicidade compatível com codigo. Sem ela, o PostgreSQL não consegue usar a coluna como alvo do conflito. Uma violação diferente, como a ausência de um campo obrigatório, ainda pode causar erro: o upsert não transforma qualquer falha de inserção em atualização.

    O PostgreSQL executa essa alternativa entre inserir e atualizar de forma atômica, inclusive com gravações concorrentes, desde que não ocorra outro erro. Isso evita separar a consulta de existência da gravação, mas você ainda precisa definir quais colunas podem mudar e conceder as permissões exigidas pelo comando.

    Dúvidas frequentes

    Perguntas frequentes sobre upsert

    Upsert substitui a linha inteira?
    As colunas alteradas dependem da implementação. No PostgreSQL, a cláusula DO UPDATE SET especifica o que será atualizado na linha existente. Uma coluna omitida dessa cláusula não é substituída por ela.
    Qual chave o PostgreSQL usa para identificar o conflito?
    O comando precisa indicar o alvo de ON CONFLICT DO UPDATE, por colunas de um índice único compatível ou pelo nome de uma restrição de unicidade. A chave primária pode cumprir essa função.
    A permissão de inserir é suficiente?
    O comando com DO UPDATE também exige UPDATE nas colunas alteradas. As colunas lidas pelo comando exigem SELECT, inclusive as usadas para identificar o conflito ou devolver o resultado.

    Para continuar

    Recursos relacionados

    Aplicação na formação

    Vibe Coding: Do Zero ao MVP

    Ao revisar uma gravação criada com agentes, você precisa testar o cadastro de um código novo e a atualização de um código existente para conferir quais campos mudam.

    Conhecer a formação
    Capa da Formação Vibe Coding do Zero ao MVP

    Fontes consultadas

    Referências deste verbete

    Este verbete ajudou você?

    Planos Promovaweb

    Tire seus projetos do papel

    O Plano Martech cobre automação e atendimento. O Plano IA Makers acrescenta desenvolvimento com IA, enquanto o Plano Founders trata de gestão de negócios. Todos são anuais.

    Plano Martech

    Para conectar automação, marketing e atendimento com infraestrutura própria.

    R$ 897

    R$ 597/ano

    • Grade de automação, atendimento, marketing e análise de indicadores
    • Instalador Exclusivo Promovaweb
    • n8n, Evolution API, Chatwoot e Mautic
    • Trilha DevOps incluída
    • Encontros ao vivo (terça e quinta)
    • Comunidade e acompanhamento
    Conhecer o plano

    Plano Founders

    Plano anual para fazer um projeto de tecnologia avançar, com 90 dias de mentoria intensiva. R$ 1.997 à vista ou até 10x de R$ 219 no cartão.

    R$ 1.997/ano

    • 12 meses de acesso ao Founders
    • 90 dias de mentoria intensiva, um encontro por dia útil
    • Dia de conteúdo (terça e quinta) e War Room (segunda, quarta e sexta)
    • Encontro semanal em grupo após a fase intensiva
    • Formação Vibe Coding incluída no plano anual
    • Consultoria individual de até duas horas (bônus)
    Conhecer o plano