development.md

Development

Prerequisites

• Rust 1.92+
• Docker & Docker Compose
• PostgreSQL 17+ with pgvector (or use Docker)

Setup

docker compose up -d          # start postgres + redis
make env-setup                # create .env
make build
make run

Migrations

Migrations run automatically on startup. To add new ones:

# Create migration
touch migrations/NNN_description.sql

# Update SQLx cache
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/waypoint
cargo sqlx prepare

Backfill

# Local
make backfill-queue
make backfill-worker

# Docker (scales to 4 workers)
docker compose --profile backfill up --scale backfill-worker=4

Worker flags:

• --exit-on-complete - exit when done
• --idle-timeout <secs> - wait time before exit (default: 30)

Metrics

make metrics-start
./run-with-metrics.sh make backfill-worker
make metrics-open              # opens Grafana
make metrics-stop

Testing

make test
cargo test test_name

Formatting

make fmt