Quick start: YugabyteDB on Docker containers

If you're looking for a resilient distributed SQL database that can handle node failure, online maintenance, and linear scale-out, then you might want to give YugabyteDB a try. It's an open-source database that's compatible with PostgreSQL applications. You can easily get started with it by using Docker.

This post will use the latest YugabyteDB Docker image and PostgreSQL image (to connect with psql:

docker pull yugabytedb/yugabyte
docker pull postgres        

The following command starts a Docker container with YugabyteDB (or Podman if preferred) to get the first node of our cluster:

# start a single-node YugabyteDB cluster and remember cluster name
yb=$(
 docker run -d -p15433:15433 -p5433:5433 yugabytedb/yugabyte yugabyted start --background=false
)

# check that PostgreSQL endpoint is available
until docker run --rm -i --link $yb:yb yugabytedb/yugabyte postgres/bin/pg_isready -h yb -p 5433 ;  do sleep 1 ; done | uniq        

To connect to a container using docker --link , I store its name in a variable. Though it's advisable to create a network and use --network --hostname , I'm using the simplest command lines in this blog post.

The UI is available at https://localhost:15433, and the PostgreSQL endpoint is on port 5433. I can also connect from any PostgreSQL client in a container.

docker run --rm -it --link $yb:yb postgres psql -h yb -p 5433 -U postgres -d yugabyte -c "select host,port,node_type from yb_servers()"        

The above query displays the list of nodes that are present in the cluster.

To expand a cluster, connect new nodes to it by using the address of an existing node. The new nodes will automatically discover their IP addresses. Once the cluster has a minimum of three nodes, it will switch to Replication Factor 3, making it resilient to the failure of one node.

docker run -d --link $yb:yb -p5434:5433 yugabytedb/yugabyte yugabyted start --background=false --join yb 

docker run -d --link $yb:yb -p5435:5433 yugabytedb/yugabyte yugabyted start --background=false --join yb         

The only difference when starting the first node is the use of --join to join the cluster.

To connect randomly to one of the nodes using the exposed ports on the host, you can utilize PGLOADBALANCEHOSTS. In order to do so, you need to have PostgreSQL 16 client installed. You will also need to provide a list of PGHOST and PGPORT.

PGLOADBALANCEHOSTS=random PGHOST=localhost,localhost,localhost PGPORT=5433,5434,5435 PGUSER=yugabyte PGDATABASE=yugabyte psql -c "show listen_addresses"        

This connects to the 3 ports defined:

There are advanced possibilities for load balancing with the YugabyteDB smart drivers for YSQL (from a container, not though port redirection as the database is unaware of them - Smart Drivers use what you see in yb_servers() view).

If you need to migrate a PostgreSQL application, certain configuration parameters can be used to achieve the same behavior. These parameters can be stored in a file:

cat > ./tserver.flags <<GFLAGS
--ysql_colocate_database_by_default=true
--ysql_sequence_cache_minval=1
--yb_enable_read_committed_isolation=true
--enable_deadlock_detection=true
--enable_wait_queues=true
--ysql_beta_features=true
--ysql_yb_bnl_batch_size=1024
--ysql_pg_conf_csv=\
yb_enable_optimizer_statistics=on,yb_enable_base_scans_cost_model=on
GFLAGS        

When starting each docker container, --tserver_flags=flagfile is used to read parameters from this file. For example, the first node could have been started as:

docker run -d -p15433:15433 -p5433:5433 \
-v $PWD/tserver.flags:/tmp/tserver.flags yugabytedb/yugabyte yugabyted start --background=false --tserver_flags=flagfile=/tmp/tserver.flags        

The user interface displays all the information you need to know about your cluster:

This is for a simple quick start. If you stop the containers and restart them their IP addresses may change, which is not ideal for a cluster. Then better start with a static IP address: Docker container with fixed IP address - DEV Community

As a Developer Advocate, I would be happy to receive your feedback and answer your questions, either here or on our community Slack. You can also follow and contact me on ??: https://twitter.com/FranckPachot