Get started with QuestDB via Docker

QuestDB has images for both Linux/macOS and Windows on Docker Hub.

Install Docker#

To begin, install Docker. You can find guides for your platform on the official documentation.

Run QuestDB image#

Once Docker is installed, you will need to pull QuestDB's image from Docker Hub and create a container.

This can be done with a single command using:

docker run \
  -p 9000:9000 -p 9009:9009 -p 8812:8812 -p 9003:9003 \
  questdb/questdb:7.3.2

This command starts a Docker container from questdb/questdb image. In addition, it exposes some ports, allowing you to explore QuestDB.

In order to configure QuestDB, it is recommended to mount a volume to allow data persistance. This can be done by adding a -v flag to the above command:

-v "/host/volume/location:/var/lib/questdb"

Below each parameter is described in detail.

`-p` parameter to expose ports#

This parameter will expose a port to the host. You can specify:

-p 9000:9000 - REST API and Web Console
-p 9009:9009 - InfluxDB line protocol
-p 8812:8812 - Postgres wire protocol
-p 9003:9003 - Min health server

All ports are optional, you can pick only the ones you need. For example, it is enough to expose 8812 if you only plan to use InfluxDB line protocol.

`-v` parameter to mount storage#

This parameter will make a local directory available to QuestDB Docker container. It will have all data ingested to QuestDB, server logs and configuration.

The QuestDB root_directory is located at the /var/lib/questdb path in the container.

Docker image version#

By default, questdb/questdb points to the latest QuestDB version available on Docker. However, it is recommended to define the version used.

questdb/questdb:7.3.2

Container status#

You can check the status of your container with docker ps.

It also lists the exposed ports, container name, uptime and more:

Finding container status with docker ps

docker ps

Result of docker ps

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                NAMES
dd363939f261        questdb/questdb     "/app/bin/java -m io…"   3 seconds ago       Up 2 seconds        8812/tcp, 9000/tcp   frosty_gauss

This container:

has an id of dd363939f261
uses ports 8812 & 9000, for Postgres wire protocol and HTTP respectively
is using a questdb/questdb image
ran java to start the binary
is 3 seconds old
has been up for 2 seconds
has the unfortunate name of frosty_gauss

For full container status information, see the docker ps manual.

Debugging container logs#

Docker may generate a runtime error.

The error may not be accurate, as the true culprit is often indicated higher up in the logs.

To see the full log, retrieve the UUID - also known as the CONTAINER ID - using docker ps:

Finding the CONTAINER ID

CONTAINER ID        IMAGE               ...
dd363939f261        questdb/questdb     ...

Now pass the CONTAINER ID - or dd363939f261 - to the docker logs command:

Generating a docker log from a CONTAINER ID

$ docker logs dd363939f261
No arguments found, start with default arguments
Running as questdb user                                                                                      
Log configuration loaded from: /var/lib/questdb/conf/log.conf
...
...

Note that the log will pull from /var/lib/questdb/conf/log.conf by default.

Sharing this log when seeking support for Docker deployments will help us find the root cause.

Importing data and sending queries#

When QuestDB is running, you can start interacting with it:

Port 9000 is for REST. More info is available on the REST documentation page.
Port 8812 is used for Postgres. Check our Postgres reference page.
Port 9009 is dedicated to InfluxDB Line Protocol. Consult our InfluxDB protocol page.

Data persistence#

Mounting a volume#

Volumes can be mounted to the QuestDB Docker container so that data may be persisted or server configuration settings may be passed to an instance. The following example demonstrated how to mount the current directory to a QuestDB container using the -v flag in a Docker run command:

Mounting a volume

docker run -p 9000:9000 \
  -p 9009:9009 \
  -p 8812:8812 \
  -p 9003:9003 \
  -v "$(pwd):/var/lib/questdb" \
  questdb/questdb:7.3.2

The current directory will then have data persisted to disk for convenient migration or backups:

Current directory contents

├── conf
│   └── server.conf
├── db
├── log
├── public
└── snapshot (optional)

For details on passing QuestDB server settings to a Docker container, see the Docker section of the server configuration documentation.

For information about the file structure, see root directory.

Upgrade QuestDB version#

It is possible to upgrade your QuestDB instance on Docker when a volume is mounted to maintain data persistence.

note

Check the release notes and ensure that necessary backup is completed.
Upgrading an instance is possible only when the original instance has a volume mounted. Without mounting a volume for the original instance, the following steps create a new instance and data in the old instance cannot be retrieved.

Run docker ps to copy the container name or ID:

Container status

# The existing QuestDB version is 6.5.2:

CONTAINER ID        IMAGE                    COMMAND                  CREATED             STATUS              PORTS                NAMES
dd363939f261        questdb/questdb:6.5.2     "/app/bin/java -m io…"   3 seconds ago       Up 2 seconds        8812/tcp, 9000/tcp   frosty_gauss

Stop the instance and then remove the container:

docker stop dd363939f261
docker rm dd363939f261

Download the latest QuestDB image:

docker pull questdb/questdb:7.3.2

Start a new container with the new version and the same volume mounted:

docker run -p 8812:8812 -p 9000:9000 -v "$(pwd):/var/lib/questdb" questdb/questdb:7.3.2

Writing logs to disk#

When mounting a volume to a Docker container, a logging configuration file may be provided in the container located at /conf/log.conf:

Current directory contents

└── conf
    ├── log.conf
    └── server.conf

For example, a file with the following contents can be created:

./conf/log.conf

# list of configured writers
writers=file,stdout,http.min

# file writer
w.file.class=io.questdb.log.LogFileWriter
w.file.location=questdb-docker.log
w.file.level=INFO,ERROR,DEBUG

# stdout
w.stdout.class=io.questdb.log.LogConsoleWriter
w.stdout.level=INFO

# min http server, used monitoring
w.http.min.class=io.questdb.log.LogConsoleWriter
w.http.min.level=ERROR
w.http.min.scope=http-min-server

The current directory can be mounted:

Mounting the current directory to a QuestDB container

docker run -p 9000:9000 \
 -p 9009:9009 \
 -p 8812:8812 \
 -p 9003:9003 \
 -v "$(pwd):/root/.questdb/" questdb/questdb

The container logs will be written to disk using the logging level and file name provided in the conf/log.conf file, in this case in ./questdb-docker.log:

Current directory tree

├── conf
│  ├── log.conf
│  └── server.conf
├── db
│  ├── table1
│  └── table2
├── public
│  ├── ui / assets
│  ├── ...
│  └── version.txt
└── questdb-docker.log

For more information on logging, see the configuration reference documentation.

Restart an existing container#

Running the following command will create a new container for the QuestDB image:

docker run -p 9000:9000 \
  -p 9009:9009 \
  -p 8812:8812 \
  -p 9003:9003 \
  questdb/questdb

By giving the container a name with --name container_name, we have an easy way to refer to the container created by run later on:

docker run -p 9000:9000 \
  -p 9009:9009 \
  -p 8812:8812 \
  -p 9003:9003 \
  --name docker_questdb \
  questdb/questdb

If we want to re-use this container and its data after it has been stopped, we can use the following commands:

# bring the container up
docker start docker_questdb
# shut the container down
docker stop docker_questdb

Alternatively, restart it using the CONTAINER ID:

Starting a container by CONTAINER ID

docker start dd363939f261