Database Setup¶

OCDocker supports PostgreSQL, MySQL, and SQLite.

Use SQLite for development, tests, and quick local experiments. Use PostgreSQL or MySQL for persistent, concurrent, or long-running workloads.

SQLite¶

export OCDOCKER_DB_BACKEND=sqlite
ocdocker doctor

Config equivalent:

DB_BACKEND = sqlite
SQLITE_PATH = /path/to/ocdocker.db

If SQLITE_PATH is omitted, OCDocker uses its default local SQLite path.

PostgreSQL¶

PostgreSQL is the default server backend.

Install and start PostgreSQL on Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql

Create the user and databases:

sudo -u postgres psql

CREATE USER ocdocker WITH PASSWORD '<db_password>';
CREATE DATABASE ocdocker OWNER ocdocker;
CREATE DATABASE optimization OWNER ocdocker;
GRANT ALL PRIVILEGES ON DATABASE ocdocker TO ocdocker;
GRANT ALL PRIVILEGES ON DATABASE optimization TO ocdocker;
\q

Config example:

DB_BACKEND = postgresql
HOST = localhost
PORT = 5432
USER = ocdocker
PASSWORD = <db_password>
DATABASE = ocdocker
OPTIMIZEDB = optimization

Install Python DB dependencies when needed:

pip install "ocdocker[db]"

MySQL¶

Install and start MySQL on Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y mysql-server
sudo systemctl enable --now mysql

Create the user and databases:

sudo mysql

CREATE DATABASE IF NOT EXISTS ocdocker
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS optimization
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'ocdocker'@'localhost' IDENTIFIED BY '<db_password>';
GRANT ALL PRIVILEGES ON ocdocker.* TO 'ocdocker'@'localhost';
GRANT ALL PRIVILEGES ON optimization.* TO 'ocdocker'@'localhost';
FLUSH PRIVILEGES;
EXIT;

If OCDocker connects from a container or another host, create the matching host grant, for example 'ocdocker'@'%', and harden the network configuration.

Config example:

DB_BACKEND = mysql
HOST = localhost
PORT = 3306
USER = ocdocker
PASSWORD = <db_password>
DATABASE = ocdocker
OPTIMIZEDB = optimization

Notes¶

PostgreSQL/MySQL require HOST, USER, PASSWORD, DATABASE, and integer PORT values when database initialization is requested.
Missing PostgreSQL/MySQL databases are created only through explicit setup intent, such as CLI paths that initialize DB storage or application code that passes create_db_if_missing=True.
For CI and local unit tests, prefer SQLite unless the test specifically targets PostgreSQL or MySQL.