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-cli 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-cli 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-cli

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-cli schemas --connection ci-postgres --format json
npx @clidey/whodb-cli tables --connection ci-postgres --schema public --format json

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

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

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

# Run data-quality checks
npx @clidey/whodb-cli 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-cli 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