---
title: "chDB: An OLAP Engine Inside Your Process"
description: "chDB embeds a ClickHouse OLAP engine inside your process, so analytical queries skip the network round trip. This architecture view maps the binding layer, the local MergeTree working copy, and the flush path to object storage."
---

# chDB: An OLAP Engine Inside Your Process

**Type:** [Architecture](https://yomu.fyi/visual-explainers/category/architecture.md)

![Layered architecture diagram of chDB: bindings above an in-process ClickHouse engine with a local MergeTree working copy, above a durable layer that flushes to object storage; a side column shows the Postgres extension helper process exchanging ClickHouse Native results over file descriptors.](https://yomufyi.s3.us-east-1.amazonaws.com/visual-explainers/0b03cc0a-3d3f-412d-acfb-ea59eaec4f4c/image-70a57db0-48eb-42e9-b811-9d7e946f6863.webp)

> chDB embeds a ClickHouse OLAP engine inside your process, so analytical queries skip the network round trip. This architecture view maps the binding layer, the local MergeTree working copy, and the flush path to object storage.

## Explanation

chDB is an embedded SQL OLAP engine: a ClickHouse engine that runs inside the application process instead of behind a database server. Bindings for Python, Node, Go, and Rust sit at the top and hand queries to the engine, which keeps a local MergeTree working copy on disk. A durable layer below publishes authoritative state to object storage through flush() and checkpoint(), so the same memory can move to CI, a sandbox, or another laptop without losing the local analytical hot path. The Postgres extension variant shows the same idea at the process boundary: a helper application runs on demand and returns ClickHouse Native results over file descriptors, isolating the database cluster.

## FAQ

### What breaks when the local MergeTree directory is the only copy?

The MergeTree directory exists on one disk, so moving memory to CI, a sandbox, or another laptop breaks the local-disk assumption. Publishing authoritative state to object storage removes that single-machine dependency without reintroducing a server round trip on every read.

**Tags:** [Agent Memory](https://yomu.fyi/topic/agent-memory.md), [chdb](https://yomu.fyi/topic/chdb.md), [ClickHouse](https://yomu.fyi/topic/clickhouse.md), [Object Storage](https://yomu.fyi/topic/object-storage.md), [OLAP](https://yomu.fyi/topic/olap.md), [Postgres](https://yomu.fyi/topic/postgres.md)

## Related reading

### [Lakebase branching for CI/CD: lessons from 100 PR databases](https://yomu.fyi/post/lakebase-branching-for-ci-cd-lessons-from-100-pr-databases.md)
- Company: [Databricks](https://yomu.fyi/company/databricks.md)
- Author: Yasamin Tari, Kartik Mathur
- Published: Nov 1, 2026
- Type: Problem & solution

Snorkel AI needed each pull request in its CI pipeline to have an isolated copy of production data for realistic testing, but restoring a full database copy took about 20 minutes per environment. They adopted Databricks’ Lakebase Postgres, whose copy-on-write branching creates writable branches in seconds regardless of database size because no data is copied at branch creation. AWS DMS continuously replicates the production Aurora cluster into Lakebase’s main branch, keeping it within about two minutes of the source. For every PR, the CI pipeline creates a branch via API, runs tests, and either deletes the branch or relies on automatic TTL expiration to clean up. Provisioning time dropped from over 30 minutes to under 60 seconds at p95, supporting about 100 concurrent PR branches on a 2.5 TB dataset with storage growing only for changes written.


### [Meet GroeneAI: our autonomous contributor to ClickHouse](https://yomu.fyi/post/meet-groeneai-our-autonomous-contributor-to-clickhouse.md)
- Company: [Clickhouse](https://yomu.fyi/company/clickhouse.md)
- Published: Oct 29, 2026
- Type: Announcement

GroeneAI is an autonomous engineering agent that investigates and fixes failures in the ClickHouse codebase without human intervention, selecting its own work from CI results, fuzzer findings, and user reports. It reproduces failures, writes and tests fixes, and follows pull requests through CI and review, operating 24 hours a day, seven days a week. The agent runs on Nerve, an open-source runtime that provides persistent sessions, memory, and tools for scheduled execution, allowing it to learn from past investigations and autonomously handle review comments and rebase changes. Since March 2026, GroeneAI has contributed over 3,000 merged pull requests, covering the SQL engine, storage, query planning, and test infrastructure. A detailed example shows how it fixed a query condition cache bug that incorrectly skipped rows after mutations, with the fix guarded by checks for mutation steps and row-level security, taking sixteen days from the initial failure to the final merge.


### [chDB Durable Layer for agent memory](https://yomu.fyi/post/chdb-durable-layer-for-agent-memory.md)
- Company: [Clickhouse](https://yomu.fyi/company/clickhouse.md)
- Published: Sep 28, 2026
- Type: Announcement

Agent memory built on chDB, an embedded SQL OLAP engine, accumulated state such as project rules, user preferences, and recall traces on a single laptop. Moving that memory to CI, sandboxes, or another laptop broke the local-disk assumption because the MergeTree directory existed on only one disk. Adding a ClickHouse server backend fixed portability but turned every recall into a network round trip. The chDB Durable Layer fills the gap by keeping the local analytical hot path while publishing authoritative state to object storage (S3, GCS, or Azure Blob). Applications write to a local working copy and use flush() to publish writes and checkpoint() to compact the log, avoiding a sidecar or database server. The contract supports Python, Node, Go, and Rust bindings with cross-binding recoverability.


### [Introducing chdb Postgres extension: High-performance imports from cloud storage](https://yomu.fyi/post/introducing-chdb-postgres-extension-high-performance-imports-from-clou.md)
- Company: [Clickhouse](https://yomu.fyi/company/clickhouse.md)
- Published: Sep 8, 2026
- Type: Announcement

The new chdb Postgres extension uses the chDB library, an in-process ClickHouse engine, to import and export data between Postgres and files on cloud storage. In benchmarks using the one-million-row NYC Taxi dataset, chdb ran on four-vCPU, 32-GB ClickHouse Managed Postgres instances and showed the most consistent performance; pg\_duckdb and pg\_lake took about two to three times longer for CSV, JSON, and Parquet, while aws\_s3 supported fewer formats. Its chdb\_query() function executes chDB queries, while chdb\_hook integrates with COPY for AWS S3, Google Cloud Storage, Azure Blob Storage, local files, and HTTP URLs, with wildcard expansion for multiple files. The extension launches a separate helper application on demand and exchanges ClickHouse Native results through file descriptors, limiting resource use and isolating the PostgreSQL cluster.
