PostgreSQL 19: o que muda para desenvolvedores de API
Os novos recursos do PostgreSQL 19 que mais importam para desenvolvedores de API: INSERT ... ON CONFLICT DO SELECT para endpoints get-or-create em uma única instrução, WAIT FOR LSN para read-your-writes em réplicas, REPACK (CONCURRENTLY) para limpeza de bloat online, saída JSON do COPY, novos métodos de string do jsonpath e verificações de chave estrangeira mais rápidas em inserções em massa.
Este guia cobre o que muda nos seus handlers, réplicas e plano de upgrade. Todos os exemplos de sintaxe vêm das notas de versão do PostgreSQL 19 e das páginas de referência.
O que há de novo no PostgreSQL 19 em resumo
O PostgreSQL 19 é o lançamento principal anual do banco de dados open source, anunciado pelo PostgreSQL Global Development Group em 19 de novembro de 2026. Ele adiciona inserções get-or-create, esperas em réplicas para read-your-writes, repacking online de tabelas, recomendações de planos e replicação lógica de sequências, além de alterar vários padrões que você deve verificar antes de fazer o upgrade.
| Recurso | O que substitui | Onde você sentirá a diferença |
|---|---|---|
ON CONFLICT DO SELECT | Loops de retry com SELECT e depois INSERT | Endpoints POST idempotentes e de cadastro |
WAIT FOR LSN | Roteamento persistente das leituras para o primário | Réplicas de leitura atrás de uma API |
REPACK (CONCURRENTLY) | VACUUM FULL, CLUSTER, pg_repack | Tabelas quentes com bloat, sem downtime |
COPY ... (FORMAT json) | Conversão de linhas para JSON no código da aplicação | Endpoints de exportação e download em massa |
Métodos de string do jsonpath | Pós-processamento de JSONB no código da aplicação | Filtragem e normalização de colunas JSON |
pg_plan_advice + pg_stash_advice | Reescrever consultas para influenciar o planner | Regressões de plano em produção |
Publicações FOR ALL SEQUENCES | Redefinição manual de sequências após o cutover | Upgrades blue-green via replicação lógica |
O anúncio oficial da versão também menciona vacuum paralelo de índices e workers de I/O assíncrono com dimensionamento automático. Como eles não alteram o SQL que sua API envia, este post não os aborda.
ON CONFLICT DO SELECT: get-or-create em uma única instrução
Toda API tem um endpoint que precisa retornar uma linha, existindo ela ou não: registrar um dispositivo, criar uma tag, iniciar um checkout idempotente. Antes da versão 19, você executava um SELECT e depois um INSERT (e perdia corridas sob carga), ou escrevia um ON CONFLICT DO UPDATE fictício apenas para fazer o RETURNING disparar, o que grava uma nova versão da linha à toa.
O PostgreSQL 19 adiciona uma quarta ação de conflito. A referência do INSERT a chama de "inserção idempotente ou get or create":
INSERT INTO distributors (did, dname) VALUES (11, 'Global Electronics') ON CONFLICT (did) DO SELECT RETURNING *; Se did = 11 estiver livre, a linha é inserida e retornada. Se já estiver ocupada, a linha existente é devolvida e nada é modificado. Três regras da documentação:
- Uma cláusula
RETURNINGé obrigatória comDO SELECT. - Um
conflict_targeté obrigatório, da mesma forma que comDO UPDATE. - Restrições de exclusão não podem atuar como árbitros; use um índice único ou uma restrição unique
NOT DEFERRABLE.
Seu handler geralmente precisa saber qual ramo foi executado, para poder responder com 201 Created ou 200 OK. A documentação observa que os valores antigos do RETURNING são não-NULL quando houve conflito na linha, então uma única coluna informa isso:
INSERT INTO users (email, name) VALUES ($1, $2) ON CONFLICT (email) DO SELECT RETURNING *, (old.id IS NULL) AS created; Precisa bloquear a linha existente antes de mexer em tabelas relacionadas? Adicione uma cláusula de bloqueio: ON CONFLICT (did) DO SELECT FOR UPDATE RETURNING *. Você também pode filtrar com WHERE, por exemplo DO SELECT WHERE d.dname != EXCLUDED.dname, e apenas as linhas que passarem no filtro serão devolvidas.
Privilégios: o DO SELECT requer SELECT na tabela, e as formas FOR UPDATE/FOR SHARE também exigem UPDATE em pelo menos uma coluna.
WAIT FOR LSN: read-your-writes em réplicas
O clássico bug de réplica: um usuário salva o perfil dele, o próximo GET acerta uma réplica assíncrona que ainda não aplicou a alteração, e os dados antigos voltam. A maioria das equipes fixa as leituras no primário após uma escrita, o que desperdiça a réplica.
O PostgreSQL 19 adiciona o comando WAIT FOR. Após uma escrita, capture a posição do WAL do primário:
UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama'; SELECT pg_current_wal_insert_lsn(); -- returns 0/0306EE20 Armazene esse LSN na sessão do usuário (Simon Willison sugere um cookie assinado em seu artigo). Na próxima requisição, execute isto na réplica antes da leitura:
WAIT FOR LSN '0/0306EE20' WITH (TIMEOUT '100ms', NO_THROW); SELECT * FROM movie WHERE genre = 'Drama'; Os detalhes que importam em uma API:
- Modos. O modo padrão
MODE 'standby_replay'espera até que a alteração seja aplicada, que é o que o read-your-writes exige.standby_write,standby_flusheprimary_flushexistem para verificações de durabilidade. - Timeouts. Sem
TIMEOUT, ou comTIMEOUT '0', ele espera para sempre. Sempre defina um nos caminhos de requisição. -
NO_THROW. Sem ele, um timeout gera um erro e aborta sua transação. Com ele, você recebe um status desuccess,timeoutounot in recovery, e pode recorrer ao primário. - Posicionamento. O
WAITdeve ser um comando de nível superior, não dentro de uma função ou blocoDO. Execute-o fora de uma transação ou como primeira instrução, antes de qualquer coisa que adquira um lock, ou ele será rejeitado.
REPACK (CONCURRENTLY) substitui o VACUUM FULL para tabelas em uso
Tabelas atrás de endpoints movimentados, como sessions ou webhook_deliveries, sofrem bloat rápido. VACUUM FULL e CLUSTER resolvem isso, mas travam a tabela. O PostgreSQL 19 adiciona uma opção online:
REPACK (CONCURRENTLY) webhook_deliveries; REPACK (CONCURRENTLY, ANALYZE) orders USING INDEX orders_created_at_idx; As notas de versão dizem que o REPACK (CONCURRENTLY) recupera espaço e pode reordenar uma tabela por um índice sem bloquear leituras ou escritas. VACUUM FULL e CLUSTER permanecem por compatibilidade. Acompanhe o progresso na nova view pg_stat_progress_repack e procure a nova configuração de servidor max_repack_replication_slots ao ajustar o cluster.
Saída JSON do COPY e novos métodos de string do jsonpath
Endpoints de exportação costumam transmitir linhas pelo código da aplicação apenas para transformá-las em JSON. O COPY TO agora pode fazer isso direto no banco, conforme a referência do COPY:
COPY (SELECT * FROM (VALUES(1),(2)) val(id)) TO STDOUT (FORMAT JSON, FORCE_ARRAY); Isso imprime [, {"id":1}, ,{"id":2} e ] em linhas separadas, de modo que a saída é um único array JSON válido. Sem FORCE_ARRAY, você obtém um objeto JSON por linha, o que é compatível com NDJSON. O NULL do SQL vira null do JSON, e o formato json funciona apenas com COPY TO.
Para colunas JSONB, o jsonpath ganha métodos de string: lower(), upper(), initcap(), ltrim(), rtrim(), btrim(), replace() e split_part(). A documentação mostra:
jsonb_path_query('"TOM"', '$.lower()') -- "tom" jsonb_path_query('" hello "', '$.btrim()') -- "hello" jsonb_path_query('"abc,def,ghi,jkl"', '$.split_part(",", 3)') -- "ghi" As notas de versão os marcam como imutáveis, e eles permitem normalizar um campo JSONB (remover espaços, converter para minúsculas, dividir) dentro da própria consulta, em vez de no seu handler.
Além disso, json_array() sobre zero linhas agora retorna [] em vez de NULL, o que pode quebrar um cliente que verifica null.
Outras mudanças do PostgreSQL 19 que equipes de API devem conhecer
- Verificações de chave estrangeira mais rápidas. O anúncio diz que tornaram as inserções em massa quase 2x mais rápidas em testes. Útil para endpoints de importação que gravam linhas filhas.
- Recomendações de plano. A extensão
pg_plan_advicefixa escolhas do planner, e opg_stash_adviceaplica essas recomendações por ID de consulta, permitindo corrigir uma consulta regredida sem redeploy. - UUID e codificação. É possível fazer cast entre
byteaeuuid, eencode()/decode()suportambase64url, o formato seguro para URLs de IDs em paths e tokens. - Replicação lógica para upgrades.
CREATE PUBLICATION all_sequences FOR ALL SEQUENCES;sincroniza sequências, eFOR ALL TABLES EXCEPT (TABLE users, departments)exclui tabelas. Isso fecha a lacuna de "IDs colidem após o cutover" em migrações blue-green.
Mudanças incompatíveis para verificar antes do upgrade
A seção de migração das notas de versão lista mudanças que podem afetar uma API sem que uma única consulta falhe no ambiente de staging:
| Mudança no PostgreSQL 19 | O que verificar |
|---|---|
max_locks_per_transaction padrão de 64 para 128, e configurações existentes devem ser dobradas | Valores personalizados na sua configuração ou no parameter group do serviço gerenciado |
| JIT desabilitado por padrão | Endpoints de analytics que dependiam do JIT para consultas longas |
Compressão TOAST padrão de pglz para lz4 | Nada quebra, mas os perfis de armazenamento e CPU mudam |
standard_conforming_strings forçado para on | Dumps antigos criados com ele em off não serão restaurados |
| Autenticação por senha MD5 gera um warning; RADIUS removido | Migre os roles da aplicação para SCRAM-SHA-256 |
json_array() sobre zero linhas retorna [] | Clientes que testam por null |
READ ONLY repassado ao postgres_fdw | Transações somente leitura que gravavam através de uma tabela externa |
log_lock_waits ativado por padrão | Volume de logs e ruído de alertas |
Fazer upgrade de qualquer versão principal anterior ainda exige pg_upgrade, um dump e restore com pg_dumpall, ou replicação lógica. Planeje a migração agora se você está no PostgreSQL 14: segundo a política de versionamento, seu lançamento final foi em 12 de novembro de 2026.
Deixe seu agente de codificação fazer o teste de regressão da sua API após o upgrade com Apidog CLI
Um upgrade importante do Postgres raramente quebra a sintaxe SQL. Ele quebra o comportamento: um json_array() que retorna [], um limite de locks, um plano mais lento. Detecte isso executando os cenários de teste da sua API contra um banco de dados PostgreSQL 19 de staging, fazendo asserções na resposta HTTP e nas linhas por trás dela. Deixe seu agente de codificação fazer isso com o Apidog CLI.
npm install -g apidog-cli@latest apidog login --with-token <YOUR_TOKEN> npx -y skills add https://apidog.com # pick your agent when prompted Depois, dê ao seu agente um único prompt:
In Apidog project <projectId>, add a test case for POST /users that sends the same email twice and asserts the first call returns 201 and the second returns 200 with the same id. Then run test scenario <scenarioId> against the pg19-staging environment with database assertions, and summarize every failure next to the PostgreSQL 19 change that could explain it. O agente lê o schema do payload, valida-o, cria o caso de teste e executa o cenário com seu arquivo de conexão de banco de dados, para que as etapas de banco acessem o novo cluster:
apidog cli-schema get test-case-create apidog cli-schema validate test-case-create --file case.json apidog test-case create --project <projectId> --file case.json apidog run -t <scenarioId> --project <projectId> -e <envId> \ --database-connection ./database-connections.json -r cli,junit As operações de banco de dados do Apidog suportam PostgreSQL no plano Free, então você pode consultar a tabela após cada requisição e verificar que o endpoint get-or-create gravou exatamente uma linha. A documentação explica consultas de banco de dados em testes de API e como executar cenários com conexões de banco de dados via CLI. Coloque o mesmo comando apidog run ... -r junit no seu pipeline de CI e todos os lançamentos menores seguintes receberão a mesma verificação. Se preferir deixar seu agente consultar o Postgres diretamente, veja o guia do servidor PostgreSQL MCP.
FAQ
Quando o PostgreSQL 19 foi lançado? Em 19 de novembro de 2026. O projeto PostgreSQL suporta cada versão principal por 5 anos, então a versão 19 receberá correções até 19 de novembro de 2031.
O ON CONFLICT DO SELECT é o mesmo que um upsert? Não. O DO UPDATE altera a linha existente; o DO SELECT a retorna sem modificações. Use-o para get-or-create e POSTs idempotentes. Ele exige uma cláusula RETURNING e um conflict target.
O WAIT FOR LSN funciona no primário? O modo padrão standby_replay só funciona em um standby durante a recuperação. Em um primário, você recebe um erro, ou not in recovery com NO_THROW. Use MODE 'primary_flush' se precisar esperar no próprio primário.
Posso fazer upgrade do PostgreSQL 18 para o 19 in place? Sim, com pg_upgrade. Você também pode fazer dump e restore ou usar replicação lógica, que agora replica sequências com FOR ALL SEQUENCES. Revise primeiro a tabela de mudanças incompatíveis acima.
O PostgreSQL 19 substitui o pg_repack? Para a maioria dos casos, sim. O REPACK (CONCURRENTLY) recupera o bloat e reordena tabelas por índice sem bloquear leituras ou escritas, e vem incluído no core.

