Skip to main content
Version: 0.2

Architecture

pg_mooncake is built as a Postgres extension. It combines pg_duckdb for read path, with Moonlink for the write path.

Writing to the columnstore​

Moonlink is a Rust library that handles writes to the columnstore (Apache Iceberg format). It is a high-performance ingestion engine for getting data into the open columnar table format used for analytics.

By default, it is packaged as a Postgres background worker. And can also be deployed as an external service.

pg_mooncake supports writing data to columnstore tables via:

  1. Logical replication - Replicate a Postgres table automatically
  2. [roadmap] Bulk file uploads - Import large datasets efficiently
  3. [roadmap] Streaming events - Write data directly through the events API
  4. [roadmap] Kafka / OTEL sink.

Reading from the columnstore​

pg_duckdb handles all reads from columnstore tables within Postgres. Since Moonlink writes data to object storage, the read path remains completely stateless / serverless.

Production deployment​

By default, pg_mooncake bundles Moonlink as a Postgres background worker. This gives you both read and write capabilities in a single, easy-to-manage experience.

For production workloads, we recommend:

  1. Running Moonlink as a separate service rather than as a background worker
  2. Connecting Postgres (with pg_mooncake extension) to this external Moonlink instance to query the latest Iceberg tables

This architecture provides complete separation of storage and compute, making pg_mooncake completely stateless. A common pattern we see is running pg_mooncake as a separate analytics databse, alongside your transactional Postgres (RDS, Supabase, etc.). This often looks like:

┌────────────┐                                
│            │logical                         
│            │replication                     
│            ├──────────┐                     
│  Postgres  │          │                     
│  OLTP      │    ┌─────▼──────┐              
└────────────┘    │┌──────────┐│              
                  ││          ││   ┌─────────┐
                  ││          │├───│         │
┌────────────┐    ││ moonlink ││   │s3       │
│            │    │└──────────┘│   └─────────┘
│            │    └─────┬──────┘              
│            │          │                     
│pg_mooncake │          │                     
│            ◄──────────┘                     
└────────────┘stateless                       
              reads

Reach out if you're planning a production deployment—we're happy to share deployment best practices and architecture guidance.