PostgreSQL

PostgreSQL é o banco relacional principal da Veloz. Vem com PgBouncer opcional, túnel local seguro e variáveis de ambiente injetadas nos seus serviços.

Tamanhos

O tamanho padrão é essencial.

Nota: o PostgreSQL também pode rodar no tier compartilhado gerenciado, com backups automáticos, recuperação para um ponto no tempo (PITR) e armazenamento gerenciado (sem dimensionar storage). Bancos existentes podem ser migrados pelo dashboard. Veja tier compartilhado.

Criar via CLI

# Mais simples
veloz db create --name postgres --engine postgresql
 
# Com versão, storage e PgBouncer
veloz db create --name postgres --engine postgresql --version 16 --storage 20Gi --size essencial --pooler

Criar via veloz.json

{
  "databases": {
    "postgres": {
      "engine": "postgresql",
      "version": "16",
      "storage": "20Gi",
      "size": "essencial",
      "pooler": {
        "enabled": true,
        "poolMode": "transaction",
        "defaultPoolSize": 20,
        "maxClientConn": 100
      }
    }
  }
}

Ao rodar veloz deploy, o banco é criado se não existir, ou atualizado se a config mudou.

PgBouncer (Connection Pooler)

PgBouncer roda como sidecar junto ao PostgreSQL. Use sempre que sua aplicação abre/fecha muitas conexões (Lambda-style, serverless, escala horizontal).

Modos disponíveis:

• transaction (recomendado), conexão é devolvida ao pool após cada transação
• session, conexão é mantida durante toda a sessão do cliente
• statement, conexão é devolvida após cada statement (não suporta transações multi-statement)

Quando o pooler está ativo, duas connection strings são expostas:

• POSTGRES_POOLER_URL, use para queries (porta 6432)
• POSTGRES_DATABASE_URL, use para migrations e LISTEN/NOTIFY (conexão direta na porta 5432)

Uso com Prisma

datasource db {
  provider  = "postgresql"
  url       = env("POSTGRES_POOLER_URL")    // pooled, para queries
  directUrl = env("POSTGRES_DATABASE_URL")  // direto, para migrations
}

Importante: o directUrl é necessário porque prisma migrate usa locks que o pooler em modo transaction não suporta. Sem ele, suas migrations vão travar.

Uso com Drizzle

// queries via pooler
const queryClient = postgres(process.env.POSTGRES_POOLER_URL);
 
// migrations conexão direta
const migrationClient = postgres(process.env.POSTGRES_DATABASE_URL, { max: 1 });

Réplica de leitura

No tier compartilhado, todo banco PostgreSQL roda com uma segunda instância que recebe uma cópia contínua dos dados. Ela já existia para garantir alta disponibilidade, e agora você também pode enviar consultas para ela.

O ganho é tirar leitura pesada da instância principal: relatórios, exportações, dashboards internos e páginas de listagem deixam de competir com as escritas do seu app. Não é preciso ativar nada, e as credenciais são as mesmas.

Variáveis injetadas

Como usar

Prisma, com um segundo client só para leitura:

const db = new PrismaClient();
const dbRead = new PrismaClient({
  datasources: { db: { url: process.env.POSTGRES_READ_URL } },
});
 
await db.pedido.create({ data: pedido });        // escrita, principal
await dbRead.pedido.findMany({ where: { ... } }); // leitura, réplica

Drizzle ou pg:

const readPool = new Pool({ connectionString: process.env.POSTGRES_READ_URL });

Se o seu app abre muitas conexões de leitura (várias instâncias, picos de tráfego), troque por POSTGRES_READ_POOLER_URL. Ele funciona em modo transaction, então com Prisma acrescente ?pgbouncer=true ao final da URL.

Três coisas para saber antes

A réplica fica um instante atrás. A cópia é assíncrona: em repouso o atraso é de poucos milissegundos, mas cresce quando há muita escrita. Uma leitura feita logo depois de uma escrita pode não enxergar essa escrita ainda. Se a consulta precisa do dado recém-gravado, use a conexão principal.

Escritas são recusadas. INSERT, UPDATE, DELETE e migrations falham nessa conexão com cannot execute … in a read-only transaction. Isso é proposital, e vale inclusive para frameworks que criam tabelas sozinhos no boot.

Consultas muito longas podem ser interrompidas. Para manter a réplica em dia com a principal, o banco pode cancelar uma leitura que fica travando a sincronização por tempo demais. Consultas analíticas longas ficam mais seguras na conexão principal, ou com retry no seu lado.

{NOME}_ANY_URL

Distribui as conexões entre a instância principal e a réplica, alternadamente. Serve para espalhar leitura por toda a capacidade disponível, mas metade das conexões cai na principal, então não isola carga e continua sujeita ao mesmo atraso. É read-only como as demais. Na dúvida, use {NOME}_READ_URL.

Tier dedicado: essas variáveis não são injetadas. Um banco dedicado roda em uma única instância, então não existe réplica para consultar. Migre para o tier compartilhado pelo dashboard para ganhar réplica de leitura, backups automáticos e PITR.

Acesso local

Túnel para GUI (DBeaver, pgAdmin, TablePlus)

# Abre na porta 5432 local
veloz db tunnel postgres
 
# Porta customizada
veloz db tunnel postgres --port 5433

Em outra aba, conecte com qualquer client:

psql postgresql://user:[email protected]:5432/veloz

As credenciais aparecem em veloz db credentials postgres.

Query rápida

# Interativo (abre prompt)
veloz db query postgres
 
# Inline
veloz db query postgres -q "SELECT count(*) FROM users"
veloz db query postgres -q "SELECT * FROM orders ORDER BY created_at DESC LIMIT 10"

Dashboard

Cada banco tem uma seção de Insights no dashboard com métricas (conexões, QPS, latência, memória, disco), SQL Editor com syntax highlighting e Table Explorer para navegar a estrutura sem escrever SQL.

Comandos úteis

veloz db list                       # Listar bancos do projeto
veloz db credentials postgres       # Ver host, porta, usuário, senha
veloz db update postgres --size turbo   # Trocar tier
veloz db restart postgres           # Reiniciar engine
veloz db delete postgres            # Excluir (irreversível)

Próximos passos

• Bancos de Dados, conceitos comuns (env vars, status, deploy update)
• MySQL e Redis, outras opções gerenciadas
• Variáveis de Ambiente, interpolação e composição de URLs