diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 5cad74dd..3c7a2056 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -64,6 +64,7 @@ *** xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan] *** xref:master/ecosystem_components/redis_fdw.adoc[redis_fdw] *** xref:master/ecosystem_components/pg_show_plans.adoc[pg_show_plans] +*** xref:master/ecosystem_components/pgdog.adoc[PgDog] * 监控运维 ** xref:master/getting-started/daily_monitoring.adoc[日常监控] ** xref:master/getting-started/daily_maintenance.adoc[日常维护] diff --git a/CN/modules/ROOT/pages/master/ecosystem_components/pgdog.adoc b/CN/modules/ROOT/pages/master/ecosystem_components/pgdog.adoc new file mode 100644 index 00000000..dbd7df9f --- /dev/null +++ b/CN/modules/ROOT/pages/master/ecosystem_components/pgdog.adoc @@ -0,0 +1,279 @@ + +:sectnums: +:sectnumlevels: 5 + += PgDog + +== 概述 +PgDog 是一个专为 PostgreSQL 设计的高性能、开源集群中间件（代理工具），采用 Rust 语言编写。它集成了自动分片、连接池和负载均衡功能，能让开发者在无需修改任何应用程序代码的前提下，实现 PostgreSQL 数据库的水平扩展与高可用管理。 + +注意，PgDog 使用 PostgreSQL 原生的 pg_query 模块实现语句解析，所以它不支持在 Oracle 兼容模式下运行。 + +项目地址： + +版本：v0.1.45 + +开源协议：AGPL-3.0 License + +== 安装 + +[TIP] +源码测试安装环境为 Ubuntu 26.04。 + +=== 依赖 + +[source,bash] +---- +sudo apt update && \ +sudo apt install -y cmake clang curl pkg-config \ + libssl-dev git build-essential mold rustup \ + docker +---- + +[TIP] +本文使用说明需要两个IvorySQL数据库实例，可通过本文提供的docker-compose文件快速搭建。安装docker-compose请参考： + +=== 源码安装 + +[source,bash] +---- +wget https://github.com/pgdogdev/pgdog/archive/refs/tags/v0.1.45.tar.gz +tar -zxf v0.1.45.tar.gz +cd pgdog-0.1.45 + +# 编译完后，会在`target/release`目录下生成可执行文件 +cargo build --release +---- + +=== 验证安装 + +[source,bash] +---- +# PgDog在本文档编写时处于快速迭代开发阶段，所以下面命令的输出不完整 +./target/release/pgdog --version +# 输出：PgDog v +---- + +== 配置 + +本文将配置两个分片，对PgDog的自动分片功能为例进行使用说明。 + +PgDog通过两个文件进行配置： + +[cols="1,2"] +|=== +| 文件名 | 说明 + +| pgdog.toml +| 包含PgDog的端口配置、后端PostgreSQL服务的配置等基础配置信息 + +| users.toml +| 访问PgDog的用户名和密码在这里配置 +|=== + + +创建`pgdog.toml`： + +[source,toml] +---- +[general] +host = "0.0.0.0" +port = 6432 +default_pool_size = 10 + +# ---- ivory_shard：分片到两个 IvorySQL 后端 ---- +# host、port以及database_name，如果不是使用本文提供的docker-compose搭建的环境，需要按照实际情况修改 +[[databases]] +name = "ivory_shard" +host = "ivory-shard0" +port = 5432 +database_name = "testdb" +user = "ivorysql" # 如果不提供，默认使用`users.toml`中对应的`name` +password = "ivorysql" # 如果不提供，默认使用`users.toml`中对应的`password` +shard = 0 + +[[databases]] +name = "ivory_shard" +host = "ivory-shard1" +port = 5432 +database_name = "testdb" +shard = 1 + +# ---- 分片键声明 ---- +# 配置必须与实际表结构统一 +[[sharded_tables]] +database = "ivory_shard" +name = "orders" +column = "customer_id" +data_type = "bigint" +---- + +创建`users.toml`： + +[source,toml] +---- +[admin] +name = "admin" +user = "admin" +password = "pgdog" + +[[users]] +name = "ivorysql" +password = "ivorysql" +database = "ivory_shard" +pool_size = 10 +---- + +创建`docker-compose.shard.yml`： + +[TIP] +`volumes`字段请根据实际的配置文件位置进行修改 + +[source,dockerfile] +---- +# 分片测试拓扑（独立 compose）：2 个分片后端。 +# ivory-shard0 IvorySQL 5.4 (pg) host:5443 +# ivory-shard1 IvorySQL 5.4 (pg) host:5444 + +x-ivory: &ivory + image: registry.highgo.com/ivorysql/ivorysql:5.4-bookworm + environment: &ivoryenv + MODE: pg + IVORYSQL_USER: ivorysql + IVORYSQL_PASSWORD: ivorysql + IVORYSQL_DB: testdb + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ivorysql -d testdb"] + interval: 5s + timeout: 3s + retries: 30 + +services: + ivory-shard0: + <<: *ivory + container_name: ivory-shard0 + ports: ["5443:5432"] + ivory-shard1: + <<: *ivory + container_name: ivory-shard1 + ports: ["5444:5432"] +---- + +== 使用 + +=== 启动PgDog + +[source,bash] +---- +./target/release/pgdog --config ./pgdog.toml --users ./users.toml +---- + + +=== 管理控制台 + +PgDog 提供了内置的管理数据库，用户名密码通过`users.toml`中`[[admin]]`字段进行配置。 + +[source,bash] +---- +psql "postgres://admin:pgdog@localhost:6433/admin" +---- + +[source,sql] +---- +-- 查看客户端连接及实时统计 +SHOW CLIENTS + +-- 查看从PgDog发起的PostgreSQL连接 +SHOW SERVERS + +-- 查看连接池信息 +SHOW POOLS + +-- 查看当前从pgdog.toml加载的配置 +SHOW CONFIG + +-- 查看连接池统计 +SHOW STATS + +-- 在同一网络中运行的 PgDog 进程列表。需要启用服务发现(service discovery) +SHOW PEERS + +-- 从磁盘重新加载配置。关于哪些选项可以在运行时修改,请参阅 pgdog.toml 和 users.toml +RELOAD + +-- 使用现有配置重新创建所有服务器连接 +RECONNECT + +-- 暂停所有连接池。客户端将一直等待连接,直到连接池恢复。可用于平滑重启 PostgreSQL 服务器 +PAUSE + +-- 恢复所有连接池。客户端可以重新取用连接 +RESUME + +-- 列出当前缓存中的prepared statements +SHOW PREPARED + +-- 列出当前位于 AST 缓存中、用于查询路由的语句 +SHOW QUERY_CACHE + +-- 暂停所有查询,以便在多个 PgDog 实例之间同步配置变更 +MAINTENANCE + +-- 显示每个数据库的 PostgreSQL 复制状态,包括副本延迟 +SHOW REPLICATION +---- + +=== 连接PgDog + +[source,bash] +---- +psql "postgres://ivorysql:ivorysql@localhost:6433/ivory_shard" +---- + +=== 执行操作 + +[TIP] +请确认分片后端没有`orders`表，PgDog会自动创建。 + +[source,sql] +---- +-- 创建表 +CREATE TABLE orders ( + order_id bigint, + customer_id bigint, + amount numeric(10,2), + PRIMARY KEY (order_id, customer_id) +); + +-- 插入数据：这两条数据将分别插入到两个分片后端 +-- BUG：这里不能使用`generate_series`函数，因为PgDog暂时对这个函数进行透传 +INSERT INTO orders values(1, 1, 1); +INSERT INTO orders values(2, 2, 2); +INSERT INTO orders values(3, 3, 3); +INSERT INTO orders values(4, 4, 4); +INSERT INTO orders values(5, 5, 5); +INSERT INTO orders values(6, 6, 6); +INSERT INTO orders values(7, 7, 7); + +-- 查询数据 +SELECT * FROM orders; +---- + +=== 分别连接两个分片后端确认数据 + +[TIP] +这里将看到两个分片后端的条目并不是均分的，这是因为PgDog根据`[[sharded_tables]]`中配置的`customer_id`字段，提取了数值并对其进行HASH分片。 + +[source,bash] +---- +# 分片1 +psql "postgres://ivorysql:ivorysql@localhost:5443/testdb", +# 分片2 +psql "postgres://ivorysql:ivorysql@localhost:5444/testdb", +---- + +在分片后端分别执行查询确认数据 +[source,sql] +---- +SELECT * FROM orders; +---- diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index 33e493d1..41f496c8 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -64,6 +64,7 @@ *** xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan] *** xref:master/ecosystem_components/redis_fdw.adoc[redis_fdw] *** xref:master/ecosystem_components/pg_show_plans.adoc[pg_show_plans] +*** xref:master/ecosystem_components/pgdog.adoc[PgDog] * Monitor and O&M ** xref:master/getting-started/daily_monitoring.adoc[Monitoring] ** xref:master/getting-started/daily_maintenance.adoc[Maintenance] diff --git a/EN/modules/ROOT/pages/master/ecosystem_components/pgdog.adoc b/EN/modules/ROOT/pages/master/ecosystem_components/pgdog.adoc new file mode 100644 index 00000000..23bebbf4 --- /dev/null +++ b/EN/modules/ROOT/pages/master/ecosystem_components/pgdog.adoc @@ -0,0 +1,278 @@ +:sectnums: +:sectnumlevels: 5 + += PgDog + +== Overview +PgDog is a high-performance, open-source clustering middleware (proxy tool) designed specifically for PostgreSQL and written in Rust. It integrates automatic sharding, connection pooling, and load balancing, enabling developers to achieve horizontal scaling and high-availability management of PostgreSQL databases without modifying any application code. + +Note that PgDog uses PostgreSQL's native pg_query module to parse statements, so it does not support running in Oracle compatibility mode. + +Project URL: + +Version: v0.1.45 + +Open-source license: AGPL-3.0 License + +== Installation + +[TIP] +The source build was tested on Ubuntu 26.04. + +=== Dependencies + +[source,bash] +---- +sudo apt update && \ +sudo apt install -y cmake clang curl pkg-config \ + libssl-dev git build-essential mold rustup \ + docker +---- + +[TIP] +The instructions in this document require two IvorySQL database instances, which can be quickly set up using the docker-compose file provided in this document. To install docker-compose, refer to: + +=== Building from Source + +[source,bash] +---- +wget https://github.com/pgdogdev/pgdog/archive/refs/tags/v0.1.45.tar.gz +tar -zxf v0.1.45.tar.gz +cd pgdog-0.1.45 + +# After compilation, the executable will be generated in the `target/release` directory +cargo build --release +---- + +=== Verifying the Installation + +[source,bash] +---- +# At the time this document was written, PgDog is under rapid iterative development, so the output of the command below is incomplete +./target/release/pgdog --version +# Output: PgDog v +---- + +== Configuration + +This document configures two shards and uses PgDog's automatic sharding feature as an example. + +PgDog is configured through two files: + +[cols="1,2"] +|=== +| File Name | Description + +| pgdog.toml +| Contains basic configuration information such as PgDog's port settings and the backend PostgreSQL service configuration + +| users.toml +| The username and password for accessing PgDog are configured here +|=== + + +Create `pgdog.toml`: + +[source,toml] +---- +[general] +host = "0.0.0.0" +port = 6432 +default_pool_size = 10 + +# ---- ivory_shard: shard across two IvorySQL backends ---- +# host, port, and database_name need to be modified according to your actual setup if you are not using the environment built with the docker-compose provided in this document +[[databases]] +name = "ivory_shard" +host = "ivory-shard0" +port = 5432 +database_name = "testdb" +user = "ivorysql" # if not provide, using `name` in `users.toml` +password = "ivorysql" # if not provide, using `password` in `users.toml` +shard = 0 + +[[databases]] +name = "ivory_shard" +host = "ivory-shard1" +port = 5432 +database_name = "testdb" +shard = 1 + +# ---- Shard key declaration ---- +# The configuration must match the actual table structure +[[sharded_tables]] +database = "ivory_shard" +name = "orders" +column = "customer_id" +data_type = "bigint" +---- + +Create `users.toml`: + +[source,toml] +---- +[admin] +name = "admin" +user = "admin" +password = "pgdog" + +[[users]] +name = "ivorysql" +password = "ivorysql" +database = "ivory_shard" +pool_size = 10 +---- + +Create `docker-compose.shard.yml`: + +[TIP] +Please modify the `volumes` field according to the actual location of your configuration files. + +[source,dockerfile] +---- +# Sharding test topology (standalone compose): 2 shard backends. +# ivory-shard0 IvorySQL 5.4 (pg) host:5443 +# ivory-shard1 IvorySQL 5.4 (pg) host:5444 + +x-ivory: &ivory + image: registry.highgo.com/ivorysql/ivorysql:5.4-bookworm + environment: &ivoryenv + MODE: pg + IVORYSQL_USER: ivorysql + IVORYSQL_PASSWORD: ivorysql + IVORYSQL_DB: testdb + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ivorysql -d testdb"] + interval: 5s + timeout: 3s + retries: 30 + +services: + ivory-shard0: + <<: *ivory + container_name: ivory-shard0 + ports: ["5443:5432"] + ivory-shard1: + <<: *ivory + container_name: ivory-shard1 + ports: ["5444:5432"] +---- + +== Usage + +=== Starting PgDog + +[source,bash] +---- +./target/release/pgdog --config ./pgdog.toml --users ./users.toml +---- + + +=== Administration Console + +PgDog provides a built-in administration database. The username and password are configured via the `[[admin]]` field in `users.toml`. + +[source,bash] +---- +psql "postgres://admin:pgdog@localhost:6433/admin" +---- + +[source,sql] +---- +-- View client connections and real-time statistics +SHOW CLIENTS + +-- View PostgreSQL connections initiated by PgDog +SHOW SERVERS + +-- View connection pool information +SHOW POOLS + +-- View the configuration currently loaded from pgdog.toml +SHOW CONFIG + +-- View connection pool statistics +SHOW STATS + +-- List of PgDog processes running on the same network. Requires service discovery to be enabled +SHOW PEERS + +-- Reload the configuration from disk. For which options can be changed at runtime, refer to pgdog.toml and users.toml +RELOAD + +-- Recreate all server connections using the existing configuration +RECONNECT + +-- Pause all connection pools. Clients will wait for a connection until the pools resume. Useful for performing a graceful restart of the PostgreSQL server +PAUSE + +-- Resume all connection pools. Clients can acquire connections again +RESUME + +-- List the prepared statements currently in the cache +SHOW PREPARED + +-- List the statements currently in the AST cache used for query routing +SHOW QUERY_CACHE + +-- Pause all queries in order to synchronize configuration changes across multiple PgDog instances +MAINTENANCE + +-- Show the PostgreSQL replication status for each database, including replica lag +SHOW REPLICATION +---- + +=== Connecting to PgDog + +[source,bash] +---- +psql "postgres://ivorysql:ivorysql@localhost:6433/ivory_shard" +---- + +=== Performing Operations + +[TIP] +Make sure the shard backends do not have an `orders` table; PgDog will create it automatically. + +[source,sql] +---- +-- Create the table +CREATE TABLE orders ( + order_id bigint, + customer_id bigint, + amount numeric(10,2), + PRIMARY KEY (order_id, customer_id) +); + +-- Insert data: these rows will be inserted into the two shard backends respectively +-- BUG: the `generate_series` function cannot be used here, because PgDog currently passes this function through transparently +INSERT INTO orders values(1, 1, 1); +INSERT INTO orders values(2, 2, 2); +INSERT INTO orders values(3, 3, 3); +INSERT INTO orders values(4, 4, 4); +INSERT INTO orders values(5, 5, 5); +INSERT INTO orders values(6, 6, 6); +INSERT INTO orders values(7, 7, 7); + +-- Query the data +SELECT * FROM orders; +---- + +=== Connecting to Each Shard Backend to Verify the Data + +[TIP] +Here you will see that the entries in the two shard backends are not evenly distributed. This is because PgDog extracts the value of the `customer_id` field configured in `[[sharded_tables]]` and applies HASH-based sharding to it. + +[source,bash] +---- +# Shard 1 +psql "postgres://ivorysql:ivorysql@localhost:5443/testdb", +# Shard 2 +psql "postgres://ivorysql:ivorysql@localhost:5444/testdb", +---- + +Run the query on each shard backend to verify the data +[source,sql] +---- +SELECT * FROM orders; +----