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.

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 });

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