cupug

Build and Test

cupug is a standard PostgreSQL extension built with PGXS. Testing can run locally in Docker or on remote GPU instances via vast.ai.

Building

cupug compiles against a PostgreSQL installation using pg_config:

make PG_CONFIG=/path/to/pg_config
make install PG_CONFIG=/path/to/pg_config

If pg_config is already on your PATH, the PG_CONFIG variable can be omitted.

Regression Tests

The extension ships with pg_regress tests in expected/ and sql/. After building and installing:

make installcheck

This requires a running PostgreSQL instance with the test database contrib_regression already created.

Docker Tests (CPU)

Docker targets build a self-contained image, compile the extension inside it, and run pg_regress automatically. No local PostgreSQL installation is needed.

make test-pg16       # test against PostgreSQL 16
make test-pg17       # test against PostgreSQL 17
make test-all        # both versions, sequentially

The image is based on the official postgres:XX Docker image. The Dockerfile is at test/Dockerfile and the in-container test runner is test/run_tests.sh.

vast.ai GPU Tests

For testing on real GPU hardware, cupug can rent a GPU instance on vast.ai, run the tests, and tear it down automatically.

Prerequisites

  1. Install the vast.ai CLI: pip install vastai
  2. Save your API key from https://cloud.vast.ai/account/ to ~/.vast_api_key
  3. Set DOCKER_REGISTRY to a registry you can push to (e.g., export DOCKER_REGISTRY=docker.io/myuser)
  4. Ensure docker login has been run for that registry

Makefile Targets

make vast-build              # build the CUDA Docker image locally
make vast-push               # build + push to DOCKER_REGISTRY
make test-vast-pg16          # full lifecycle: build, push, rent GPU, test, destroy
make test-vast-pg17          # same for PostgreSQL 17
make test-vast-all           # PG 16 then PG 17

Configuration

All vast.ai targets accept these Make variables:

Variable Default Description
CUDA_TAG 12.4.1-cudnn-devel-ubuntu22.04 CUDA base image tag
DOCKER_REGISTRY (required) Docker registry for push
VAST_TIMEOUT 600 Seconds before timeout
VAST_MAX_PRICE 0.20 Max dollars per hour for GPU rental

Example:

make test-vast-pg17 VAST_MAX_PRICE=0.30 VAST_TIMEOUT=900

How It Works

The lifecycle is managed by test/vast-run.sh:

  1. Build test/Dockerfile.vast – a CUDA-enabled Ubuntu image with PostgreSQL from the PGDG apt repository. The extension source is copied in but not compiled at build time (compilation needs the target GPU environment).
  2. Push the image to DOCKER_REGISTRY.
  3. Search vast.ai for the cheapest GPU offer matching the price and reliability criteria.
  4. Create an instance with test/vast-test.sh as the startup command.
  5. Poll the instance until it reaches “running” state.
  6. Poll the instance logs for the sentinel string CUPUG_VAST_TESTS_PASSED or CUPUG_VAST_TESTS_FAILED.
  7. Destroy the instance (always, via a shell trap).
  8. Exit 0 on pass, 1 on failure or timeout.

Orchestrator Options

test/vast-run.sh can also be invoked directly with finer control:

bash test/vast-run.sh --pg-major 17 --gpu-name RTX_4090 --max-price 0.50
Flag Default Description
--pg-major 16 PostgreSQL major version
--cuda-tag 12.4.1-cudnn-devel-ubuntu22.04 CUDA base image tag
--gpu-name RTX_3060 GPU type to request
--disk 16 Disk space in GB
--max-price 0.20 Max $/hr
--timeout 600 Timeout in seconds
--image (auto) Use a pre-built remote image
--skip-build off Skip docker build/push

Local Verification

The vast.ai image can be tested locally without GPU hardware or API credentials:

docker build -f test/Dockerfile.vast --build-arg PG_MAJOR=17 -t cupug-vast:pg17 .
docker run --rm cupug-vast:pg17 bash /build/cupug/test/vast-test.sh

This runs the same test sequence on CPU, which is sufficient for validating the extension logic and the test infrastructure itself.

File Layout

test/
  Dockerfile          # CPU-only test image (postgres:XX base)
  Dockerfile.vast     # GPU test image (CUDA + PGDG PostgreSQL)
  run_tests.sh        # in-container runner for Docker tests
  vast-test.sh        # in-container runner for vast.ai tests
  vast-run.sh         # developer-machine orchestrator for vast.ai