Database setup

Tether supports MariaDB (recommended), PostgreSQL, and SQLite. All three ship with their drivers pre-installed in requirements.txt — no extra installation needed.

Which database should I use?

MariaDB setup

With Docker (automatic)

If you use Docker Compose, MariaDB starts automatically. No setup required — the credentials from your .env are passed to the MariaDB container on first start and the database is created automatically.

With bare-metal

bashCopy
sudo apt install -y mariadb-server

# Secure the install (set root password, remove anonymous users, etc.)
sudo mysql_secure_installation

# Create the database
sudo mysql -e "CREATE DATABASE tether CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Create the user and grant access
sudo mysql -e "CREATE USER 'tether'@'localhost' IDENTIFIED BY 'yourpassword';"
sudo mysql -e "GRANT ALL PRIVILEGES ON tether.* TO 'tether'@'localhost'; FLUSH PRIVILEGES;"

# Verify
sudo mysql -u tether -pyourpassword -e "SHOW DATABASES;"

Add to your .env:

bashCopy
DB_HOST=localhost
DB_PORT=3306
DB_NAME=tether
DB_USER=tether
DB_PASSWORD=yourpassword

Tether automatically builds the connection string as:

textCopy
mysql+pymysql://tether:yourpassword@localhost:3306/tether?charset=utf8mb4

PostgreSQL setup

bashCopy
sudo apt install -y postgresql postgresql-contrib

# Create the database and user
sudo -u postgres psql -c "CREATE DATABASE tether;"
sudo -u postgres psql -c "CREATE USER tether WITH PASSWORD 'yourpassword';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE tether TO tether;"
sudo -u postgres psql -c "ALTER DATABASE tether OWNER TO tether;"

Add to your .env:

bashCopy
DATABASE_URL=postgresql://tether:yourpassword@localhost:5432/tether

AWS Aurora (MySQL-compatible)

bashCopy
DATABASE_URL=mysql+pymysql://tether:[email protected]:3306/tether?charset=utf8mb4

Aurora MySQL-compatible mode uses the same pymysql driver as MariaDB — no changes to Tether code needed.

SQLite (development only)

If neither DATABASE_URL nor DB_HOST/DB_USER are set, Tether falls back to SQLite. The database file is created at:

textCopy
$TETHER_DATA/tether.db
# e.g. ./data/tether.db

Connection priority

Tether resolves the database URL in this order:

1. DATABASE_URL environment variable — always used if set, overrides everything
2. DB_HOST + DB_USER set — builds a MariaDB URL automatically
3. Neither set — SQLite file at TETHER_DATA/tether.db

Schema management

Tether uses SQLAlchemy's create_all() on startup, which creates any missing tables or columns automatically. You do not need to run migration scripts for additive changes (new tables, new nullable columns with defaults).

For destructive changes (dropping columns, renaming tables), the release notes will include explicit SQL to run before starting the new version. These are rare and always clearly documented.

Backing up the database

See Backup & restore for complete instructions including automated cron jobs and offsite storage recommendations.