Installation

KoldStore must load at postmaster start. Without shared_preload_libraries = 'koldstore', planner hooks never register and managed SELECTs can silently miss cold rows after flush.

Fastest path: Docker

Published images preload the extension and create it on first init:

1docker pull jamals86/pg-koldstore:latest2docker run --rm \3  -e POSTGRES_PASSWORD=postgres \4  -p 5432:5432 \5  jamals86/pg-koldstore:latest

Connect:

1psql postgres://postgres:postgres@127.0.0.1:5432/koldstoredb

Confirm:

1SHOW shared_preload_libraries;     -- must include koldstore2CREATE EXTENSION IF NOT EXISTS koldstore;3SELECT koldstore.preload_status(); -- loaded_via_shared_preload = true

pg_cron may be packaged in the image but is not preloaded. Enable it yourself if you want cron-based flush scheduling.

Shared preload (required on every install)

Install order:

1. Install extension package files
2. Set shared_preload_libraries = 'koldstore' (merge with any existing list)
3. Restart PostgreSQL (reload is not enough)
4. CREATE EXTENSION koldstore

Ubuntu / Debian example:

1echo "shared_preload_libraries = 'koldstore'" | \2  sudo tee /etc/postgresql/16/main/conf.d/koldstore.conf3sudo systemctl restart postgresql@16-main

Rules:

• session_preload_libraries is not sufficient
• Removing preload after manage_table is unsupported
• Check with SELECT koldstore.preload_status();

Logical WAL (required for managed tables)

Committed-WAL capture needs:

1wal_level = logical

Restart after changing wal_level. Do not create the publication or logical slot yourself: CREATE EXTENSION ensures the empty publication koldstore_async_mirror, and the first manage_table creates the database’s deterministic slot. Provisioning is idempotent.

Recommended production GUC baseline

Prefer ALTER SYSTEM / ALTER DATABASE for settings the background worker reads (session SET does not always reach the worker):

From source (developers)

Build and install with pgrx against a local PostgreSQL (typical loop for PG 16):

1cargo pgrx install -p pg_koldstore \2  --no-default-features \3  --features "pg16 s3" \4  --pg-config "$(cargo pgrx info pg-config 16)"

Then set preload, restart, and CREATE EXTENSION. See the repository quickstart  and Docker  folder for compose + MinIO layouts.

Upgrades (beta)

There are no packaged ALTER EXTENSION … UPDATE edges yet while the product is in development. Local installs reinstall or resync when the bootstrap SQL changes. Treat in-place upgrade and pg_upgrade as future ops work — see Status & Limits.

Next step

Getting Started — register storage, manage a table, flush, and read with changes_since.