How to Run YugabyteDB in Docker and Docker Compose

YugabyteDB is a PostgreSQL-compatible open-source distributed SQL database. It adds horizontal scalability to applications built for PostgreSQL while keeping familiar relational database properties (SQL, strong consistency, and ACID transactions) along with distributed-system features (auto-sharding and fault tolerance).

Because YugabyteDB is PostgreSQL-compatible (YSQL), many tools that work with PostgreSQL work with YugabyteDB as well (for example psql or pgAdmin).

YugabyteDB is versatile when it comes to data and traffic volumes. Because it provides auto-scaling, auto-sharding, and auto-balancing, you won’t have to rearchitect your system the moment it becomes too successful for the initial architecture to cope with.

It is the best fit for cloud-native OLTP (i.e. real-time, business-critical) applications that need absolute data correctness and requires at least one of the following: scalability, high tolerance to failures, and globally-distributed deployments.

YugabyteDB also supports a Cassandra-compatible API (YCQL), which can be useful for workloads that previously relied on Cassandra-style data access patterns.

In this guide, we will run a single-node YugabyteDB cluster on a local machine using Docker and Docker Compose.

Prerequisites

Before proceeding, ensure that you have Docker installed on your machine. To download and install Docker, check out the installation page.

Running YugabyteDB with Docker

To create a 1-node cluster with a replication factor (RF) of 1, first pull the Docker image (pinning a tag is recommended so your guide stays reproducible):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
$ docker pull yugabytedb/yugabyte:2.18.0.1-b4

2.18.0.1-b4: Pulling from yugabytedb/yugabyte
6cd55418c38e: Pull complete
8d173d46dac8: Pull complete
8e6321237433: Pull complete
20c6d227782e: Pull complete
061fc51f8956: Pull complete
cbdefd461ea5: Pull complete
64f07608ca74: Pull complete
866db348ded5: Pull complete
56035b96eb1b: Pull complete
7fa5a20081ec: Pull complete
77565a1d10fe: Pull complete
a34370038700: Pull complete
d033f067031c: Pull complete
04127a190dc6: Pull complete
e188da68db3d: Pull complete
8fdbb705c342: Pull complete
62006d2d98f3: Pull complete
Digest: sha256:bb5221992907b01377a21d9aa6849186e9a41d8d2e4a0c39df940259de671a97
Status: Downloaded newer image for yugabytedb/yugabyte:2.18.0.1-b4
docker.io/yugabytedb/yugabyte:2.18.0.1-b4

Once the image is downloaded, create a new container using the following docker run command:

1
2
3
4
5
6
docker run -d --name yugabyte \
    -p 7000:7000 \
    -p 9000:9000 \
    -p 5433:5433 \
    -p 9042:9042 \
    yugabytedb/yugabyte:2.18.0.1-b4 bin/yugabyted start --daemon=false

If you are running macOS (AirPlay Receiver enabled), port 7000 may already be in use. In that case, replace -p 7000:7000 with -p 7001:7000 and access the master UI at http://localhost:7001.

Below is a breakdown of the options:

-d: The detach option runs the container as a background process and displays the container ID. This option is needed to regain control of the shell since the yugabyted process is intended to be long-lived.
--name yugabyte: This option gives the container a user-friendly name that can be used later.
-p 7000:7000 -p 9000:9000 -p 5433:5433 -p 9042:9042: These options expose internal ports to the host so they can be interacted with from outside the container. These are YugabyteDB significant ports and will be discussed later.
yugabytedb/yugabyte:2.18.0.1-b4: This is the container image and version (tag) to run.
bin/yugabyted start --daemon=false: This command starts yugabyted, the parent process for YugabyteDB and passes additional options to set the base directory for the YugabyteDB data folder and directs the process to not run in the background (the default behavior which would cause the container to stop).

It is important to note that YugabyteDB is a distributed SQL database and that the image used is only a single node deployment (i.e. a replication factor of 1). This is not typical for a production environment which would usually be RF=3 or even RF=5. Running a multi-node environment locally is possible but beyond the scope of this guide.

Run the following command to check the cluster status:

1
2
3
$ docker ps
CONTAINER ID   IMAGE                        COMMAND                  CREATED          STATUS          PORTS                                                                                                                                                                                                                                                 NAMES
a857794263fb   yugabytedb/yugabyte:2.18.0.1-b4   "/sbin/tini -- bin/y..."   16 minutes ago   Up 16 minutes   0.0.0.0:5433->5433/tcp, :::5433->5433/tcp, 0.0.0.0:7000->7000/tcp, :::7000->7000/tcp, 0.0.0.0:9000->9000/tcp, :::9000->9000/tcp, 0.0.0.0:9042->9042/tcp, :::9042->9042/tcp   yugabyte

Check logs

1
2
3
4
$ docker logs -f yugabyte
Starting yugabyted...
YugabyteDB Started
Data placement constraint successfully verified

Ports and endpoints

These are the common ports you’ll use locally:

YSQL (PostgreSQL-compatible): localhost:5433
YCQL (Cassandra-compatible): localhost:9042
YB-Master UI: http://localhost:7000
YB-TServer UI: http://localhost:9000

Connecting to YugabyteDB (YSQL)

Inside the container, you can open the YSQL shell (ysqlsh):

1
docker exec -it yugabyte /home/yugabyte/bin/ysqlsh

From your host, you can also connect using psql:

1
psql -h 127.0.0.1 -p 5433 -U yugabyte

The default database user in a local YugabyteDB container is commonly yugabyte. If you changed users/passwords, use your own values.

Connecting to YugabyteDB (YCQL)

To open the YCQL shell (ycqlsh) inside the container:

1
docker exec -it yugabyte /home/yugabyte/bin/ycqlsh

Run YugabyteDB with Docker in a persistent volume

In the preceding docker run command, the data stored in YugabyteDB does not persist across container restarts. To make YugabyteDB persist data across restarts, you can add a volume mount option to the docker run command, as follows:

Create a ~/yb_data directory by executing the following command:

1
mkdir ~/yb_data

Run Docker with the volume mount option by executing the following command:

1
2
3
4
5
docker run -d --name yugabyte \
  -p 7000:7000 -p 9000:9000 -p 5433:5433 -p 9042:9042 \
  -v ~/yb_data:/home/yugabyte/yb_data \
  yugabytedb/yugabyte:2.18.0.1-b4 bin/yugabyted start \
  --base_dir=/home/yugabyte/yb_data --daemon=false

Using Docker Compose to run YugabyteDB

Using a Docker Compose file is often easier than managing multiple docker run options manually, and it makes persistence and port mappings explicit.

Save this as docker-compose.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
version: "3.9"

services:
  yugabyte:
    image: yugabytedb/yugabyte:2.18.0.1-b4
    restart: always
    command: ["bin/yugabyted", "start", "--base_dir=/home/yugabyte/yb_data", "--daemon=false"]
    ports:
      - "7000:7000"
      - "9000:9000"
      - "5433:5433"
      - "9042:9042"
    volumes:
      - yugabyte_db:/home/yugabyte/yb_data

volumes:
  yugabyte_db:

To run, use the following command:

1
docker compose up -d

Confirm that it is running as expected:

1
docker compose ps

Connecting to the Admin UI

The cluster you have created consists of two processes: YB-Master which keeps track of various metadata (list of tables, users, roles, permissions, and so on) and YB-TServer which is responsible for the actual end user requests for data updates and queries.

Each of the processes exposes its own Admin UI that can be used to check the status of the corresponding process, as well as perform certain administrative operations. The yb-master Admin UI is available at http://localhost:7000 and the yb-tserver Admin UI is available at http://localhost:9000. To avoid port conflicts, you should make sure other processes on your machine do not have these ports mapped to localhost.

Connect to the Yugabyte database

Using the YugabyteDB SQL shell, ysqlsh, you can connect to your cluster and interact with it using distributed SQL. ysqlsh is installed in the container and is located in the YugabyteDB bin directory.

1
2
3
4
5
6
7
docker exec -it yugabyte /home/yugabyte/bin/ysqlsh

# To echo queries
docker exec -it yugabyte /home/yugabyte/bin/ysqlsh --echo-queries

# You can also connect explicitly to the container hostname
docker exec -it yugabyte bash -lc 'ysqlsh --echo-queries -h $(hostname) -p 5433'

You can also connect to YugabyteDB using any PostgreSQL-compatible tool like pgAdmin.

From your favorite programming language, you can connect to Yugabyte just like you’d do for PostgreSQL.

SQL Actions

Load Sample Dataset

1
2
CREATE DATABASE yb_demo;
\c yb_demo;

Import data

1
2
3
4
5
\i share/schema.sql
\i share/products.sql
\i share/users.sql
\i share/orders.sql
\i share/reviews.sql

Run queries:

1
SELECT users.id, users.name, users.email, orders.id, orders.total FROM orders INNER JOIN users ON orders.user_id=users.id LIMIT 10;

Cleaning up

If you no longer want to run YugabyteDB, you can use these commands to clean up:

1
2
3
4
5
# Stop the container
docker stop yugabyte

# Remove the container
docker rm yugabyte

If you used a bind mount (for example ~/yb_data) and want to delete persisted data too:

1
rm -rf ~/yb_data

If you used Docker Compose and want to remove containers and volumes:

1
docker compose down -v

Conclusion

This should be enough information to get started using YugabyteDB locally in a Docker container or via Docker Compose.

Since YugabyteDB is PostgreSQL-compatible, it allows you to reuse lots of tools that you’re already familiar with.

You can easily migrate existing applications and workloads from PostgreSQL to YugabyteDB and benefit from its many features like auto-scaling capabilities.