diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index d0e7ddec..8cae5d78 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -65,6 +65,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/ecosystem_overview.adoc b/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc index f633321f..e672ed95 100644 --- a/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc +++ b/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc @@ -34,6 +34,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库 | 21 | xref:master/ecosystem_components/pg_show_plans.adoc[pg_show_plans] | 2.1 | 显示当前所有正在运行的 SQL 语句的执行计划,支持 TEXT、JSON、YAML 等多种输出格式 | 查询性能诊断、实时执行计划监控、慢查询分析 | 22 | xref:master/ecosystem_components/pg_bulkload.adoc[pg_bulkload] | 3.1.23 | 为IvorySQL提供高速数据载入工具,可以跳过PG的共享缓存直接将数据导入表中 | 海量数据初始加载,历史数据归档,跨库迁移 | 23 | xref:master/ecosystem_components/pg_bigm.adoc[pg_bigm] | 1.2 | 为 IvorySQL 提供二元分词全文检索能力,适配中日韩文本,快速实现模糊检索与相似度查询 | 中日韩文内容、商品、地址类文字搜索场景 +| 24 | xref:master/ecosystem_components/pgdog.adoc[PgDog] | 0.1.45 | 专为 PostgreSQL 设计的高性能、开源集群中间件(代理工具),采用 Rust 语言编写 | 自动分片、连接池和负载均衡功能 |==== 这些插件均经过 IvorySQL 团队的测试和适配,确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件,进一步提升数据库系统的能力和灵活性。 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..5b2b7a34 --- /dev/null +++ b/CN/modules/ROOT/pages/master/ecosystem_components/pgdog.adoc @@ -0,0 +1,279 @@ + +:sectnums: +:sectnumlevels: 5 + += PgDog + +== 概述 +PgDog 是一个专为 PostgreSQL 设计的高性能、开源集群中间件(代理工具),采用 Rust 语言编写。它集成了自动分片、连接池和负载均衡功能,能让开发者在无需修改任何应用程序代码的前提下,实现 PostgreSQL 数据库的水平扩展与高可用管理。 + +NOTE: 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 25134d36..0aa7f354 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -65,6 +65,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/ecosystem_overview.adoc b/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc index 94fb010d..0acc14c9 100644 --- a/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc +++ b/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc @@ -35,6 +35,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o |*21*| xref:master/ecosystem_components/pg_show_plans.adoc[pg_show_plans] | 2.1 | Displays execution plans of all currently running SQL statements, supporting TEXT, JSON, and YAML output formats | Query performance diagnosis, real-time execution plan monitoring, slow query analysis |*22*| xref:master/ecosystem_components/pg_bulkload.adoc[pg_bulkload] | 3.1.23 | Provides high-speed data loading tool for IvorySQL, which directly imports data into tables bypassing PostgreSQL shared buffers | initial loading of massive data, historical data archiving and cross-database migration |*23*| xref:master/ecosystem_components/pg_bigm.adoc[pg_bigm] | 1.2 | Equips IvorySQL with bigram full-text search capability, supporting Chinese, Japanese and Korean texts to implement fuzzy retrieval and similarity query efficiently | text search for articles, commodities and addresses in CJK languages +|*24*| xref:master/ecosystem_components/pgdog.adoc[PgDog] | 0.1.45 | High-performance, open-source clustering middleware (proxy tool) designed specifically for PostgreSQL and written in Rust | Connection pooler, load balancer, distributed database. |==== These plugins have all been tested and adapted by the IvorySQL team to ensure stable operation in the IvorySQL environment. Users can select appropriate plugins based on business needs to further enhance the capabilities and flexibility of the database system. 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..fd944fe9 --- /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: PgDog uses PostgreSQL's native pg_query module to parse statements, so it currently does not support 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; +----