docker

PLANET in Docker

This directory provides PostgreSQL 18.4 with PLANET built in, plus the evaluation tools. Calibration normally runs on the host; benchmarks run in containers.

Quick start

make demo      # guided walkthrough of the whole interface (demo.sql)
make test      # the extension's regression suite against the running server
make psql      # a shell on it
make down      # stop  (make clean also drops the data volume)

make demo and make test bring the server up first, so a fresh clone needs nothing else. All of these are also reachable from the repository root.

Comparing two alternatives

make compare ARGS="-q 'SELECT count(*) FROM facts WHERE dim_id = 7' \
    -A 'SET enable_seqscan=off' -B 'SET enable_indexscan=off' \
    --sweep /results/sweep.csv"

Put your calibration sweep in results/ first; that directory is mounted at /results in the container. Without it the tool prints the point ordering and makes no recommendation.

Reproducing the paper's experiments

make up
make dataset SCALE=2000000
make overhead ARGS="--mode ro --rounds 1 --time 5 --energy off"
make pilot
make plot
make down

The paper uses the default SCALE=20000000. Results are written to results/. make clean also removes the PostgreSQL data volume.

Calibration handoff

Create coefficients on the database host:

cd ../calibration
python3 collect_sweep.py -d calib -o sweep.csv
python3 fit_model.py sweep.csv -o ../config/coefficients.json

Then apply them to a running container:

cd ../docker
make coefficients

The file is also applied on first database initialization. make up prints the active PLANET settings.

Important settings

• PLANET is not preloaded. The overhead benchmark needs a baseline session without its hooks; benchmark sessions load it explicitly.
• The database and benchmark container use a Unix socket to avoid TCP noise.
• shm_size: 2gb is required for the parallel-plan sweep.
• Port 5432 is not published because the benchmark uses trust authentication.
• planet.conf contains the server settings used by the experiments.

RAPL inside Docker

Most benchmarks run without RAPL. To collect the optional energy-per-transaction column, make RAPL readable on the host and use the supplied overlay:

sudo chmod a+r /sys/class/powercap/intel-rapl:*/energy_uj
docker compose -f compose.yaml -f compose.energy.yaml run --rm bench \
  python3 /opt/planet/eval/bench_overhead.py -d bench --energy on

RAPL is host-wide. Use it only on an otherwise idle measurement machine.

Files

File	Purpose
Dockerfile	builds the extension and runtime image
demo.sql	the guided walkthrough make demo runs
compose.yaml	database, benchmark, and regression-test services
compose.energy.yaml	opt-in RAPL access
planet.conf	benchmark PostgreSQL settings
initdb.d/	extension and coefficient initialization
apply-coefficients.py	validates and applies coefficient JSON