TimescaleDB "extension must be loaded via shared_preload_libraries" in CI

By Kaveh Alemi·Latchkey

TimescaleDB must be loaded at server startup via shared_preload_libraries. If you run CREATE EXTENSION timescaledb on a Postgres that did not preload it, the command fails telling you to add it and restart. Using the official timescaledb image avoids this.

What this error means

CREATE EXTENSION fails with "FATAL: extension \"timescaledb\" must be preloaded" or "The timescaledb library is not preloaded. Please add 'timescaledb' to shared_preload_libraries".

ERROR: could not open extension control file: The timescaledb library is not
preloaded. Please add 'timescaledb' to shared_preload_libraries in
postgresql.conf and restart the database.

Common causes

A plain Postgres image without preload

A stock postgres image does not preload TimescaleDB, so the extension cannot initialize even if the files are present.

shared_preload_libraries not configured

The server was started without timescaledb in shared_preload_libraries, which only takes effect after a restart.

How to fix it

Use the official TimescaleDB image

1. Run the timescale/timescaledb image, which preloads the library.
2. Create the extension after the server is ready.
3. Verify with \dx that timescaledb is installed.

services:
  timescaledb:
    image: timescale/timescaledb:latest-pg16
    env: { POSTGRES_PASSWORD: postgres }
    ports: ['5432:5432']

Preload the library if using plain Postgres

Set the preload at startup so the extension can load, then create it.

# start with: -c shared_preload_libraries=timescaledb
psql -c "CREATE EXTENSION IF NOT EXISTS timescaledb;"

How to prevent it

• Use the official timescaledb image in CI.
• If using plain Postgres, set shared_preload_libraries at startup.
• Verify the extension with \dx before running migrations.

Frequently asked questions

Related guides

References

• GitHub Actions documentation