logo

WhoDB

Integrations

CI/CD Integration

CI/CD Integration

Use CI/CD for repeatable database work. With WhoDB today, the practical paths are:

  • Run clidey/whodb:latest as a temporary web UI for inspecting a test or staging database.
  • Run whodb for scriptable checks such as listing schemas, listing tables, running validation queries, exporting rows, importing CSV or Excel fixtures, and running data-quality audits.
  • Keep migrations, full backups, restores, and large bulk loads in your database-native tooling such as psql, mysql, pg_dump, mysqldump, COPY, or LOAD DATA.

Common Pipeline Patterns

Schema Checks

Apply migrations to a disposable database, then verify the expected tables, columns, and constraints.

Fixture Loading

Use native SQL seed files or whodb import for CSV and Excel fixtures.

Data Validation

Run row counts, orphan checks, and business-rule queries after migrations or imports.

Debug UI

Start the WhoDB web container while reproducing a pipeline failure locally.

GitHub Actions Example

This workflow starts PostgreSQL and WhoDB, applies migrations with psql, checks the WhoDB process health endpoint, and validates the database with SQL.

YAML

name: Database CI

on:
  pull_request:
    paths:
      - "migrations/**"
      - "schema/**"
      - "test/fixtures/**"

jobs:
  postgres:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: app_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

      whodb:
        image: clidey/whodb:latest
        ports:
          - 8080:8080
        env:
          WHODB_POSTGRES: >-
            [{"alias":"ci-postgres","host":"postgres","user":"postgres","password":"postgres","database":"app_test","port":"5432"}]

    steps:
      - uses: actions/checkout@v4

      - name: Install PostgreSQL client
        run: sudo apt-get update && sudo apt-get install -y postgresql-client

      - name: Wait for WhoDB
        run: |
          timeout 60 bash -c 'until curl -fsS http://localhost:8080/health | grep -qx ok; do sleep 2; done'

      - name: Apply migrations
        env:
          PGPASSWORD: postgres
        run: |
          psql -h localhost -U postgres -d app_test -f migrations/001_initial_schema.sql

      - name: Verify schema
        env:
          PGPASSWORD: postgres
        run: |
          psql -h localhost -U postgres -d app_test -c "\dt"
          psql -h localhost -U postgres -d app_test -c "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public';"

      - name: Run application tests
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/app_test
        run: |
          npm ci
          npm run test

Scriptable Checks With whodb

The CLI can read the same environment-defined connection profile format used by the web app.

Bash

export WHODB_POSTGRES_1='{"alias":"ci-postgres","host":"localhost","user":"postgres","password":"postgres","database":"app_test","port":"5432"}'

Use the CLI when you want a WhoDB-flavored command surface in a pipeline:

Bash

# List schemas and tables
npx @clidey/whodb schemas --connection ci-postgres --format json
npx @clidey/whodb tables --connection ci-postgres --schema public --format json

# Run validation SQL
npx @clidey/whodb query "SELECT COUNT(*) FROM users" --connection ci-postgres --format json

# Export a table for artifacts or downstream checks
npx @clidey/whodb export --connection ci-postgres --table users --format csv --output users.csv

# Import CSV or Excel fixtures
npx @clidey/whodb import --connection ci-postgres --file test/fixtures/users.csv --table users

# Run data-quality checks
npx @clidey/whodb audit --connection ci-postgres --schema public --format json

Import Fixtures In CI

Use the path that matches your fixture format:

CSV Or Excel

Bash

npx @clidey/whodb import \
  --connection ci-postgres \
  --file test/fixtures/users.csv \
  --table users \
  --mode append

Useful flags include --schema, --delimiter, --sheet, --header=false, --mapping position, --mode overwrite, --mode upsert, --create-table, and --allow-auto-generated.

SQL

Bash

PGPASSWORD=postgres \
psql -h localhost -U postgres -d app_test -f test/fixtures/seed.sql

The in-app import panel also supports pasted SQL and .sql uploads for manual workflows.

Local Reproduction With Docker Compose

This is useful when a pipeline failure needs a browser-based inspection pass.

YAML

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app_test
    ports:
      - "5432:5432"

  whodb:
    image: clidey/whodb:latest
    ports:
      - "8080:8080"
    environment:
      WHODB_POSTGRES: >-
        [{"alias":"local-ci-postgres","host":"postgres","user":"postgres","password":"postgres","database":"app_test","port":"5432"}]
    depends_on:
      - postgres

Run:

Bash

docker compose up -d
curl -fsS http://localhost:8080/health

Open http://localhost:8080 and choose the preloaded profile.

Validation Script

Keep validation scripts small and database-specific:

Bash

#!/usr/bin/env bash
set -euo pipefail

DATABASE_URL="${DATABASE_URL:?DATABASE_URL is required}"

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 <<'SQL'
SELECT COUNT(*) AS user_count FROM users;

SELECT COUNT(*) AS orphaned_orders
FROM orders o
LEFT JOIN users u ON u.id = o.user_id
WHERE u.id IS NULL;
SQL

Best Practices

Related Pages

Importing Data

Use the in-app and CLI import flows.

Docker Integration

Run WhoDB with Docker and Docker Compose.

Monitoring Integration

Monitor the /health endpoint and logs.

Backup Tools

Use database-native backup and restore workflows.

Next

Monitoring Integration