pg_durable: execução durável de workflows dentro do PostgreSQL
TL;DR: pg_durable é uma extensão open-source do PostgreSQL que permite executar workflows longos e tolerantes a falhas diretamente no banco, com retries, paralelismo e checkpointing automáticos. Para tarefas fortemente acopladas ao estado do banco (ETL, embeddings, jobs agendados), ele simplifica drasticamente a arquitetura ao eliminar sistemas externos de orquestração. Não substitui Temporal ou Airflow para workflows que cruzam múltiplos serviços, mas preenche uma lacuna crítica no ecossistema de dados.
Por Abe Omorogbe, Senior PM | Pino De Candia, Principal Software Engineer | TJ Green, Principal Software Engineer
Postgres armazena seus dados, executa queries e escala por anos. Mas quando você precisa fazer mais — transformações multi-passo, rollups noturnos, geração de embeddings ou aguardar aprovações — surge um bloqueio: o Postgres não tem uma forma nativa de executar trabalhos de longa duração e tolerantes a falhas.
Foi pensando nisso que a Microsoft criou o pg_durable, uma extensão open-source que traz execução durável diretamente para dentro do banco de dados. Com ela, o Postgres não apenas armazena dados: ele executa workflows longos e tolerantes a falhas, com retries embutidos, paralelismo, agendamento e recuperação. Em vez de costurar funções PL/pgSQL ou construir sistemas externos de orquestração, você define e executa workflows resilientes inteiramente no banco, apoiados pela durabilidade e alta disponibilidade do Postgres.
No Azure HorizonDB, o pg_durable também turbina AI pipelines, permitindo workflows de dados e IA prontos para produção, ponta a ponta, dentro do banco.
Neste artigo abordamos:
- A armadilha oculta do background work bloqueante
- O que é pg_durable e a DSL que o impulsiona
- Como esse motor alimenta AI pipelines no HorizonDB
- Padrões de uso que valem a pena explorar
- Como começar no HorizonDB, no laptop e no VS Code
A armadilha oculta: como o background work bloqueia seu banco?
A maioria dos times de Postgres eventualmente precisa rodar tarefas críticas sobre seus dados: transformações, agregações noturnas, manutenções, jobs de embedding ou processos de negócio multi-passo. A tentação natural é manter esse trabalho dentro do Postgres.
Primeiro: executar a tarefa como uma função dentro do banco — você coloca todo o workflow em uma única função PL/pgSQL: loop, transforma, chama APIs, escreve resultados, retorna. Parece simples até rodar em produção. Uma conexão fica presa o tempo todo. Tudo roda dentro de uma transação gigante, com locks longos e nenhuma visibilidade de progresso parcial. Se a conexão cair ou o banco reiniciar, tudo é perdido. Sem retries por passo, sem paralelismo, sem scheduling, sem pausa para input humano.
Quando falha: você move para fora — o workflow vai para um serviço externo: fila de jobs, workers de polling, tabelas de estado, coordenação de passos, lógica de retry, varreduras de crash-recovery e jobs de limpeza. O que começou como algumas tarefas de fundo vira um sistema distribuído completo. Antes mesmo de tocar na lógica de negócio, você está construindo e operando infraestrutura só para coordenar trabalho que ainda está fundamentalmente atrelado aos seus dados.
Ambos os caminhos são workarounds para a mesma primitiva ausente: trabalho de fundo durável, assíncrono, que vive onde seus dados vivem. Essa é a lacuna que o pg_durable preenche.
O que exatamente é o pg_durable?
pg_durable é uma extensão do Postgres que consiste em uma DSL (linguagem específica de domínio) e o runtime duroxide hospedado em um background worker do Postgres. Você descreve um workflow como uma pequena expressão SQL, chama df.start(...) e recebe um ID de instância imediatamente. O trabalho roda em segundo plano em um background worker, sem nunca bloquear sua conexão ou transação. Você pode verificar o progresso depois com df.status() e df.result(). O estado de execução vive no Postgres, beneficiando-se da durabilidade, HA, backups e recovery do banco. Além disso, a definição do workflow não precisa estar no banco: sua aplicação pode enviá-la para df.start(...) por uma conexão Postgres comum.
Como a execução é assíncrona, o pg_durable quebra automaticamente um workflow em passos discretos. Cada passo roda em sua própria sessão e transação, commitando seu progresso e passando para o próximo — em vez de manter uma transação gigante aberta. Os passos são checkpointed no Postgres e recuperados por replay determinístico, então workflows sobrevivem a crashes, restartes e failovers, retomando exatamente de onde pararam. Se um passo falha, apenas aquele passo é retentado.
Tudo isso é expresso por uma DSL enxuta de operadores combináveis:
| Operador | Significado |
|---|---|
~> |
Sequencial: execute isso, depois aquilo |
& |
Paralelo: fan-out, aguarde todos |
| ` | ` |
?> / !> |
Condicional: if / else |
@> |
Loop: repita de forma durável, sobreviva a restartes |
| ` | =>` |
| Funções Avançadas | |
df.if() |
Ramo condicional |
df.loop() |
Repetir statements |
df.join() |
Executar em paralelo, aguardar todos |
df.http() |
Chamar um endpoint allowlisted |
df.wait_for_schedule() |
Timing estilo cron |
df.wait_for_signal() |
Pausar para um evento externo |
Exemplo prático: Para rodar três agregações em paralelo e depois atualizar um dashboard com retries e crash recovery, você escreve algo como: SELECT df.start('step1 ~> step2 & step3 ~> step4', ...) — e o pg_durable cuida de toda a orquestração, tolerância a falhas e checkpointing automático, eliminando centenas de linhas de código de infraestrutura.
