Noções Básicas de Onboarding

10 exemplos para onboarding no primeiro dia: PostgreSQL 18.4 local, psql, hábito de EXPLAIN, e política de acesso de produção somente leitura - para que um novo colega envie um PR de query seguro antes do final da primeira semana.

Pré-requisitos

Clone o repositório da plataforma ou aplicação e confirme o contrato da stack.

git clone git@github.com:your-org/your-app.git
cd your-app
cat CONTRIBUTING.md | grep -i postgres

Stack local alvo:

# docker-compose.yml (trecho)
services:
  postgres:
    image: postgres:18.4
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app_dev
    ports: ["5432:5432"]

Exemplos Básicos

1. Iniciar Postgres Local

docker compose up -d postgres
docker compose ps
psql "postgresql://app:app@localhost:5432/app_dev" -c "SELECT version();"

Espere PostgreSQL 18.4 na saída
Corrija conflitos de porta com ss -tlnp | grep 5432 antes de alterar as portas do compose

2. Essenciais do psql

psql "postgresql://app:app@localhost:5432/app_dev"

\conninfo
\dt app.*
\d+ orders
\q

\d+ mostra índices e constraints antes de escrever migrações
Veja Noções Básicas de psql

3. Executar Migrações Localmente

flyway -url=jdbc:postgresql://localhost:5432/app_dev \
  -user=app -password=app migrate

SELECT version, description, success
FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 3;

Caminho de comando igual ao do job de staging da CI
Nunca edite arquivos de migração mesclados; adicione novas versões para frente

4. Hábito de EXPLAIN (Primeiro PR)

EXPLAIN (ANALYZE, BUFFERS)
SELECT id FROM orders WHERE tenant_id = $1 AND status = 'open' LIMIT 50;

Anexe a saída ao PR antes de solicitar revisão
Staging é obrigatório antes de produção; tabelas locais vazias mentem sobre os planos

Relacionado: Noções Básicas de EXPLAIN

5. Política de Produção Somente Leitura

## Acesso à Produção (semana 2+)
- Função: app_readonly (apenas SELECT)
- Colega necessário nas primeiras 5 sessões
- Sem DDL, sem pg_terminate_backend
- Use apenas VPN de bastião + psql (sem modo de escrita GUI)

-- Verifica a função
SELECT current_user, rolsuper, rolcreatedb FROM pg_roles WHERE rolname = current_user;

6. Dados de Exemplo para Planos Realistas

psql "$LOCAL_URL" -f db/seeds/dev_fixtures.sql
ANALYZE;

Mínimo de 10.000 linhas nas tabelas que você consulta em PRs
Copie um snapshot de estatísticas sanitizado do staging se a equipe fornecer

7. Encontrar Mapa da Documentação

docs/
├── database/
│   ├── CONTRIBUTING-db.md
│   └── runbooks/
site/postgresql/   # guias internos de SME

Marque Noções Básicas de Migrações e Revisão de Código para SQL

Exemplos Intermediários

8. Checklist do Colega na Primeira Semana

Dia 1: postgres local + psql + primeira tabela \d
Dia 2: flyway migrate + SELECT somente leitura no staging
Dia 3: EXPLAIN em PR de amostra com comentário do colega
Dia 4: walkthrough do script de bundle de incidentes (somente leitura)
Dia 5: shadow no plantão para alerta não-SEV1

9. Primeira Contribuição Segura

-- Bom primeiro PR: adicionar índice parcial com CONCURRENTLY no staging
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_open_tenant
  ON orders (tenant_id) WHERE status = 'open';

Emparelhe com a saída do Skill de Segurança de Migração no PR

10. Caminho de Escalada

Query lenta da aplicação → EXPLAIN → #database Slack → rotação de DBA
SEV1 banco de dados → PagerDuty → canal de incidentes → Skill de Triagem de Incidentes
Dúvida sobre design de schema → horário de atendimento terça-feira 10:00

FAQs

A versão do Postgres local deve ser 18.4?

Corresponda ao major.minor da equipe quando possível. Local 18.x contra staging 18.4 é aceitável; evite local PG 16 contra staging 18 para testes de migração.

Ferramentas GUI no primeiro dia?

psql na primeira semana. pgAdmin/DBeaver somente leitura após a sessão com o colega. Escreva DDL apenas através de migrações git.

Quando obter acesso de escrita ao staging?

Após o primeiro PR de migração revisado e treinamento flyway, geralmente na semana 2-3. Escrita em produção é apenas para a função de plantão.

Relacionados

Caminho de Desenvolvedor de Aplicação → DBA - progressão de carreira
Matriz de Habilidades - níveis de competência
Melhores Práticas de Equipe e Onboarding - resumo de 25 itens
Noções Básicas de psql - fluxos de trabalho do cliente
Noções Básicas de Git para Trabalho com Banco de Dados - fluxo git de migração

Versões da Stack: Esta página foi escrita para PostgreSQL 18.4, Flyway 10+, e desenvolvimento local com Docker Compose.

Noções Básicas de Onboarding

Pré-requisitos

Clone o repositório da plataforma ou aplicação e confirme o contrato da stack.

git clone git@github.com:your-org/your-app.git
cd your-app
cat CONTRIBUTING.md | grep -i postgres

Stack local alvo:

# docker-compose.yml (trecho)
services:
  postgres:
    image: postgres:18.4
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app_dev
    ports: ["5432:5432"]

Exemplos Básicos

1. Iniciar Postgres Local

docker compose up -d postgres
docker compose ps
psql "postgresql://app:app@localhost:5432/app_dev" -c "SELECT version();"

Espere PostgreSQL 18.4 na saída
Corrija conflitos de porta com ss -tlnp | grep 5432 antes de alterar as portas do compose

2. Essenciais do psql

psql "postgresql://app:app@localhost:5432/app_dev"

\conninfo
\dt app.*
\d+ orders
\q

\d+ mostra índices e constraints antes de escrever migrações
Veja Noções Básicas de psql

3. Executar Migrações Localmente

flyway -url=jdbc:postgresql://localhost:5432/app_dev \
  -user=app -password=app migrate

SELECT version, description, success
FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 3;

Caminho de comando igual ao do job de staging da CI
Nunca edite arquivos de migração mesclados; adicione novas versões para frente

4. Hábito de EXPLAIN (Primeiro PR)

EXPLAIN (ANALYZE, BUFFERS)
SELECT id FROM orders WHERE tenant_id = $1 AND status = 'open' LIMIT 50;

Anexe a saída ao PR antes de solicitar revisão
Staging é obrigatório antes de produção; tabelas locais vazias mentem sobre os planos

Relacionado: Noções Básicas de EXPLAIN

5. Política de Produção Somente Leitura

## Acesso à Produção (semana 2+)
- Função: app_readonly (apenas SELECT)
- Colega necessário nas primeiras 5 sessões
- Sem DDL, sem pg_terminate_backend
- Use apenas VPN de bastião + psql (sem modo de escrita GUI)

-- Verifica a função
SELECT current_user, rolsuper, rolcreatedb FROM pg_roles WHERE rolname = current_user;

6. Dados de Exemplo para Planos Realistas

psql "$LOCAL_URL" -f db/seeds/dev_fixtures.sql
ANALYZE;

Mínimo de 10.000 linhas nas tabelas que você consulta em PRs
Copie um snapshot de estatísticas sanitizado do staging se a equipe fornecer

7. Encontrar Mapa da Documentação

docs/
├── database/
│   ├── CONTRIBUTING-db.md
│   └── runbooks/
site/postgresql/   # guias internos de SME

Marque Noções Básicas de Migrações e Revisão de Código para SQL

Exemplos Intermediários

8. Checklist do Colega na Primeira Semana

Dia 1: postgres local + psql + primeira tabela \d
Dia 2: flyway migrate + SELECT somente leitura no staging
Dia 3: EXPLAIN em PR de amostra com comentário do colega
Dia 4: walkthrough do script de bundle de incidentes (somente leitura)
Dia 5: shadow no plantão para alerta não-SEV1

9. Primeira Contribuição Segura

-- Bom primeiro PR: adicionar índice parcial com CONCURRENTLY no staging
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_open_tenant
  ON orders (tenant_id) WHERE status = 'open';

Emparelhe com a saída do Skill de Segurança de Migração no PR

10. Caminho de Escalada

Query lenta da aplicação → EXPLAIN → #database Slack → rotação de DBA
SEV1 banco de dados → PagerDuty → canal de incidentes → Skill de Triagem de Incidentes
Dúvida sobre design de schema → horário de atendimento terça-feira 10:00

FAQs

A versão do Postgres local deve ser 18.4?

Corresponda ao major.minor da equipe quando possível. Local 18.x contra staging 18.4 é aceitável; evite local PG 16 contra staging 18 para testes de migração.

Ferramentas GUI no primeiro dia?

psql na primeira semana. pgAdmin/DBeaver somente leitura após a sessão com o colega. Escreva DDL apenas através de migrações git.

Quando obter acesso de escrita ao staging?

Após o primeiro PR de migração revisado e treinamento flyway, geralmente na semana 2-3. Escrita em produção é apenas para a função de plantão.

Relacionados

Caminho de Desenvolvedor de Aplicação → DBA - progressão de carreira
Matriz de Habilidades - níveis de competência
Melhores Práticas de Equipe e Onboarding - resumo de 25 itens
Noções Básicas de psql - fluxos de trabalho do cliente
Noções Básicas de Git para Trabalho com Banco de Dados - fluxo git de migração

Versões da Stack: Esta página foi escrita para PostgreSQL 18.4, Flyway 10+, e desenvolvimento local com Docker Compose.

Noções Básicas de Onboarding

Buscar na documentação

Noções Básicas de Onboarding