Skip to main content

How to run Database Lab Engine on macOS

This guide explains how to run the Database Lab Engine (DLE) 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 ZFS installed on your Mac.

note

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

Prerequisites​

Install Docker and Colima:

brew install docker colima

1. Clone repo & enter engine directory​

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:

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​

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 DLE 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 Database Lab​

Before running the server, create your configuration file:

cp config/config.yaml.example config/config.yaml

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

  • Set the ZFS mount path:
mountDir: /var/lib/dblab/dblab_pool

This should match the dataset mount path used by the ZFS pool.

  • Set the database connection parameters:
    connection:
        dbname: postgres
        host: localhost
        port: <port>
        username: postgres
        password: your_password

7. Run DLE 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" \
  -p 2345:2345 \
  dblab_server:local

8. Cleanup (optional)​

Stop the container:

docker rm -f dblab_server

Stop Colima VM:

colima stop

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

colima delete