quickstart.md

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 GalaxyKube 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
• CentOS
• Ubuntu
• Windows

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 python3

It 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 ps after 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 ps after 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

• You can also specify the number of CN, DN, CDC nodes and the version with the following command.

pxd tryout -cn_replica 1 -cn_version latest -dn_replica 1 -dn_version latest -cdc_replica 1 -cdc_version latest

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.