pgsharding/spqr-router

SPQR Router 镜像文档

镜像概述和主要用途

SPQR（Stateless Postgres Query Router）是一个生产就绪的PostgreSQL水平扩展系统，通过分片实现查询路由。它作为透明的查询路由器，可将查询分发到多个PostgreSQL实例（分片），同时保持完整的PostgreSQL协议兼容性，使应用无需修改即可使用分片集群。

核心功能和特性

• 透明查询路由：自动将查询分发到相应分片，对应用透明
• PostgreSQL协议兼容：支持标准PostgreSQL客户端连接，无需修改应用
• 生产就绪：稳定可靠，适合生产环境部署
• 灵活的分片规则：支持基于列的分片策略，可动态配置
• 管理控制台：提供PostgreSQL协议的管理接口，便于配置分片规则
• 轻量级设计：镜像体积小（约50MB），运行时依赖少

使用场景和适用范围

• 需要对PostgreSQL进行水平扩展以处理大量数据的场景
• 高并发读写操作，需要分散负载到多个PostgreSQL实例
• 希望保持PostgreSQL兼容性，无需修改应用代码的场景
• 需动态调整分片策略的企业级应用

使用方法和配置说明

前提条件

使用SPQR Router需要先准备PostgreSQL分片实例，建议使用PostgreSQL 15及以上版本。

通过docker run启动SPQR Router实例

bash
# 创建网络
docker network create spqr-net

# 启动PostgreSQL分片
docker run -d --name shard1 --network spqr-net \
  -e POSTGRES_PASSWORD=password -e POSTGRES_USER=user1 -e POSTGRES_DB=db1 \
  postgres:15

docker run -d --name shard2 --network spqr-net \
  -e POSTGRES_PASSWORD=password -e POSTGRES_USER=user1 -e POSTGRES_DB=db1 \
  postgres:15

# 启动SPQR Router
docker run -d --name spqr-router --network spqr-net \
  -p 6432:6432 -p 7432:7432 \
  -v $(pwd)/router.yaml:/etc/spqr/router.yaml:ro \
  pgsharding/spqr-router:latest

上述命令创建了一个SPQR路由器，监听6432端口（数据查询）和7432端口（管理命令）。

通过docker compose启动

创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  shard1:
    image: postgres:15
    environment:
      POSTGRES_USER: user1
      POSTGRES_PASSWORD: password
      POSTGRES_DB: db1

  shard2:
    image: postgres:15
    environment:
      POSTGRES_USER: user1
      POSTGRES_PASSWORD: password
      POSTGRES_DB: db1

  spqr-router:
    image: pgsharding/spqr-router:latest
    ports:
      - "6432:6432"  # 路由端口
      - "7432:7432"  # 管理控制台
    volumes:
      - ./router.yaml:/etc/spqr/router.yaml:ro
    depends_on:
      - shard1
      - shard2

启动服务：

bash
docker compose up -d

配置文件说明

SPQR通过YAML文件进行配置。创建router.yaml：

yaml
host: '0.0.0.0'
router_port: '6432'
admin_console_port: '7432'

router_mode: PROXY
log_level: info

frontend_rules:
  - usr: user1
    db: db1
    pool_mode: TRANSACTION
    auth_rule:
      auth_method: ok

shards:
  shard1:
    db: db1
    usr: user1
    pwd: password
    type: DATA
    tls:
      sslmode: disable
    hosts:
      - 'shard1:5432'
  shard2:
    db: db1
    usr: user1
    pwd: password
    type: DATA
    tls:
      sslmode: disable
    hosts:
      - 'shard2:5432'

backend_rules:
  - usr: user1
    db: db1
    connection_limit: 100

配置项说明：

• host: 路由器监听地址
• router_port: 数据查询端口
• admin_console_port: 管理控制台端口
• router_mode: 路由模式（PROXY）
• log_level: 日志级别（debug/info/warn/error）
• frontend_rules: 前端连接规则，定义用户和数据库的匹配关系
• shards: 分片配置，包含各分片的连接信息
• backend_rules: 后端连接规则，定义连接限制等

配置分片规则

启动SPQR后，连接管理控制台配置分片规则：

bash
psql "host=localhost port=7432 user=user1 dbname=db1 sslmode=disable"

创建分布和定义键范围：

sql
-- 创建基于整数的分布
CREATE DISTRIBUTION ds1 COLUMN TYPES integer;

-- 将表附加到分布
ALTER DISTRIBUTION ds1 ATTACH RELATION orders DISTRIBUTION KEY id;

-- 定义键范围（1-999 → shard1，1000+ → shard2）
CREATE KEY RANGE kr1 FROM 1 ROUTE TO shard1 FOR DISTRIBUTION ds1;
CREATE KEY RANGE kr2 FROM 1000 ROUTE TO shard2 FOR DISTRIBUTION ds1;

使用SPQR Router

连接路由端口，像使用普通PostgreSQL数据库一样操作：

bash
psql "host=localhost port=6432 user=user1 dbname=db1 sslmode=disable"

执行SQL操作：

sql
CREATE TABLE orders (id INTEGER PRIMARY KEY, customer TEXT, total DECIMAL);

INSERT INTO orders VALUES (100, 'Alice', 150.00);   -- 路由到shard1
INSERT INTO orders VALUES (1500, 'Bob', 200.00);    -- 路由到shard2

SELECT * FROM orders WHERE id = 100;  -- 查询shard1
SELECT * FROM orders;                  -- 查询所有分片

环境变量

暴露端口

• 6432: 路由端口（PostgreSQL协议）- 应用程序连接此端口
• 7432: 管理控制台（PostgreSQL协议）- 配置分片规则
• 7000: gRPC API - 程序化管理和监控

镜像变体

pgsharding/spqr-router:<version>

生产环境推荐使用此镜像，包含SPQR路由器二进制文件和最小运行时依赖（约50MB）。

支持的标签

• latest, stable: 最新稳定版本
• v1.2.3, v1.2, v1: 特定版本标签
• nightly: 从master分支构建（最新功能，用于测试）
• nightly-<git-hash>: 特定夜间构建
• prerelease: 最新预发布版本（alpha、beta、rc）

用户反馈

问题反馈

如遇到镜像相关问题，请在https://github.com/pg-sharding/spqr/issues%E6%8F%90%E4%BA%A4issue%E3%80%82

如需一般使用问题和讨论，可加入我们的***聊天。

贡献

SPQR是开源项目，欢迎贡献！详情请查看https://github.com/pg-sharding/spqr%E3%80%82

许可证

SPQR源代码采用PostgreSQL全球开发组许可证分发。