Quick Start
To get started with PolarDB-X, you will use the PXD tool. With PXD installed, you can run a PolarDB-X with just one-click.
Notes:
- PXD is mainly used for test or development, for production environment please use PolarDB-X Operator to deploy PolarDB-X on K8S.
Prerequisites
Deploying PolarDB-X via PXD tool requires Python3 and Docker to be installed first. Here is how they are installed for different operating systems:
PXD is only supported on x86 currently
macOS
MacBook with M1 processor is currently not supported.
1.Install Python3
If you already have python3 installed, you can skip to step 2
Check whether python3 is installed by
which python3It is recommended to use Homebrew to install python3, you can refer to the official Homebrew installation shell command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"Install python3 by brew
brew install python
2.Install Docker Desktop for Mac
See the official guide: https://docs.docker.com/desktop/mac/install/
After installation, adjust the memory to 8G:
CentOS
1.Install Python3
If you already have python3 installed, you can skip to step 2
Check whether python3 is installed by
which python3
Install python3 by yum
yum update -y
yum install -y python3
2.Install Docker
See the official guide: https://docs.docker.com/engine/install/centos/
Check whether you have the right permission by
docker psafter the installation.If you encounter the following error, see Docker Permission for a fix.
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http:///var/run/docker.sock/v1.26/images/json: dial unix /var/run/docker.sock: connect: permission denied
Ubuntu
1.Install Python3
If you already have python3 installed, you can skip to step 2
Check whether python3 is installed by
which python3
Install python3 by apt-get
apt-get update
apt-get install python3.8 python3.8-venv
2.Install Docker
See the official guide: https://docs.docker.com/engine/install/
Check whether you have the right permission by
docker psafter the installation.If you encounter the following error, see Docker Permission for a fix.
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http:///var/run/docker.sock/v1.26/images/json: dial unix /var/run/docker.sock: connect: permission denied
Windows
WSL is generally used to run PolarDB-X on Windows platforms.
1.Install WSL
See the official guide: https://docs.microsoft.com/en-us/windows/wsl/install.
Use the default Linux distribution, Ubuntu
2.Install Docker Desktop
See the official guide: https://docs.docker.com/desktop/windows/wsl/
3.Install Python3
Skip this step if you already have python3 installed
apt-get install python3
apt-get install python3-venv
4.Install pip
apt-get install python3-pip
Install PXD
NOTE: It is Recommended to use Python Virtual Environment to install PXD tool
python3 -m venv venv source venv/bin/activate
Upgrade the PIP before installation
pip install --upgrade pip
Install PXD
pip install pxd
Note: Mainland China users downloading packages from pypi is slow, you can download it from the AliCloud.
pip install -i https://mirrors.aliyun.com/pypi/simple/ pxd
Install PolarDB-X
Running the pxd tryout command to create an up-to-date version of the PolarDB-X database (with 1 node each of GMS, CN, DN, CDC).
pxd tryout
To create an instance of a specific version, you can obtain the latest image tags for each PolarDB-X component with the following command:
curl -s "https://polardbx-opensource.oss-cn-hangzhou.aliyuncs.com/scripts/get-version.sh" | sh
The output will be as follows (taking PolarDB-X V2.4.0 as an example):
CN polardbx/polardbx-sql:v2.4.0_5.4.19
DN polardbx/polardbx-engine:v2.4.0_8.4.19
CDC polardbx/polardbx-cdc:v2.4.0_5.4.19
Specify the number of CN, DN, CDC nodes and the version with the following command.
pxd tryout -cn_replica 1 -cn_version v2.4.0_5.4.19 -dn_replica 1 -dn_version v2.4.0_8.4.19 -cdc_replica 1 -cdc_version v2.4.0_5.4.19
After the PolarDB-X database is created, the connection information will be printed:
Note: The password of PolarDB-X administrator is generated randomly, and it only appears once.
You can connect to PolarDB-X through MySQL client now.
Try the following SQLs to enjoy the features of PolarDB-X. More details see: PolarDB-X SQL Manual.
# Check GMS
select * from information_schema.schemata;
# Check create database
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;
# Check CDC
show master status ;
show binlog events in 'binlog.000001' from 4;
# Check CN and DN
show storage ;
show mpp ;
Check the Status of PolarDB-X
Show a list of PolarDB-X in the current environment:
pxd list
Cleanup PolarDB-X
Cleanup all PolarDB-X instances by:
pxd cleanup
FAQ
Docker Permission
1.Create a docker group
sudo groupadd docker
2.Add User to the docker Group
sudo gpasswd -a ${USER} docker
3.Switch the Current Group to the docker Group
newgrp docker
NOTE: you can also log out and log back in
4.Check the permission by docker ps
PolarDB-X Port Usage
During the creation of PolarDB-X,
the CN, DN and GMS nodes will each occupy a randomly generated port.
If PolarDB-X fails to be created due to port conflict,
please execute pxd cleanup or pxd delete {cluster name} to clean it up and recreate it.