Skip to main content

How to run DBLab Engine on macOS

This guide explains how to run the DBLab Engine with full ZFS support on macOS, using Colima, a lightweight Linux VM with Docker support.
All ZFS operations happen inside the Colima VM, so you don't need to install the ZFS module to your macOS.

note

This guide provides an experimental way to run DBLab Engine on macOS.

Prerequisites: Docker, Colima, Go​

First, install Homebrew, if you don't have it yet:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install Docker, Colima, and Go:

brew install docker colima go

To build the DLE binary locally, Go 1.23 or higher is required, so let's check Go version:

go version

If your Go version is older than 1.23, update it:

brew update
brew upgrade go

1. Get DBLab source code​

git clone https://gitlab.com/postgres-ai/database-lab.git
cd database-lab/engine

2. Start Colima VM​

Run Colima with enough resources and mount your project directory (adjust parameters based on available resources):

colima start --cpu 4 --memory 6 --disk 20 --mount $HOME:w

The --mount $HOME:w flag makes your home directory accessible inside Colima at /mnt/host/Users/yourname/....

3. Initialize ZFS in Colima VM​

You can either use the provided setup script or run all steps manually if you prefer better control.

# to run this, we must be in `./engine` subdirectory
colima ssh < ./scripts/init-zfs-colima.sh

This will:

  • Install zfsutils-linux if needed
  • Create a loop device-backed ZFS pool (dblab_pool)
  • Create default datasets: dataset_1, dataset_2, dataset_3

4. Build engine​

Compile DBLab Engine binary for Linux:

GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o bin/dblab-server ./cmd/database-lab/main.go

5. Build Docker image​

docker build -t dblab_server:local -f Dockerfile.dblab-server .

6. Configure your DBLab Engine​

Before running the server, create your configuration file:

cp configs/config.example.logical_generic.yml configs/server.yml

Then edit configs/server.yml and make the following changes:

  • Set the ZFS mount path to /var/lib/dblab/dblab_pool:
    mountDir: /var/lib/dblab/dblab_pool
    This should match the dataset mount path used by the ZFS pool.
  • Configure connection to the source database:
        connection:
            dbname: postgres
            host: localhost
            port: <port>
            username: postgres
            password: your_password

7. Run DBLab main container​

docker run \
  --rm \
  --name dblab_server \
  --privileged \
  --device /dev/zfs \
  -v /tmp:/tmp \
  -v /var/lib/dblab/dblab_pool:/var/lib/dblab/dblab_pool:rshared \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/run/zfs.sock:/var/run/zfs.sock \
  -v "$(pwd)/configs:/home/dblab/configs:rw" \
  -v "$(pwd)/configs/standard:/home/dblab/standard:ro" \
  -v "$(pwd)/meta:/home/dblab/meta" \
  --env DOCKER_API_VERSION=1.39 \
  -p 2345:2345 \
  dblab_server:local

Open DBLab UI​

When the main container (dblab_server) starts, it launches an additional container with UI, whose name looks like dblab_embedded_ui_xxx; it provides UI available at port 2346 by default (can be changed in server.yml).

In your browser, open http://localhost:2346.

You'll see a "refreshing" state while the engine initializes. This may take some time; please wait until the refresh is complete. Once it's done, you will be able to create snapshots, branches, clones.

8. Cleanup (optional)​

Stop the container:

docker stop dblab_server
docker rm -f dblab_server

Ensure no extra containers (UI, Postgres) that were launched by dblab_server, are present (if there are, delete them using docker rm):

docker ps -a \
  --format "ID: {{.ID}}\tName: {{.Names}}\tImage: {{.Image}}\tLabels: {{.Labels}}" \
| grep dblab

Stop Colima VM:

colima stop

Reset everything (⚠️ this wipes Colima VM, ZFS pool, images):

colima delete