Link Search Menu Expand Document

Installation

Table of contents
  1. Requirements
  2. Build from Source
    1. 1. Install build dependencies
    2. 2. Clone and build
    3. 3. Configure PostgreSQL
    4. 4. Restart and create extension
  3. Upgrade
  4. Verify Installation
  5. Configuration

Requirements

  • PostgreSQL 16, 17, or 18 (server headers required)
  • C compiler (gcc or clang)
  • Optional compression libraries (strongly recommended):
Library Package (Debian/Ubuntu) Benefit
LZ4 liblz4-dev Very fast compression/decompression (~500 MB/s). Ideal for write-heavy workloads.
ZSTD ★ libzstd-dev Best ratio + good speed. Strongly recommended — saves 40–60% disk vs LZ4 with comparable read performance.
libdeflate libdeflate-dev zlib-compatible codec. Good middle ground between LZ4 and ZSTD.
ZXC build from source Asymmetric codec: extremely fast decompression via SIMD (NEON/ARM64, AVX2-AVX512/x86_64). Excellent on ARM Graviton/Neoverse.

Default compression precedence (first available wins): ZSTD > ZXC > LZ4 > Deflate > pglz

Build from Source

1. Install build dependencies

Ubuntu / Debian:

sudo apt update
sudo apt install -y build-essential postgresql-server-dev-18 \
    liblz4-dev libzstd-dev

# Optional
# sudo apt install libdeflate-dev

Replace postgresql-server-dev-18 with your PostgreSQL version (16, 17, or 18).

RPM-based (dnf):

sudo dnf install -y gcc make postgresql18-devel \
    lz4-devel libzstd-devel

# Optional
# sudo dnf install libdeflate-devel

2. Clone and build 

git clone https://github.com/saulojb/storage_engine.git
cd storage_engine
sudo make -j$(nproc) install

If multiple PostgreSQL versions are installed, specify which one:

# Pass PG_CONFIG as a make argument (not an env var before sudo)
sudo make -j$(nproc) install PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config

3. Configure PostgreSQL

Add to postgresql.conf:

shared_preload_libraries = 'storage_engine'

storage_engine must appear after citus and pg_cron if they are also loaded:

shared_preload_libraries = 'pg_cron,citus,storage_engine'

citus must be the outermost planner hook; reversing the order prevents PostgreSQL from starting.

4. Restart and create extension 

sudo systemctl restart postgresql

CREATE EXTENSION storage_engine;

Upgrade

To upgrade from a previous version:

# Build and install new version
sudo make -j$(nproc) install

# Restart PostgreSQL, then run in each database that uses the extension:
ALTER EXTENSION storage_engine UPDATE;

Upgrade scripts (storage_engine--X.Y.Z--A.B.C.sql) are provided for all version pairs.

Verify Installation 

-- Check loaded version
SELECT extversion FROM pg_extension WHERE extname = 'storage_engine';

-- List available AMs
SELECT amname FROM pg_am WHERE amname IN ('colcompress', 'rowcompress');

-- Quick sanity check
CREATE TABLE _test (id int, val text) USING colcompress;
INSERT INTO _test VALUES (1, 'hello'), (2, 'world');
SELECT * FROM _test;
DROP TABLE _test;

Configuration

Key GUCs after installation. All can be set globally in postgresql.conf or per-session.

-- Enable vectorized GROUP BY aggregation (default: on)
SET storage_engine.enable_vectorized_groupagg = on;

-- Enable parallel scan (default: on)
SET storage_engine.enable_parallel_execution = on;

-- Default compression codec (default: zstd)
SET storage_engine.compression = 'zstd';

-- Default compression level for zstd 1–19 (default: 3)
SET storage_engine.compression_level = 3;

See Reference → GUCs for the full parameter list.