From 3cb46b7c19525df2d4edc4d5e0f6b7ec17f8b8b7 Mon Sep 17 00:00:00 2001 From: Zaid Date: Wed, 7 Oct 2026 15:16:32 +0500 Subject: [PATCH 1/3] Revise ColdFront architecture diagram in README Updated the architecture diagram for ColdFront to clarify the hot and cold tier structure and their components. --- README.md | 54 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 5c9c3cc8..e63e1b6e 100644 --- a/README.md +++ b/README.md @@ -66,27 +66,39 @@ ColdFront runs inside PostgreSQL and rewrites each statement to the correct tier, so the application sees one relation: ```text - Application - │ - SELECT / INSERT / UPDATE / DELETE - against one relation: "events" - │ - PostgreSQL 16 / 17 / 18 - events VIEW: reads union hot + cold - coldfront extension: routes writes by tier - ┌─────────────┴───────────────┐ - │ │ - hot tier cold tier - _events: native PostgreSQL pg_duckdb: in-process DuckDB - range partitions Iceberg reads + writes - │ │ - │ Lakekeeper (Iceberg REST catalog) - │ │ - │ object store, S3 / Azure / GCS - │ (Parquet data + Iceberg metadata) - │ ▲ - └──── Archiver (Go, cron) ────┘ - moves partitions past the hot window: hot → cold + Application + │ + SELECT / INSERT / UPDATE / DELETE + on one relation: "events" + │ + ┌────────────────────────────▼─────────────────────────────┐ + │ PostgreSQL 16 / 17 / 18 │ + │ │ + │ events view: reads return hot + cold rows │ + │ coldfront extension: routes writes by tier. │ + └───────────┬─────────────────────────────────┬────────────┘ + │ │ + HOT TIER COLD TIER + recent rows, local disk older rows, object storage + │ │ + ┌──────────▼───────────┐ ┌────────────▼────────────┐ + │ _events │ │ pg_duckdb │ + │ native PostgreSQL │ │ in-process DuckDB │ + │ range partitions │ │ Iceberg reads + writes │ + └──────────┬─────────── └────────────┬────────────┘ + │ │ + │ ┌───────────▼─────────────┐ + │ │ Lakekeeper │ + │ │ Iceberg REST catalog │ + │ └───────────┬─────────────┘ + │ │ + │ │ + │ ┌───────────▼─────────────────────┐ + │ │ Object store,S3 / Azure / GCS │ + │ │ │ + └── Archiver (Go) ───▶│(Parquet data + Iceberg metadata)│ + └─────────────────────────────────┘ + cron job: moves partitions out of the hot window: hot -> cold ``` ## Installation From ea4cc92af53d799fdb229598f387c5a0642fb9a1 Mon Sep 17 00:00:00 2001 From: Zaid Date: Thu, 8 Oct 2026 17:29:05 +0500 Subject: [PATCH 2/3] Update architecture diagram in index.md Update architecture diagram in index.md --- docs/index.md | 54 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 21 deletions(-) diff --git a/docs/index.md b/docs/index.md index b60f72dc..78a0b2f5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,27 +40,39 @@ ColdFront runs inside PostgreSQL and rewrites each statement to the correct tier, so the application sees one relation: ```text - Application - │ - SELECT / INSERT / UPDATE / DELETE - against one relation: "events" - │ - PostgreSQL 16 / 17 / 18 - events VIEW: reads union hot + cold - coldfront extension: routes writes by tier - ┌─────────────┴───────────────┐ - │ │ - hot tier cold tier - _events: native PostgreSQL pg_duckdb: in-process DuckDB - range partitions Iceberg reads + writes - │ │ - │ Lakekeeper (Iceberg REST catalog) - │ │ - │ object store, S3 / Azure / GCS - │ (Parquet data + Iceberg metadata) - │ ▲ - └──── Archiver (Go, cron) ────┘ - moves partitions past the hot window: hot → cold + Application + │ + SELECT / INSERT / UPDATE / DELETE + on one relation: "events" + │ + ┌────────────────────────────▼─────────────────────────────┐ + │ PostgreSQL 16 / 17 / 18 │ + │ │ + │ events view: reads return hot + cold rows │ + │ coldfront extension: routes writes by tier. │ + └───────────┬─────────────────────────────────┬────────────┘ + │ │ + HOT TIER COLD TIER + recent rows, local disk older rows, object storage + │ │ + ┌──────────▼───────────┐ ┌────────────▼────────────┐ + │ _events │ │ pg_duckdb │ + │ native PostgreSQL │ │ in-process DuckDB │ + │ range partitions │ │ Iceberg reads + writes │ + └──────────┬─────────── └────────────┬────────────┘ + │ │ + │ ┌───────────▼─────────────┐ + │ │ Lakekeeper │ + │ │ Iceberg REST catalog │ + │ └───────────┬─────────────┘ + │ │ + │ │ + │ ┌───────────▼─────────────────────┐ + │ │ Object store,S3 / Azure / GCS │ + │ │ │ + └── Archiver (Go) ───▶│(Parquet data + Iceberg metadata)│ + └─────────────────────────────────┘ + cron job: moves partitions out of the hot window: hot -> cold ``` ## Quickstart From a28c70a2a5fb81598c593b3e88190605fe70c004 Mon Sep 17 00:00:00 2001 From: Susan Douglas Date: Thu, 8 Oct 2026 09:18:49 -0400 Subject: [PATCH 3/3] fix: close the left box in the architecture diagram, fix spacing The _events box's bottom border was missing its closing corner, and "Object store,S3" was missing a space after the comma. Co-Authored-By: Claude Sonnet 5 --- README.md | 4 ++-- docs/index.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e63e1b6e..c4fa4930 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ tier, so the application sees one relation: │ _events │ │ pg_duckdb │ │ native PostgreSQL │ │ in-process DuckDB │ │ range partitions │ │ Iceberg reads + writes │ - └──────────┬─────────── └────────────┬────────────┘ + └──────────┬───────────┘ └────────────┬────────────┘ │ │ │ ┌───────────▼─────────────┐ │ │ Lakekeeper │ @@ -94,7 +94,7 @@ tier, so the application sees one relation: │ │ │ │ │ ┌───────────▼─────────────────────┐ - │ │ Object store,S3 / Azure / GCS │ + │ │ Object store, S3 / Azure / GCS │ │ │ │ └── Archiver (Go) ───▶│(Parquet data + Iceberg metadata)│ └─────────────────────────────────┘ diff --git a/docs/index.md b/docs/index.md index 78a0b2f5..d38a410b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -59,7 +59,7 @@ tier, so the application sees one relation: │ _events │ │ pg_duckdb │ │ native PostgreSQL │ │ in-process DuckDB │ │ range partitions │ │ Iceberg reads + writes │ - └──────────┬─────────── └────────────┬────────────┘ + └──────────┬───────────┘ └────────────┬────────────┘ │ │ │ ┌───────────▼─────────────┐ │ │ Lakekeeper │ @@ -68,7 +68,7 @@ tier, so the application sees one relation: │ │ │ │ │ ┌───────────▼─────────────────────┐ - │ │ Object store,S3 / Azure / GCS │ + │ │ Object store, S3 / Azure / GCS │ │ │ │ └── Archiver (Go) ───▶│(Parquet data + Iceberg metadata)│ └─────────────────────────────────┘