Issues & Troubleshooting

Mac OS Installation

Docker/Database Issues

Make sure Docker is installed:

Download the dmg installer from: https://docs.docker.com/desktop/setup/install/mac-install/

### Database: mariadb_config error

Sometimes the plugin isn’t properly set up or can’t be found.

Check:

which mariadb

If no path is displayed:

  1. Install the connector:

    brew install mariadb-connector-c

  2. Add missing paths:

For Intel:

export PATH="/usr/local/opt/mariadb-connector-c/bin:$PATH"
export CPPFLAGS="-I/usr/local/opt/mariadb-connector-c/include"
export LDFLAGS="-L/usr/local/opt/mariadb-connector-c/lib"
export MARIADB_CONFIG=/usr/local/opt/mariadb-connector-c/bin/mariadb_config

For Apple Silicon:

export PATH="/opt/homebrew/opt/mariadb-connector-c/bin:$PATH"
export CPPFLAGS="-I/opt/homebrew/opt/mariadb-connector-c/include"
export LDFLAGS="-L/opt/homebrew/opt/mariadb-connector-c/lib"
export MARIADB_CONFIG=/opt/homebrew/opt/mariadb-connector-c/bin/mariadb_config

  1. Manually install MariaDB Python bindings:

    pip install mariadb

  2. Update your shell environment:

    source ~/.zshrc

Linux Installation

Prerequisite Libraries/Plugins

These are not installed by default, so it is helpful to ensure all Python tools are available:

sudo apt update
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install -y python3-dev python3-pip python3-venv build-essential
sudo apt install python3.11 python3.11-venv python3.11-dev -y

Install GCC:

sudo apt install build-essential -y

### Database: mariadb_config error

sudo apt install libmariadb-dev -y

Check:

mariadb_config --cflags
mariadb_config --libs

Docker Issues

After installing Docker, if you get a permissions error when running dt-db up:

sudo groupadd docker

sudo usermod -aG docker $USER

newgrp docker

  1. Verify Docker is working:

docker ps

—

Thank you for helping us improve the project!