Statamic PostgreSQL Engine

Important notice: This addon is in an alpha state. Expect bugs. Do not use in production without rigorous testing. Please raise issues.

A PostgreSQL-native content engine for Statamic 6. Replaces flat-file Stache storage with PostgreSQL while preserving full compatibility with Statamic's Query Builder, GraphQL API, Antlers tags, and Control Panel.

No Eloquent models. No statamic/eloquent-driver. Direct PostgreSQL storage through Statamic's repository contracts.

What it does

• Stores all Statamic content types in PostgreSQL: collections, entries, taxonomies, terms, globals, navigations, asset containers, forms, submissions, and revisions
• Uses PostgreSQL-native features: JSONB for flexible data, UUID primary keys, citext for case-insensitive handles, tsvector for full-text search, pg_trgm for fuzzy search
• Provides bidirectional import/export between flat files and PostgreSQL
• Includes observability tooling: slow query logging, query profiling, health checks

What it doesn't do

• Does not use Eloquent models for content persistence
• Does not require statamic/eloquent-driver
• Does not introduce a custom query API — everything works through standard Statamic methods
• Does not store blueprints, fieldsets, or users — those stay in their default locations

Requirements

• PHP 8.5+
• PostgreSQL 15+
• Statamic 6
• Laravel 13

---

Installation

1. Install the package

composer require stokoe/postgres-engine

2. Configure your database

Your .env should have a PostgreSQL connection:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=your_database
DB_USERNAME=your_user
DB_PASSWORD=your_password

3. Activate the addon

Add this to your .env:

POSTGRES_ENGINE_CONNECTION=pgsql

Without this line, the addon stays dormant and Statamic uses Stache as normal.

4. Run migrations

php artisan migrate

5. Verify

php artisan pg-engine:doctor

All checks should pass.

6. Publish config (optional)

php artisan vendor:publish --tag=postgres-engine-config

See INSTALL.md for the full installation guide including troubleshooting.

---

Usage

Once activated, the addon is transparent. All standard Statamic code works without modification:

// Query Builder — works identically
Entry::query()->where('collection', 'blog')->orderBy('date', 'desc')->get();

// Facades — work identically
Collection::findByHandle('blog');
Taxonomy::findByHandle('tags');
GlobalSet::findByHandle('site_settings');

// Repository contracts — resolve to PostgreSQL implementations
app(EntryRepository::class)->find($id);
app(CollectionRepository::class)->all();

Antlers templates, GraphQL queries, and the Control Panel all work without changes.

---

Import & Export

Import flat files into PostgreSQL

# Dry-run first (validates without writing)
php artisan pg-engine:import content --dry-run

# Full import
php artisan pg-engine:import content

Export PostgreSQL back to flat files

php artisan pg-engine:export storage/app/export --overwrite

Import specific content types

php artisan pg-engine:import content --type=collections
php artisan pg-engine:import content --type=entries --collection=blog
php artisan pg-engine:import content --type=taxonomies
php artisan pg-engine:import content --type=terms --taxonomy=tags
php artisan pg-engine:import content --type=globals
php artisan pg-engine:import content --type=navigations
php artisan pg-engine:import content --type=assets
php artisan pg-engine:import content --type=forms
php artisan pg-engine:import content --type=submissions
php artisan pg-engine:import content --type=revisions

Export specific content types

php artisan pg-engine:export path/to/export --type=collections --overwrite
php artisan pg-engine:export path/to/export --type=globals --overwrite
php artisan pg-engine:export path/to/export --type=navigations --overwrite

Import is idempotent — running it twice updates existing records without creating duplicates. Export supports --dry-run and --overwrite flags. Sensitive metadata (IP hashes, user agent hashes) is excluded from exports.

See docs/IMPORT_EXPORT.md for the full import/export architecture.

---

Switching Between PostgreSQL and Flat Files

Mode	.env setting	Content source
PostgreSQL	POSTGRES_ENGINE_CONNECTION=pgsql	pg_* tables
Flat files	Line removed or commented	content/ YAML/MD files

To switch back to flat files:

# Comment out the activation line in .env
# POSTGRES_ENGINE_CONNECTION=pgsql

# Clear caches
php artisan cache:clear
php artisan statamic:stache:clear
php artisan statamic:stache:warm

To switch back to PostgreSQL, uncomment the line. No reimport needed.

---

Commands

Command	Description
pg-engine:doctor	Health check: connection, extensions, tables, indexes, bindings
pg-engine:import {path}	Import flat files into PostgreSQL
pg-engine:export {path}	Export PostgreSQL content to flat files
pg-engine:reindex	Rebuild full-text search indexes
pg-engine:search:test {query}	Test search queries interactively
pg-engine:stats	Query statistics and slow query report

All commands support --help for full option details.

---

Search

The addon provides PostgreSQL-native search with four modes:

• Full-text search — tsvector-based, language-aware, ranked by relevance
• Fuzzy search — pg_trgm trigram matching for typo tolerance
• Hybrid search — combines full-text and fuzzy results
• Accent-insensitive search — uses the unaccent extension

Search weights are configurable per field (A/B/C/D ranking). Rebuild indexes after import:

php artisan pg-engine:reindex

---

Architecture

See docs/ARCHITECTURE.md for the full technical architecture.

The addon is structured in layers:

ServiceProvider          — Registers all bindings, validates config
  ├── Repositories       — Implement Statamic contracts (Entry, Collection, etc.)
  │     ├── Hydrators    — Convert DB rows ↔ Statamic objects
  │     └── Storage      — Raw PostgreSQL operations (no Eloquent)
  ├── Query              — EntryQueryBuilder, TermQueryBuilder, SQL compilation
  ├── Search             — Full-text, fuzzy, hybrid search engine
  ├── Import/Export      — Bidirectional flat-file ↔ PostgreSQL
  ├── Observability      — Query profiling, slow query logging
  ├── Support            — Identity map, cycle detector, bulk loader
  └── Commands           — Artisan commands (doctor, import, export, reindex, stats)

---

Testing

composer test

The test suite enforces strict guards — any incomplete, skipped, or noticed test fails the run:

• 976 tests, 5114 assertions
• 0 incomplete, 0 skipped, 0 PHPUnit notices
• failOnIncomplete, failOnSkipped, failOnNotice, failOnRisky all enabled

---

Compatibility

This addon maintains full compatibility with:

• Statamic Query Builder — Entry::query(), where(), orderBy(), paginate(), JSONB dot-notation
• Statamic GraphQL API — collections, entries, globals, filtering, sorting, pagination
• Antlers tags — {{ collection }}, {{ nav }}, {{ global }}, all standard tags
• Control Panel — listings, filtering, sorting, pagination, publish/unpublish
• Native Statamic objects — Entry, Collection, Term, GlobalSet, Nav, etc.

Existing Statamic code works without modification.

---

Postgres Engine is a Commercial Addon.

You can use it for free while in development, but requires a license to use on a live site. Learn more or buy a license on The Statamic Marketplace!