Configure and start a Database Lab Engine instance
Define config file
All YAML features can be used, including anchors and aliases, to help you conveniently manage your configuration sections.
For instance, you can define a binding with
& and then refer to it using an alias denoted by
See config examples here
After configuring Database Lab Engine, run the following command:
sudo docker run \
--name dblab_server \
--label dblab_control \
--publish 127.0.0.1:2345:2345 \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume /var/lib/dblab:/var/lib/dblab:rshared \
--volume ~/.dblab/engine/configs:/home/dblab/configs \
--volume ~/.dblab/engine/meta:/home/dblab/meta \
--volume ~/.dblab/engine/logs:/home/dblab/logs \
--volume /sys/kernel/debug:/sys/kernel/debug:rw \
--volume /lib/modules:/lib/modules:ro \
--volume /proc:/host_proc:ro \
--publish 127.0.0.1:2345:2345 means that only local connections will be allowed.
To allow external connections, consider either using additional software such as NGINX or Envoy or changing this parameter. Removing the host/IP part (
--publish 2345:2345) allows listening to all available network interfaces.
See more details in the official Docker command-line reference.
Reconfigure Database Lab Engine
Database Lab Engine supports reconfiguration without a restart (therefore, without any downtime):
Edit the configuration file (usually,
Issue a SIGHUP signal to the main process in the DLE container – if the container name is
dblab_server, then run this (note that
killhere is not killing the process, it just sends the SIGHUP signal to it):
sudo docker exec -it dblab_server kill -SIGHUP 1
Ensure that configuration was reloaded, it should be seen in the logs (message
Configuration has been reloaded):
sudo docker logs --since 5m dblab_server
Note that not all configuration options can be reloaded. Unable to reload server API options (host and port).
Note, that by default, editing a file in Vim leads to file inode change, so your change wouldn't propagate into the container. To mitigate this issue, use
:set backupcopy=yes. For future launches of Vim, put it into
echo 'set backupcopy=yes' >> ~/.vimrc
Upgrade Database Lab Engine
Stop and remove the container using
sudo docker stop dblab_server and
sudo docker rm dblab_server After that, launch a new container.
Prior to version 3.0.0, upgrading or restarting DLE meant losing all the running clones. In DLE 3.0.0, clones became persistent: after any restart – including VM restart - existing Postgres containers are restarted as well. The same should apply to future upgrades unless a specific upgrade breaks backward compatibility (consulting release notes is advised).
Before version 3.1.0, DLE images (
postgresai/dblab-server) were based on ZFS 0.8.x. Since 3.1.0, we switched to ZFS 2.1.x.
An example of error:
"RunnerError(cmd=\"zfs clone -o mountpoint=/var/lib/dblab/dblab_pool/clones/dblab_clone_6000 [email protected]_20220712153456 dblab_pool/dblab_clone_6000 \u0026\u0026 chown -R root /var/lib/dblab/dblab_pool/clones/dblab_clone_6000\", inerr=\"exit status 1\", stderr=\"chown: /var/lib/dblab/dblab_pool/clones/dblab_clone_6000: No such file or directory\n\" exit=\"1\")"
If you need to upgrade an existing DLE setup that is running on ZFS 0.8.x, consider the following options:
Option 1: upgrade your system to use ZFS 2.1, optionally upgrade your pool (
zpool upgrade dblab_pool), and then upgrade DLE to use the default image,
Option 2: postpone the ZFS upgrade, stay on ZFS 0.8, and upgrade DLE to version 3.1 using a special image,
Observe Database Lab Engine logs
To observe the logs for Database Lab Engine running in a container (remove
--since 1m to see the log from the very beginning):
sudo docker logs --since 1m -f dblab_server
If you need to save the logs in a file:
sudo docker logs dblab_server 2>&1 | gzip > dblab_server.log.gz
When debug mode is turned on, logs may contain sensitive data such as API secret keys for the backup system.
Check Database Lab Engine status
To check the status of the running container, perform an HTTP request
GET /healthz. For example, using cURL:
curl -XGET 'http://127.0.0.1:2345/healthz'
If the instance is up and running, you will get the response with status code
HTTP/1.1 200 OK and a body like this: