166 lines
7.0 KiB
Markdown
166 lines
7.0 KiB
Markdown
## 简介
|
||
PolarDB-X 是一款分布式数据库系统，其核心组件由 CN、DN、GMS 和 CDC 四个部分组成，实际运行中，每个组件是一个单独的进程。
|
||
|
||
本文围绕 3 个场景介绍 PolarDB-X 的镜像使用方式。
|
||
|
||
## 1. 基于docker 快速体验 PolarDB-X
|
||
|
||
基于 PolarDB-X Docker 镜像，可快速在本地运行一个 PolarDB-X 实例并开始体验。
|
||
首先将镜像下载到本地：
|
||
|
||
```shell
|
||
docker pull polardbx/polardb-x
|
||
```
|
||
|
||
之后运行如下命令启动一个 PolarDB-X 容器，建议docker内存>=12GB (CN/DN/CDC各自分配mem_size=4096)：
|
||
|
||
```shell
|
||
docker run -d --name polardb-x -m 12GB -p 3306:8527 -v /etc/localtime:/etc/localtime polardbx/polardb-x
|
||
```
|
||
|
||
等待之后即可通过 MySQL Client 连接到 PolarDB-X ：
|
||
|
||
```shell
|
||
mysql -h127.0.0.1 -upolardbx_root -p123456
|
||
```
|
||
|
||
PolarDB-X 高度兼容 MySQL 语法，与分布式相关的特性会对 SQL 语法进行扩展，可通过以下 SQL 指令初步体验 PolarDB-X:
|
||
|
||
```mysql
|
||
# 检查GMS
|
||
select * from information_schema.schemata;
|
||
|
||
# 创建分区表
|
||
create database polarx_example mode='auto';
|
||
|
||
use polarx_example;
|
||
|
||
create table example (
|
||
`id` bigint(11) auto_increment NOT NULL,
|
||
`name` varchar(255) DEFAULT NULL,
|
||
`score` bigint(11) DEFAULT NULL,
|
||
primary key (`id`)
|
||
) engine=InnoDB default charset=utf8
|
||
partition by hash(id)
|
||
partitions 8;
|
||
|
||
insert into example values(null,'lily',375),(null,'lisa',400),(null,'ljh',500);
|
||
|
||
select * from example;
|
||
|
||
show topology from example;
|
||
|
||
# 检查CDC
|
||
show master status;
|
||
show binlog events in 'binlog.000001' from 4;
|
||
|
||
|
||
# 检查DN和CN
|
||
show storage;
|
||
show mpp;
|
||
```
|
||
|
||
以上过程在本地运行了一个 PolarDB-X 容器，容器中运行了1个CN进程，1个DN进程（该进程同时扮演GMS角色）和一个CDC进程，并且使用默认参数进行了系统初始化，初始化完成后通过8527端口对外提供服务。
|
||
|
||
## 场景2. 手工调整 docker 内组件配置
|
||
|
||
您可以通过传递环境变量 `mem_size` 来控制 CN 和 CDC 的内存占用，CN 和 CDC 会***分别***占用不超过 `mem_size(MB)` 的内存。
|
||
同时，DN 的 buffer pool size 将设置为 `0.3*mem_size` 。此外，DN 的 my.cnf 文件以及数据文件位于容器内 `/home/polarx/polardbx/build/run/polardbx-engine/data` 这个目录下。
|
||
您可以将该目录挂载到本地，然后暂停 (stop) 容器，修改 mycnf，再启动 (start) 容器。接下来，我们用一个例子说明这些配置项：
|
||
|
||
1. 首先运行 polardb-x 容器，传递 mem_size 环境变量，并将数据目录挂载到本地：
|
||
```shell
|
||
docker run -d --name polardb-x -p 3306:8527 --env mem_size=8192 -v /etc/localtime:/etc/localtime -v polardbx-data:/home/polarx/polardbx/build/run/polardbx-engine/data polardbx/polardb-x
|
||
```
|
||
上述指令，使得 CN 、DN、 CDC 分别占用不超过 8GB 内存，即一共占用不超过 24GB 内存。
|
||
同时，DN 的 `innodb_buffer_pool_size` 将设置为 `0.3*8192 MB`，最终取整为 2560MB。
|
||
|
||
2. 如果要修改 my.cnf，待容器启动后，先暂停容器的运行
|
||
```shell
|
||
docker stop polardb-x
|
||
```
|
||
|
||
3. 找到本地挂载的目录
|
||
```shell
|
||
docker volume inspect polardbx-data
|
||
```
|
||
通过上述指令找到 `Mountpoint`，进入该目录，修改其中的 `my.cnf` 然后保存
|
||
|
||
4. 最后再重新启动容器
|
||
```shell
|
||
docker start polardb-x
|
||
```
|
||
|
||
## 场景3. 基于 polardbx-sql 进行开发
|
||
|
||
polardbx-engine（即 DN ） 是 MySQL 8.x 的一个分支，可参考 MySQL 官方文档进行相关开发工作。
|
||
|
||
本文主要讲解如何用 IntelliJ IDEA + PolarDB-X Docker 镜像搭建 polardbx-sql（即 CN） 开发环境。
|
||
|
||
### 启动 DN&GMS 容器
|
||
CN 的运行依赖DN和GMS，GMS可以看做一个扮演特殊角色的DN，所以在进行CN开发时，可用一个容器同时扮演DN和GMS的角色。运行这样一个容器的命令如下：
|
||
|
||
```shell
|
||
docker run -d --name polardb-x --env mode=dev -p 4886:4886 -p 34886:34886 -v /etc/localtime:/etc/localtime -v polardb-x-data:/home/polarx/polardbx/build/run/polardbx-engine/data polardbx/polardb-x
|
||
```
|
||
|
||
该命令会启动一个名叫 polardb-x 的容器，通过环境变量 `mode` 设置容器运行模式为开发模式（即 `mode=dev`）并将 MySQL 协议端口和私有协议端口暴露出来以供 CN 使用。
|
||
数据卷映射可以将数据保存下来，以便后续使用。
|
||
`mode` 所有取值见最后一个小节。
|
||
|
||
之后开始配置 CN 相关的内容。
|
||
|
||
### 配置 server.properties
|
||
首先修改代码中 polardbx-server/src/main/resources/server.properties 文件:
|
||
|
||
1. 将`serverPort`改为 `8527`
|
||
2. 将`metaDbAddr` 改为 `127.0.0.1:4886`
|
||
3. 将`metaDbXprotoPort` 改为 `34886`
|
||
4. 将`galaxyXProtocol` 改为 `2`
|
||
5. 执行以下命令以获取`metaDbPasswd`：`docker exec polardb-x bash -c 'mysql -h127.1 -P4886 -uroot -D polardbx_meta_db_polardbx -e "select passwd_enc from storage_info where inst_kind=2"'`
|
||
6. 增加`metaDbPasswd=<查询到的密码>` 。
|
||
|
||
然后开始配置 IntelliJ IDEA 相关参数。
|
||
|
||
### 配置 IntelliJ IDEA
|
||
设置环境变量（Environment Variables） `dnPasswordKey=asdf1234ghjk5678`
|
||
由于 CN 编译过程比较耗内存，所以需要同时设置以下两个编译参数:
|
||
|
||
6. Preference-Compiler-Build process heap size 设置为 4096.
|
||
7. Preference-Build, Execution, -Build tools - maven - importing - VM options for importer 设置为 -Xmx2048m -Xms2048m.
|
||
|
||
至此 CN 的运行环境便配置好了，之后可以启动 `TddlLauncher` 进行相关开发和调试。
|
||
|
||
### 远程部署 DN，本地开发 CN
|
||
当然，上述过程也可以在远程机器上部署 docker 容器来运行 polardbx-engine，
|
||
对外开放相应端口（4886，34886），然后：
|
||
1. 修改本地的 resources/server.properties 文件中的相应 ip，
|
||
把 127.0.0.1 改成远程机器 ip。
|
||
2. 登录远程机器，执行 `docker exec -it polardb-x bash` 登进 DN 容器。
|
||
3. 修改 storage_info 的 ip 为远程机器 ip：`mysql -h127.1 -P4886 -uroot -Dpolardbx_meta_db_polardbx -e "update storage_info set ip='<远程机器 ip>'"`。
|
||
4. 本地启动 `TddlLauncher` 即可。
|
||
|
||
## 附录
|
||
|
||
### 1. mode 取值及含义
|
||
|
||
| mode 取值 | 含义 |
|
||
|----------|------------------------------------------------|
|
||
| play | 默认值，即体验模式，该模式会初始化并启动一个完整的 PolarDB-X 实例 |
|
||
| dev | 开发模式，该模式会在容器内部初始化并启动一个DN进程，该进程同时会扮演GMS角色 |
|
||
| dev-dist | (尚未支持)分布式开发模式，部分特性需要在多DN的场景下进行开发和测试，此时可以启动多个DN |
|
||
| cn | (尚未支持)cn模式，用于生产环境，该容器内仅启动一个 CN 进程 |
|
||
| dn | (尚未支持)dn模式，用于生产环境，该容器内仅启动一个 DN 进程 |
|
||
| gms | (尚未支持)gms模式，用于生产环境，该容器内仅启动一个 GMS 进程 |
|
||
| cdc | (尚未支持)cdc模式，用于生产环境，该容器内仅启动一个 CDC 进程 |
|
||
|
||
|
||
### 2. docker build
|
||
|
||
```shell
|
||
git clone https://github.com/polardb/polardbx.git
|
||
make
|
||
|
||
cd docker && sh image-build.sh /home/polarx/polardbx/build
|
||
```
|