ShardingSphere-Proxy——使用手册-京东云开发者社区

本章节将介绍 ShardingSphere-Proxy 相关使用。 更多使用细节请参见使用示例。
# PROXY 启动

## 启动步骤

1. 下载 ShardingSphere-Proxy 的最新发行版。
1. 如果使用 docker，可以执行 `docker pull shardingsphere/shardingsphere-proxy` 获取镜像。详细信息请参考[Docker镜像]。
1. 解压缩后修改 `conf/server.yaml`和以 `config-` 前缀开头的文件，如：`conf/config-xxx.yaml` 文件，进行分片规则、读写分离规则配置。配置方式请参考[配置手册]。
1. Linux 操作系统请运行 `bin/start.sh`，Windows 操作系统请运行 `bin/start.bat` 启动 ShardingSphere-Proxy。如需配置启动端口、配置文件位置，可参考[快速入门]。

## 使用 PostgreSQL

1. 使用任何 PostgreSQL 的客户端连接。如: `psql -U root -h 127.0.0.1 -p 3307`

## 使用 MySQL

1. 将 MySQL 的 JDBC 驱动程序复制至目录 `ext-lib/`。
1. 使用任何 MySQL 的客户端连接。如: `mysql -u root -h 127.0.0.1 -P 3307`

## 使用自定义分片算法

当用户需要使用自定义的分片算法类时，无法再通过简单的行表达式在 YAML 文件进行配置。可通过以下方式配置使用自定义分片算法。

1. 实现 `ShardingAlgorithm` 接口定义的算法实现类。
1. 将上述 Java 文件打包成 jar 包。
1. 将上述 jar 包拷贝至 ShardingSphere-Proxy 解压后的 `conf/lib-ext` 目录。
1. 将上述自定义算法实现类的 Java 文件引用配置在 YAML 文件中，具体可参考[配置规则](/cn/user-manual/shardingsphere-proxy/configuration/)。

## 注意事项

1. ShardingSphere-Proxy 默认使用 3307 端口，可以通过启动脚本追加参数作为启动端口号。如: `bin/start.sh 3308`
1. ShardingSphere-Proxy 使用 `conf/server.yaml` 配置注册中心、认证信息以及公用属性。
1. ShardingSphere-Proxy 支持多逻辑数据源，每个以 `config-` 前缀命名的 YAML 配置文件，即为一个逻辑数据源。
# 分布式治理

ShardingSphere-Proxy 支持使用 SPI 方式接入[分布式治理](/cn/features/governance/management/)，实现配置和元数据统一管理以及实例熔断和从库禁用等功能。

## Zookeeper

ShardingSphere-Proxy 默认提供了 Zookeeper 解决方案，实现了配置中心和注册中心功能。
[配置规则](/cn/user-manual/shardingsphere-jdbc/configuration/yaml/governance/)同 ShardingSphere-JDBC YAML 保持一致。

## 其他第三方组件
详情请参考[支持的第三方组件](/cn/features/governance/management/dependency/)。

1. 使用 SPI 方式实现相关逻辑编码，并将生成的 jar 包复制至 ShardingSphere-Proxy 的 lib 目录。
1. 按照[配置规则](/cn/user-manual/shardingsphere-jdbc/configuration/yaml/governance/)进行配置，即可使用。
# 分布式事务
ShardingSphere-Proxy 接入的分布式事务 API 同 ShardingSphere-JDBC 保持一致，支持 LOCAL，XA，BASE 类型的事务。

## XA 事务

* ShardingSphere-Proxy 原生支持 XA 事务，默认的事务管理器为 Atomikos。
可以通过在 ShardingSphere-Proxy 的 `conf` 目录中添加 `jta.properties` 来定制化 Atomikos 配置项。
具体的配置规则请参考 Atomikos 的[官方文档](https://www.atomikos.com/Documentation/JtaProperties)。

* 使用 Narayana事务管理器，需要参考以下步骤。

1. 将 Narayana 所需 jar 拷贝至 `/lib` 目录。参考如下：

```xml
<propeties>
    <narayana.version>5.9.1.Final</narayana.version>
    <jboss-transaction-spi.version>7.6.0.Final</jboss-transaction-spi.version>
    <jboss-logging.version>3.2.1.Final</jboss-logging.version>
</propeties>

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>shardingsphere-transaction-xa-narayana</artifactId>
    <version>${shardingsphere.version}</version>
</dependency>
<dependency>
    <groupId>org.jboss.narayana.jta</groupId>
    <artifactId>jta</artifactId>
    <version>${narayana.version}</version>
</dependency>
<dependency>
    <groupId>org.jboss.narayana.jts</groupId>
    <artifactId>narayana-jts-integration</artifactId>
    <version>${narayana.version}</version>
</dependency>
<dependency>
    <groupId>org.jboss</groupId>
    <artifactId>jboss-transaction-spi</artifactId>
    <version>${jboss-transaction-spi.version}</version>
</dependency>
<dependency>
    <groupId>org.jboss.logging</groupId>
    <artifactId>jboss-logging</artifactId>
    <version>${jboss-logging.version}</version>
</dependency>
``` 
 
2. 在 `conf/server.yaml` 中加入如下配置：

```yaml
props:
   xa-transaction-manager-type: Narayana
```

3. 新增 `jbossts-properties.xml` 文件来定制化 Narayana 配置项，它的加载路径顺序：`user.dir (pwd)` > `user.home` > `java.home` > `classpath`。
详情请参见[Narayana官方文档](https://narayana.io/documentation/index.html)。

* 使用 Bitronix事务管理器，需要参考以下步骤。

1. 将 Bitronix 所需 jar 拷贝至 `/lib` 目录。参考如下：

```xml
<propeties>
    <btm.version>2.1.3</btm.version>
</propeties>

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>shardingsphere-transaction-xa-bitronix</artifactId>
    <version>${shardingsphere.version}</version>
</dependency>

<dependency>
    <groupId>org.codehaus.btm</groupId>
    <artifactId>btm</artifactId>
    <version>${btm.version}</version>
</dependency>
``` 
 
2. 在 `conf/server.yaml` 中加入如下配置：

```yaml
props:
   xa-transaction-manager-type: Bitronix
```

3. Bitronix 配置详情请参见[Bitronix官方文档](https://github.com/bitronix/btm/wiki)。

## BASE 事务

BASE 目前没有集成至 ShardingSphere-Proxy 的二进制发布包中，使用时需要将实现了 `ShardingTransactionManager` SPI 的 jar 拷贝至 `conf/lib` 目录，然后切换事务类型为 BASE。
# SCTL

SCTL (ShardingSphere Control Language) 为 ShardingSphere 特有的控制语句，
可以在运行时修改和查询 ShardingSphere-Proxy 的状态，目前支持的语法为：

| 语句                                     | 说明                                                                                            |
|:----------------------------------------|:------------------------------------------------------------------------------------------------|
|sctl:set transaction_type=XX             | 修改当前连接的事务类型, 支持LOCAL，XA，BASE。例：sctl:set transaction_type=XA                        |
|sctl:show transaction_type               | 查询当前连接的事务类型                                                                             |
|sctl:show cached_connections             | 查询当前连接中缓存的物理数据库连接个数                                                               |
|sctl:explain SQL                         | 查看逻辑 SQL 的执行计划，例：sctl:explain select * from t_order;                                   |
|sctl:hint set PRIMARY_ONLY=true          | 针对当前连接，是否将数据库操作强制路由到主库                                                          |
|sctl:hint set DatabaseShardingValue=yy   | 针对当前连接，设置 hint 仅对数据库分片有效，并添加分片值，yy：数据库分片值                               |
|sctl:hint addDatabaseShardingValue xx=yy | 针对当前连接，为表 xx 添加分片值 yy，xx：逻辑表名称，yy：数据库分片值                                   |
|sctl:hint addTableShardingValue xx=yy    | 针对当前连接，为表 xx 添加分片值 yy，xx：逻辑表名称，yy：表分片值                                       |
|sctl:hint clear                          | 针对当前连接，清除 hint 所有设置                                                                     |
|sctl:hint show status                    | 针对当前连接，查询 hint 状态，primary_only:true/false，sharding_type:databases_only/databases_tables |
|sctl:hint show table status              | 针对当前连接，查询逻辑表的 hint 分片值                                                               |

ShardingSphere-Proxy 默认不支持 hint，如需支持，请在 `conf/server.yaml` 中，将 `properties` 的属性 `proxy-hint-enabled` 设置为 true。