Skip to content
QueryPilotDocs

Contributing

QueryPilot will be released as open source under the Apache License 2.0. Contributions (bug reports, documentation and code) will be welcome.

Repository layout

Section titled “Repository layout”
apps/
  agent/      telemetry collector that runs next to the observed database
  api/        NestJS API
  web/        Next.js web app
  worker/     background job runner
packages/
  config/     configuration schema and loading
  database/   TypeORM entities, migrations, seed
  plans/      EXPLAIN parser, fingerprint, annotation, comparison
  postgres/   connections and capability detection
  query/      SQL normalization and fingerprinting
  shared/     logger, errors, crypto, health server
  telemetry/  agent <-> API protocol
  types/      shared domain types
infrastructure/
  docker/     Dockerfiles for every app
  postgres/   init scripts for the bundled PostgreSQL
  prometheus/ scrape configuration for the observability profile
plan-docs/    product and technical design documents
docs/         operator documentation
site/         this website

Development environment

Section titled “Development environment”

Requirements: Node.js 20.11+, pnpm 9.15 and Docker.

Terminal window
pnpm install
cp .env.example .env          # set QUERYPILOT_ENCRYPTION_KEY (openssl rand -base64 32)
pnpm dev:setup                # PostgreSQL in Docker, build, migrate, seed
pnpm dev                      # API, worker and web in watch mode

Checks

Section titled “Checks”

CI runs the following on every push and pull request. Run them locally before opening a PR:

Terminal window
pnpm lint
pnpm typecheck
pnpm test
pnpm build

CI also applies all migrations to a clean PostgreSQL 16 database, applies them a second time to prove they are idempotent, and verifies that the schema matches the entities (a pending generated migration fails the build).

Database changes

Section titled “Database changes”

Entities live in packages/database/src/entities. After changing one, generate a migration and commit it with the change:

Terminal window
pnpm db:generate
pnpm db:migrate

Commit messages

Section titled “Commit messages”

The history uses Conventional Commits with a scope:

feat(agent): scheduler, bounded buffer and resilient transport
feat(plans): EXPLAIN parser, structural fingerprint, annotation and comparison
chore: ignore local Plans directory

Principles

Section titled “Principles”

A few rules shape almost every review:

  • The observed database is sacred. Anything that runs against it is read-only, bounded, and timeout-protected. A monitoring query must never become the slow query.
  • Honest data. Never fabricate telemetry. Gaps are gaps, not zeroes; estimates are labelled as estimates.
  • Degrade, don’t fail. A missing permission or extension disables one feature and says why.
  • Everything optional stays optional. QueryPilot must be fully functional with no AI, no exporters and no cloud account.
  • Deterministic first. Analysis is rule-based and reproducible; AI may only explain it.