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:install

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:install

Container status#

You can check the status of your container with docker ps. It also lists the exposed ports:

docker ps

Result

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

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 ILP. 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:install

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:install

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:install

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, users can obtain a running container's ID with docker ps and restart it using the UUID short identifier:

Starting a container by ID

docker start dd363939f261