PowerSync - Comandos Docker¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-06

Documentação dos comandos para operar o Docker Compose do PowerSync no servidor.

Runbook (volumes, restart seguro, down -v): Fase 5 — migration-phase5-powersync-runbook.md.

Localização (um Compose por cliente)¶

Cada cliente tem a sua pasta no repositório, com docker-compose.yaml e config.yaml juntos — por exemplo:

powersync/sulplata/
powersync/onpetrotrading/
powersync/vantroba/
powersync/onpetro/

No servidor, faz-se cd para a pasta desse cliente (clone do mono-repo ou cópia só dessa pasta) e usa-se docker compose aí dentro. Visão geral: Fase 5 — migration-phase5-powersync-runbook.md.

Exemplo:

cd /caminho/do/repo/powersync/sulplata

Docker Compose v2 (plugin)¶

A partir do Docker Compose v2, o comando é o subcomando do Docker CLI: com espaço — docker compose — e não o binário legado docker-compose (hífen, v1).

Para conferir a instalação:

docker compose version

O arquivo de definição neste projeto continua sendo docker-compose.yaml (nome convencional; em outros projetos também se usa compose.yaml).

PostgreSQL: replicação lógica, role e publicação¶

Antes de subir o PowerSync, cada banco usado pelo integrador (ex.: integracao_sulplata, vantroba, onpetro, …) precisa estar preparado para replicação lógica. O PowerSync lê o WAL do Postgres e exige publicação nomeada powersync e um usuário com privilégio de replicação e SELECT nas tabelas publicadas.

Documentação oficial (inglês): Source Database Setup — Postgres.

1. Habilitar replicação lógica (`wal_level`)¶

O tipo de WAL deve ser logical (não apenas replica).

SHOW wal_level;

Se não for logical, como superusuário:

ALTER SYSTEM SET wal_level = logical;

Reinicie o PostgreSQL para aplicar. Em instalações próprias, isso costuma estar em postgresql.conf como wal_level = logical.

Ajuste também limites se tiver muitas instâncias PowerSync (cada uma usa slots de replicação), por exemplo em postgresql.conf ou via ALTER SYSTEM:

max_wal_senders = 10
max_replication_slots = 10

(Valores mínimos dependem de quantos serviços PowerSync e slots ativos existem; monitore com os comandos da documentação de manutenção.)

2. `pg_hba.conf`: permitir o host do PowerSync¶

O container do PowerSync acessa o Postgres pelo IP do host (no compose atual costuma ser algo como 172.17.0.1 apontando para a porta do servidor). Inclua regras que permitam conexões desse host até o banco, com o usuário do PowerSync (ex.: powersync_role), usando o método de autenticação que você usa (ex.: scram-sha-256).

Exemplo (ajuste IP/rede e o nome do usuário):

host    all    powersync_role    172.17.0.0/16    scram-sha-256

Recarregue o Postgres (pg_ctl reload ou SELECT pg_reload_conf();) após alterar o pg_hba.conf.

3. Role do PowerSync e permissões (cluster + por banco)¶

O usuário (powersync_role ou outro nome alinhado ao config.yaml) costuma ser criado uma vez no cluster. Em cada database onde existir uma instância PowerSync, conceda CONNECT, permissões no schema e a publicação.

Uma vez no cluster (como superusuário, ex.: postgres):

CREATE ROLE powersync_role WITH REPLICATION BYPASSRLS LOGIN PASSWORD 'defina_uma_senha_forte';

Em cada database do integrador (repita trocando nome_do_banco; URI típica no YAML: postgresql://powersync_role:...@172.17.0.1:32123/nome_do_banco):

GRANT CONNECT ON DATABASE nome_do_banco TO powersync_role;

\c nome_do_banco

GRANT USAGE ON SCHEMA public TO powersync_role;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO powersync_role;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO powersync_role;

Se preferir restringir leitura e publicação só a tabelas específicas (recomendável com muitos dados), liste explicitamente as tabelas no GRANT SELECT e na publicação (próximo passo), como na documentação do PowerSync.

4. Publicação `powersync` (obrigatório o nome)¶

A publicação deve se chamar powersync.

Opção simples (todas as tabelas do schema; bom para dev ou bases pequenas):

CREATE PUBLICATION powersync FOR ALL TABLES;

Opção enxuta (ex.: só pAbast, alinhado aos sync rules iniciais):

CREATE PUBLICATION powersync FOR TABLE pabast_empresa, pabast_senhas;

Nota: o serviço PowerSync processa as alterações das tabelas presentes na publicação, mesmo que o config.yaml filtre no sync rules — por isso, em produção com volume grande, prefira publicar só o necessário.

Para alterar uma publicação existente: ALTER PUBLICATION ... ADD/DROP TABLE ... (veja documentação PostgreSQL).

5. Um banco por cliente¶

Repita os passos 3 e 4 em cada database usado por uma instância PowerSync (ex.: Sul Plata, On Petro Trading, Vantroba, On Petro), pois publicação e role são por database.

6. Replica identity (DELETE/UPDATE com publicação lógica)¶

Se uma tabela entra na publicação powersync e o Postgres replica DELETE (e UPDATE), o servidor precisa saber qual linha foi afetada ao escrever no WAL. Sem isso, ocorre erro ao excluir/atualizar, por exemplo:

cannot delete from table "faturamento" because it does not have a replica identity and publishes deletes
HINT: To enable deleting from the table, set REPLICA IDENTITY using ALTER TABLE.

Tabelas com PRIMARY KEY (ou índice único adequado) costumam usar a identidade padrão (DEFAULT = usar a PK) e raramente precisam de ajuste.
Tabelas sem chave primária (como faturamento / movimento no BI Vantroba) precisam de replica identity explícita.

Opção usual para tabelas sem PK (envia a linha inteira no WAL em UPDATE/DELETE; mais volume de WAL, mas simples):

-- Exemplo: banco vantroba, tabelas BI sem PK
ALTER TABLE faturamento REPLICA IDENTITY FULL;
ALTER TABLE movimento REPLICA IDENTITY FULL;

Alternativa melhor em médio prazo: criar uma chave primária (ou índice único) e deixar o padrão REPLICA IDENTITY DEFAULT, que usa esse índice — menos WAL que FULL.

Documentação PostgreSQL: Replica Identity.

Comandos Principais¶

Iniciar os containers¶

Iniciar todos os serviços em background (detached mode):

docker compose up -d

Iniciar e ver os logs em tempo real:

docker compose up

Parar os containers¶

Parar todos os serviços:

docker compose down

Parar e remover volumes (⚠️ CUIDADO: Remove dados do MongoDB):

docker compose down -v

Ver os logs¶

Ver logs de todos os serviços:

docker compose logs

Ver logs em tempo real (follow):

docker compose logs -f

Ver logs de um serviço específico:

docker compose logs powersync
docker compose logs mongo

Ver últimas N linhas de log:

docker compose logs --tail=100

Ver logs em tempo real do PowerSync:

docker compose logs -f powersync

Status dos containers¶

Ver status de todos os containers:

docker compose ps

Ver todos os containers (incluindo parados):

docker compose ps -a

Reiniciar serviços¶

Reiniciar todos os serviços:

docker compose restart

Reiniciar só o PowerSync (após mudar config.yaml):

docker compose restart powersync

Recriar containers¶

Recriar containers (útil após mudanças no docker-compose.yaml):

docker compose up -d --force-recreate

Atualizar imagens¶

Atualizar as imagens Docker e recriar containers:

docker compose pull
docker compose up -d

Comandos Úteis¶

Ver uso de recursos¶

docker stats

Entrar em um container¶

docker compose exec powersync sh
docker compose exec mongo mongosh

Limpar logs antigos¶

# Limpar logs de todos os containers
docker compose logs --tail=0

Verificar saúde dos serviços¶

# Verificar se os serviços estão rodando
docker compose ps

# Verificar logs de erro
docker compose logs | grep -i error

Serviços em cada pasta de cliente¶

Em cada powersync/<cliente>/docker-compose.yaml:

powersync — serviço PowerSync (porta interna 8080).
mongo — MongoDB (replica set; porta 27017 só na rede Compose).
mongo-rs-init — job one-shot que faz rs.initiate no Mongo.

Portas e HTTPS¶

Dentro do container PowerSync: 8080 (também em config.yaml: port: 8080).
Host: o Compose publica 8080:8080. Um projeto Coolify por cliente costuma expor 8080 ao proxy; subdomínios sugeridos: ps.sulplata.xadm.biz, ps.vantroba.xadm.biz, etc. — ver Fase 5.

Os config.yaml em powersync/<cliente>/config.yaml versionam placeholders na URI Postgres; no servidor, preencher com credenciais reais (sem commitar segredos). Alinhar host/porta/banco com o Postgres de cada cliente.

JWT / JWKS: o integrador não expõe JWKS para o PowerSync. O modelo no repo usa https://auth.xadm.biz/.well-known/jwks.json — verificar o path real no serviço de auth. Contexto: docs/dev/pabast-removal-phase1.md.

Troubleshooting¶

PostgreSQL: `does not have a replica identity and publishes deletes`¶

Tabelas na publicação lógica sem PK precisam de REPLICA IDENTITY — ver a seção «6. Replica identity» acima. Rode os ALTER TABLE ... REPLICA IDENTITY FULL (ou adicione PK) no mesmo database onde está a tabela.

Container não inicia¶

# Ver logs detalhados
docker compose logs [nome-do-servico]

# Verificar configuração
docker compose config

Container reinicia constantemente¶

# Ver logs para identificar o erro
docker compose logs -f [nome-do-servico]

# Verificar status
docker compose ps

Limpar tudo e recomeçar¶

⚠️ ATENÇÃO: Isso remove todos os dados do MongoDB!

docker compose down -v
docker compose up -d