ShardingSphere-Sidecar/Scaling-京东云开发者社区

# ShardingSphere-Sidecar
## 简介

ShardingSphere-Sidecar 是 ShardingSphere 的第三个产品，目前仍然在`规划中`。
定位为 Kubernetes 或 Mesos 的云原生数据库代理，以 DaemonSet 的形式代理所有对数据库的访问。

通过无中心、零侵入的方案提供与数据库交互的的啮合层，即 Database Mesh，又可称数据网格。
Database Mesh 的关注重点在于如何将分布式的数据访问应用与数据库有机串联起来，它更加关注的是交互，是将杂乱无章的应用与数据库之间的交互进行有效地梳理。使用 Database Mesh，访问数据库的应用和数据库终将形成一个巨大的网格体系，应用和数据库只需在网格体系中对号入座即可，它们都是被啮合层所治理的对象。

![ShardingSphere-Sidecar Architecture](https://shardingsphere.apache.org/document/current/img/shardingsphere-sidecar-brief.png)

## 对比

|          | *ShardingSphere-JDBC* | *ShardingSphere-Proxy* | *ShardingSphere-Sidecar* |
| -------- | --------------------- | ---------------------- | ------------------------ |
| 数据库    | 任意                  | MySQL/PostgreSQL       | `MySQL/PostgreSQL`        |
| 连接消耗数 | 高                   | 低                     | `高`                       |
| 异构语言   | 仅Java               | 任意                    | `任意`                    |
| 性能      | 损耗低                | 损耗略高                | `损耗低`                   |
| 无中心化  | 是                    | 否                     | `是`                       |
| 静态入口  | 无                    | 有                     | `无`                       |

ShardingSphere-Sidecar 的优势在于对 Kubernetes 和 Mesos 的云原生支持。
# ShardingSphere-Scaling
ShardingSphere-Scaling 是一个提供给用户的通用的 ShardingSphere 数据接入迁移，及弹性伸缩的解决方案。

于 4.1.0 开始向用户提供，目前仍处于 Alpha 版本。
## 部署启动

1. 执行以下命令，编译生成 ShardingSphere-Scaling 二进制包：

```

git clone https://github.com/apache/shardingsphere.git；
cd shardingsphere;
mvn clean install -Prelease;
```

发布包所在目录为：`/shardingsphere-distribution/shardingsphere-scaling-distribution/target/apache-shardingsphere-${latest.release.version}-shardingsphere-scaling-bin.tar.gz`。

2. 解压缩发布包，修改配置文件 `conf/server.yaml`，这里主要修改启动端口，保证不与本机其他端口冲突，同时修改断点续传服务（可选）地址即可：

```
port: 8888
blockQueueSize: 10000
workerThread: 30

resumeBreakPoint:
  name: scalingJob
  registryCenter:
    type: ZooKeeper
    serverLists: localhost:2181
    props:
      retryIntervalMilliseconds: 10000
```

3. 启动 ShardingSphere-Scaling：

```
sh bin/start.sh
```

4. 查看日志 `logs/stdout.log`，确保启动成功。

5. 使用 curl 命令再次确认正常运行。

```
curl -X GET http://localhost:8888/scaling/job/list
```

响应应为：

```
{"success":true,"errorCode":0,"errorMsg":null,"model":[]}
```

## 结束 ShardingSphere-Scaling
   
 ```
 sh bin/stop.sh
 ```
 
## 应用配置项
 
应用现有配置项如下，相应的配置可在 `conf/server.yaml` 中修改：

| 名称           | 说明                                    | 默认值 |
| -------------- | -------------------------------------- | ------ |
| port           | HTTP服务监听端口                         | 8888   |
| blockQueueSize | 数据传输通道队列大小                      | 10000  |
| workerThread   | 工作线程池大小，允许同时运行的迁移任务线程数 | 30     |
| resumeBreakPoint   | 断点续传服务                         |        |
 
## 使用手册

### 环境要求

纯 JAVA 开发，JDK 建议 1.8 以上版本。

支持迁移场景如下：

| 源端                  | 目标端                | 是否支持 |
| --------------------- | -------------------- | ------- |
| MySQL(5.1.15 ~ 5.7.x) | ShardingSphere-Proxy | 是      |
| PostgreSQL(9.4 ~ )    | ShardingSphere-Proxy | 是      |

**注意**：

如果后端连接 MySQL 数据库，请下载 [mysql-connector-java-5.1.47.jar](https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.47/mysql-connector-java-5.1.47.jar)，并将其放入 `${shardingsphere-scaling}\lib` 目录。

### 权限要求

MySQL 需要开启 `binlog`，`binlog format` 为Row模式，且迁移时所使用用户需要赋予 Replication 相关权限。

```
+-----------------------------------------+---------------------------------------+
| Variable_name                           | Value                                 |
+-----------------------------------------+---------------------------------------+
| log_bin                                 | ON                                    |
| binlog_format                           | ROW                                   |
+-----------------------------------------+---------------------------------------+

+------------------------------------------------------------------------------+
|Grants for ${username}@${host}                                                |
+------------------------------------------------------------------------------+
|GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO ${username}@${host}     |
|.......                                                                       |
+------------------------------------------------------------------------------+
```

PostgreSQL 需要开启 [test_decoding](https://www.postgresql.org/docs/9.4/test-decoding.html)

### API接口

弹性迁移组件提供了简单的 HTTP API 接口

#### 创建迁移任务

接口描述：POST /scaling/job/start

请求体：

| 参数                                               | 描述                                                         |
| ------------------------------------------------- | ------------------------------------------------------------ |
| ruleConfiguration.source                          | 源端数据源相关配置                                             |
| ruleConfiguration.target                          | 目标端数据源相关配置                                           |
| jobConfiguration.concurrency                      | 迁移并发度，举例：如果设置为3，则待迁移的表将会有三个线程同时对该表进行迁移，前提是该表有整数型主键 |

数据源配置：

| 参数                                               | 描述                                                         |
| ------------------------------------------------- | ------------------------------------------------------------ |
| type                                              | 数据源类型（可选参数：shardingSphereJdbc、jdbc）                |
| parameter                                         | 数据源参数                                                    |

Parameter配置：

type = shardingSphereJdbc

| 参数                                               | 描述                                                         |
| ------------------------------------------------- | ------------------------------------------------------------ |
| dataSource                                        | 源端sharding sphere数据源相关配置                              |
| rule                                              | 源端sharding sphere表规则相关配置                              |

type = jdbc

| 参数                                               | 描述                                                         |
| ------------------------------------------------- | ------------------------------------------------------------ |
| name                                              | jdbc 名称                                                    |
| ruleConfiguration.targetDataSources.jdbcUrl           | jdbc 连接                                                    |
| ruleConfiguration.targetDataSources.username      | jdbc 用户                                                    |
| ruleConfiguration.targetDataSources.password      | jdbc 密码                                                    |

*** 注意 ***

当前 source type 必须是 shardingSphereJdbc

示例：

```
curl -X POST \
  http://localhost:8888/scaling/job/start \
  -H 'content-type: application/json' \
  -d '{
        "ruleConfiguration": {
          "source": {
            "type": "shardingSphereJdbc",
            "parameter": {
              "dataSource":"
                dataSources:
                  ds_0:
                    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
                    props:
                      driverClassName: com.mysql.jdbc.Driver
                      jdbcUrl: jdbc:mysql://127.0.0.1:3306/scaling_0?useSSL=false
                      username: scaling
                      password: scaling
                  ds_1:
                    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
                    props:
                      driverClassName: com.mysql.jdbc.Driver
                      jdbcUrl: jdbc:mysql://127.0.0.1:3306/scaling_1?useSSL=false
                      username: scaling
                      password: scaling
                ",
              "rule":"
                rules:
                - !SHARDING
                  tables:
                    t_order:
                      actualDataNodes: ds_$->{0..1}.t_order_$->{0..1}
                      databaseStrategy:
                        standard:
                          shardingColumn: order_id
                          shardingAlgorithmName: t_order_db_algorith
                      logicTable: t_order
                      tableStrategy:
                        standard:
                          shardingColumn: user_id
                          shardingAlgorithmName: t_order_tbl_algorith
                  shardingAlgorithms:
                    t_order_db_algorith:
                      type: INLINE
                      props:
                        algorithm-expression: ds_$->{order_id % 2}
                    t_order_tbl_algorith:
                      type: INLINE
                      props:
                        algorithm-expression: t_order_$->{user_id % 2}
                "
            }
          },
          "target": {
              "type": "jdbc",
              "parameter": {
                "username": "root",
                "password": "root",
                "jdbcUrl": "jdbc:mysql://127.0.0.1:3307/sharding_db?serverTimezone=UTC&useSSL=false"
              }
          }
        },
        "jobConfiguration":{
          "concurrency":"3"
        }
      }'
```

返回信息：

```
{
   "success": true,
   "errorCode": 0,
   "errorMsg": null,
   "model": null
}
```

#### 查询迁移任务进度

接口描述：GET /scaling/job/progress/{jobId}

示例：
```
curl -X GET \
  http://localhost:8888/scaling/job/progress/1
```

返回信息：
```
{
   "success": true,
   "errorCode": 0,
   "errorMsg": null,
   "model": {
        "id": 1,
        "jobName": "Local Sharding Scaling Job",
        "status": "RUNNING/STOPPED"
        "syncTaskProgress": [{
            "id": "127.0.0.1-3306-test",
            "status": "PREPARING/MIGRATE_HISTORY_DATA/SYNCHRONIZE_REALTIME_DATA/STOPPING/STOPPED",
            "historySyncTaskProgress": [{
                "id": "history-test-t1#0",
                "estimatedRows": 41147,
                "syncedRows": 41147
            }, {
                "id": "history-test-t1#1",
                "estimatedRows": 42917,
                "syncedRows": 42917
            }, {
                "id": "history-test-t1#2",
                "estimatedRows": 43543,
                "syncedRows": 43543
            }, {
                "id": "history-test-t2#0",
                "estimatedRows": 39679,
                "syncedRows": 39679
            }, {
                "id": "history-test-t2#1",
                "estimatedRows": 41483,
                "syncedRows": 41483
            }, {
                "id": "history-test-t2#2",
                "estimatedRows": 42107,
                "syncedRows": 42107
            }],
            "realTimeSyncTaskProgress": {
                "id": "realtime-test",
                "delayMillisecond": 1576563771372,
                "position": {
                    "filename": "ON.000007",
                    "position": 177532875,
                    "serverId": 0
                }
            }
        }]
   }
}
```

#### 查询所有迁移任务

接口描述：GET /scaling/job/list

示例：

```
curl -X GET \
  http://localhost:8888/scaling/job/list
```

返回信息：

```
{
  "success": true,
  "errorCode": 0,
  "model": [
    {
      "jobId": 1,
      "jobName": "Local Sharding Scaling Job",
      "status": "RUNNING"
    }
  ]
}
```

#### 停止迁移任务

接口描述：GET /scaling/job/stop

请求体：

| 参数      | 描述      |
| --------- | -------- |
| jobId     | job id   |

示例：
```
curl -X GET \
  http://localhost:8888/scaling/job/stop/1
```
返回信息：
```
{
   "success": true,
   "errorCode": 0,
   "errorMsg": null,
   "model": null
}
```

## 通过UI界面来操作

ShardingSphere-Scaling 与 ShardingSphere-UI 集成了用户界面，所以上述所有任务相关的操作都可以通过 UI 界面点点鼠标来实现，当然本质上还是调用了上述基本接口。

更多信息请参考 ShardingSphere-UI 项目。