walshadow README

The project's README from github.com/ClickHouse/walshadow. As one markdown file: README.md.

walshadow

[!WARNING] Experimental

Project status: Development Preview

walshadow is under active development and being hardened through real-world testing and feedback. We recommend validating it thoroughly with your workloads. Interfaces and behavior may evolve

walshadow replicates PostgreSQL rows into ClickHouse from physical WAL, including initial load, continuous changes, schema evolution, restarts, and planned source switchover

Get Started

PostgreSQL 16 or newer is required. Source and walshadow shadow must use same PostgreSQL major version

Documentation

System design and diagrams live in architecture, unfinished work in plans, and build and test guidance in development. Read source for implementation details

Build from source

Clone repository with recursive submodules, then build Rust workspace and PostgreSQL module

# Clone source plus required pg-clickhouse-c and clickhouse-c submodules
git clone --recurse-submodules https://github.com/ClickHouse/walshadow.git
cd walshadow

# Build release binaries
cargo build --release

# Build and install PostgreSQL module with PGXS
make -C pgext install

Default features include LZ4. Use --no-default-features for uncompressed builds or enable zstd for Zstandard support

Built binaries:

walshadow PostgreSQL module is not an SQL extension. Managed shadow loads it through shared_preload_libraries

Test

# Build PostgreSQL module before integration tests
make -C pgext

# Run test suite and lints
cargo nextest run --workspace --all-targets
cargo clippy --all-targets -- -D warnings

Integration tests require initdb and pg_ctl on PATH

walshadow (ClickHouse/walshadow)

Searching Database…

这是干什么的?walshadow 通过读取物理 WAL,把 PostgreSQL 的行数据复制到 ClickHouse——初始全量导入、持续的增量变更、表结构演进、重启以及计划内的源库切换,都是整个流程的一部分。
我实际装的是什么——一个服务、命令行工具,还是程序库?主要是 walshadow-stream 复制守护进程,外加几个用于过滤和分类 WAL 的辅助工具。在 PostgreSQL 这边,它会安装一个通过 shared_preload_libraries 加载的模块,不是普通的 SQL 扩展。
怎么把第一套环境跑起来?按照 Quickstart 的指引,用 Docker Compose 把 PostgreSQL、ClickHouse 和 walshadow 一起跑起来;如果要接入你已经在用的数据库,请改看 Getting started 指南。
对 PostgreSQL 版本有要求吗?有——需要 PostgreSQL 16 或更新版本,而且 walshadow 必须和源数据库使用相同的 PostgreSQL 主版本。
它能用于生产环境吗?还不能——它目前是一个实验性的 Development Preview,仍在积极开发和打磨中,接口和行为都可能变化,所以请用你自己的实际负载充分验证。
walshadow-filter 和 walshadow-classify 这两个辅助工具是做什么的?walshadow-filter 按 segment 级别离线过滤 WAL 文件,walshadow-classify 则对单条记录进行分类——两者都是随主守护进程 walshadow-stream 一起发布的诊断辅助工具。
它复制数据时会压缩吗?会——默认构建使用 LZ4 压缩,可以启用 zstd(即 Zstandard),也可以用 --no-default-features 构建为不压缩模式。
它是怎么处理表结构变更和重启的?表结构演进、重启和计划内的源库切换都是复制流程中明确涵盖的部分,每一项都有自己的文档页面,不用用户自己摸索。
我能只复制部分表,或者同时复制多个数据库吗?可以——文档覆盖了表的选择、多个源数据库以及目标表的配置,所以选择性复制和多数据库复制都是支持的使用场景。
Creator
ClickHouse
Size
6.5 MB
Stars
241
Age
4mo
Commits · 90 Days