Onboarding Basics

10 examples for day-one onboarding: local PostgreSQL 18.4, psql, EXPLAIN habit, and read-only prod access policy - so a new teammate ships a safe query PR before end of week one.

Prerequisites

Clone the platform or application repo and confirm stack contract.

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

Target local stack:

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

Basic Examples

1. Start Local Postgres

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

Expect PostgreSQL 18.4 in output
Fix port conflicts with ss -tlnp | grep 5432 before changing compose ports

2. psql Essentials

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

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

\d+ shows indexes and constraints before writing migrations
See psql Basics

3. Run Migrations Locally

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;

Same command path as CI staging job
Never edit merged migration files; add new version forward

4. EXPLAIN Habit (First PR)

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

Attach output to PR before requesting review
Staging required before prod; local empty tables lie about plans

Related: EXPLAIN Basics

5. Read-Only Prod Policy

## Production access (week 2+)
- Role: app_readonly (SELECT only)
- Buddy required first 5 sessions
- No DDL, no pg_terminate_backend
- Use bastion VPN + psql only (no GUI write mode)

-- Verify role
SELECT current_user, rolsuper, rolcreatedb FROM pg_roles WHERE rolname = current_user;

6. Seed Data for Realistic Plans

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

10k+ rows minimum on tables you query in PRs
Copy sanitized stats snapshot from staging if team provides

7. Find Documentation Map

docs/
├── database/
│   ├── CONTRIBUTING-db.md
│   └── runbooks/
site/postgresql/   # internal SME guides

Bookmark Migrations Basics and Code Review for SQL

Intermediate Examples

8. Buddy Checklist Week One

Day 1: local postgres + psql + first \d table
Day 2: flyway migrate + read-only staging SELECT
Day 3: EXPLAIN on sample PR with buddy comment
Day 4: incident bundle script walkthrough (read-only)
Day 5: shadow on-call for non-SEV1 alert

9. First Safe Contribution

-- Good first PR: add partial index with CONCURRENTLY on staging
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_open_tenant
  ON orders (tenant_id) WHERE status = 'open';

Pair with Migration Safety Skill output in PR

10. Escalation Path

App query slow → EXPLAIN → #database Slack → DBA rotation
SEV1 database → PagerDuty → incident channel → Incident Triage Skill
Schema design question → office hours Tuesday 10:00

FAQs

Local Postgres version must be 18.4?

Match team major.minor when possible. 18.x local against 18.4 staging is acceptable; avoid PG 16 local against 18 staging for migration testing.

GUI tools day one?

psql first week. pgAdmin/DBeaver read-only after buddy session. Write DDL only through git migrations.

When get write staging access?

After first reviewed migration PR and flyway training, usually week 2-3. Prod write is on-call role only.

App Dev → DBA Path - career progression
Skills Matrix - competency levels
Team & Onboarding Best Practices - 25-item summary
psql Basics - client workflows
Git for Database Work Basics - migration git flow

Stack versions: This page was written for PostgreSQL 18.4, Flyway 10+, and Docker Compose local development.

Onboarding Basics

10 examples for day-one onboarding: local PostgreSQL 18.4, psql, EXPLAIN habit, and read-only prod access policy - so a new teammate ships a safe query PR before end of week one.

Prerequisites

Clone the platform or application repo and confirm stack contract.

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

Target local stack:

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

Basic Examples

1. Start Local Postgres

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

Expect PostgreSQL 18.4 in output
Fix port conflicts with ss -tlnp | grep 5432 before changing compose ports

2. psql Essentials

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

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

\d+ shows indexes and constraints before writing migrations
See psql Basics

3. Run Migrations Locally

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;

Same command path as CI staging job
Never edit merged migration files; add new version forward

4. EXPLAIN Habit (First PR)

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

Attach output to PR before requesting review
Staging required before prod; local empty tables lie about plans

Related: EXPLAIN Basics

5. Read-Only Prod Policy

## Production access (week 2+)
- Role: app_readonly (SELECT only)
- Buddy required first 5 sessions
- No DDL, no pg_terminate_backend
- Use bastion VPN + psql only (no GUI write mode)

-- Verify role
SELECT current_user, rolsuper, rolcreatedb FROM pg_roles WHERE rolname = current_user;

6. Seed Data for Realistic Plans

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

10k+ rows minimum on tables you query in PRs
Copy sanitized stats snapshot from staging if team provides

7. Find Documentation Map

docs/
├── database/
│   ├── CONTRIBUTING-db.md
│   └── runbooks/
site/postgresql/   # internal SME guides

Bookmark Migrations Basics and Code Review for SQL

Intermediate Examples

8. Buddy Checklist Week One

Day 1: local postgres + psql + first \d table
Day 2: flyway migrate + read-only staging SELECT
Day 3: EXPLAIN on sample PR with buddy comment
Day 4: incident bundle script walkthrough (read-only)
Day 5: shadow on-call for non-SEV1 alert

9. First Safe Contribution

-- Good first PR: add partial index with CONCURRENTLY on staging
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_open_tenant
  ON orders (tenant_id) WHERE status = 'open';

Pair with Migration Safety Skill output in PR

10. Escalation Path

App query slow → EXPLAIN → #database Slack → DBA rotation
SEV1 database → PagerDuty → incident channel → Incident Triage Skill
Schema design question → office hours Tuesday 10:00

FAQs

Local Postgres version must be 18.4?

Match team major.minor when possible. 18.x local against 18.4 staging is acceptable; avoid PG 16 local against 18 staging for migration testing.

GUI tools day one?

psql first week. pgAdmin/DBeaver read-only after buddy session. Write DDL only through git migrations.

When get write staging access?

After first reviewed migration PR and flyway training, usually week 2-3. Prod write is on-call role only.

App Dev → DBA Path - career progression
Skills Matrix - competency levels
Team & Onboarding Best Practices - 25-item summary
psql Basics - client workflows
Git for Database Work Basics - migration git flow

Stack versions: This page was written for PostgreSQL 18.4, Flyway 10+, and Docker Compose local development.

Onboarding Basics

Search Documentation

Onboarding Basics