Database Configuration

TeamSpeak 6 Server supports two database backends: SQLite (default) and MariaDB. This page covers configuration for both options.

Database Plugins

--db-plugin

string

default:"sqlite3"

Specifies the database plugin to use.Options: sqlite3, mariadb
Environment Variable: TSSERVER_DATABASE_PLUGIN

./tsserver --db-plugin sqlite3

SQLite Configuration

SQLite is the default database backend and requires minimal configuration. It’s ideal for small to medium-sized deployments.

SQLite-Specific Options

--db-skip-integrity-check

boolean

default:"false"

Skip database integrity check at startup. Only applicable to SQLite.Environment Variable: TSSERVER_DATABASE_SKIP_INTEGRITY_CHECK

SQLite Example

Docker Compose
CLI
YAML

docker-compose.yml

services:
  teamspeak:
    image: teamspeaksystems/teamspeak6-server:latest
    container_name: teamspeak-server
    restart: unless-stopped
    ports:
      - "9987:9987/udp"
      - "30033:30033/tcp"
    environment:
      - TSSERVER_LICENSE_ACCEPTED=accept
      - TSSERVER_DEFAULT_PORT=9987
      - TSSERVER_VOICE_IP=0.0.0.0
      - TSSERVER_FILE_TRANSFER_PORT=30033
      - TSSERVER_FILE_TRANSFER_IP=0.0.0.0
    volumes:
      - teamspeak-data:/var/tsserver

volumes:
  teamspeak-data:
    name: teamspeak-data

./tsserver \
  --accept-license \
  --db-plugin sqlite3 \
  --db-sql-create-path create_sqlite

tsserver.yaml

server:
  accept-license: accept
  
  database:
    plugin: sqlite3
    sql-create-path: create_sqlite
    client-keep-days: 30
    config:
      skip-integrity-check: 0

SQLite stores the database in a single file within the server’s data directory. No additional database server is required.

MariaDB Configuration

MariaDB is recommended for production deployments, high-availability setups, and servers with large user bases.

Connection Parameters

--db-host

string

default:"127.0.0.1"

The hostname or IP address of your database server.Environment Variable: TSSERVER_DATABASE_HOST

--db-port

integer

default:"5432"

The port used to connect to your database server. For MariaDB, use 3306.Range: 1-65535
Environment Variable: TSSERVER_DATABASE_PORT

--db-name

string

default:"teamspeak"

The name of the database to use.Environment Variable: TSSERVER_DATABASE_NAME

--db-username

string

default:""

The username for database authentication.Environment Variable: TSSERVER_DATABASE_USERNAME

--db-password

string

default:""

The password for database authentication.Environment Variable: TSSERVER_DATABASE_PASSWORD

--db-socket

string

default:""

Socket file to use for database connection (alternative to host/port).Environment Variable: TSSERVER_DATABASE_SOCKET

--db-timeout

integer

default:"10"

Timeout in seconds when connecting to the database.Range: 1-432000
Environment Variable: TSSERVER_DATABASE_TIMEOUT

--db-connections

integer

default:"10"

Number of connections to establish to the database.Range: 2-100
Environment Variable: TSSERVER_DATABASE_CONNECTIONS

MariaDB Example

Docker Compose
CLI
YAML

docker-compose.yml

services:
  teamspeak:
    image: teamspeaksystems/teamspeak6-server:latest
    container_name: teamspeak-server
    restart: unless-stopped
    ports:
      - "9987:9987/udp"
      - "30033:30033/tcp"
    environment:
      - TSSERVER_LICENSE_ACCEPTED=accept
      - TSSERVER_DEFAULT_PORT=9987
      - TSSERVER_VOICE_IP=0.0.0.0
      - TSSERVER_FILE_TRANSFER_PORT=30033
      - TSSERVER_FILE_TRANSFER_IP=0.0.0.0
      
      # Database settings
      - TSSERVER_DATABASE_PLUGIN=mariadb
      - TSSERVER_DATABASE_SQL_CREATE_PATH=create_mariadb
      - TSSERVER_DATABASE_HOST=mariadb
      - TSSERVER_DATABASE_PORT=3306
      - TSSERVER_DATABASE_NAME=teamspeak
      - TSSERVER_DATABASE_USERNAME=teamspeak
      - TSSERVER_DATABASE_PASSWORD=YourPasswordHere
    volumes:
      - teamspeak-data:/var/tsserver
    depends_on:
      mariadb:
        condition: service_healthy
  
  mariadb:
    image: mariadb:latest
    container_name: mariadb
    environment:
      - MYSQL_ROOT_PASSWORD=SuperSecretPassword
      - MYSQL_DATABASE=teamspeak
      - MYSQL_USER=teamspeak
      - MYSQL_PASSWORD=YourPasswordHere
    volumes:
      - mariadb-data:/var/lib/mysql
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  teamspeak-data:
    name: teamspeak-data
  mariadb-data:
    name: mariadb-data

./tsserver \
  --accept-license \
  --db-plugin mariadb \
  --db-host 192.168.1.10 \
  --db-port 3306 \
  --db-name teamspeak \
  --db-username tsuser \
  --db-password secretpass \
  --db-connections 10 \
  --db-sql-create-path create_mariadb

tsserver.yaml

server:
  accept-license: accept
  
  database:
    plugin: mariadb
    sql-create-path: create_mariadb
    client-keep-days: 30
    config:
      host: mariadb
      port: 3306
      name: teamspeak
      username: teamspeak
      password: YourPasswordHere
      connections: 10
      timeout: 10

Security Best Practice: Never commit database passwords to version control. Use environment variables or secrets management for production deployments.

Common Database Options

These options apply to both SQLite and MariaDB.

SQL Paths

--db-sql-path

string

default:"sql"

Path to folder containing SQL queries used by the server.Environment Variable: TSSERVER_DATABASE_SQL_PATH

--db-sql-create-path

string

default:"create_sqlite"

Subdirectory in SQL path to use for database creation scripts.Values:

create_sqlite - For SQLite
create_mariadb - For MariaDB

Environment Variable: TSSERVER_DATABASE_SQL_CREATE_PATH

The sql-create-path must match your database plugin. Use create_sqlite for SQLite or create_mariadb for MariaDB.

Client Data Retention

--db-client-keep-days

integer

default:"30"

Number of days to keep client data in the database. Older client records are automatically purged.Environment Variable: TSSERVER_DATABASE_CLIENT_KEEP_DAYS

export TSSERVER_DATABASE_CLIENT_KEEP_DAYS=90

Query Logging

--db-log-queries

boolean

default:"false"

Enable logging of all SQL queries. Useful for debugging but can impact performance.Environment Variable: TSSERVER_DATABASE_LOG_QUERIES

Only enable query logging for debugging purposes. It can generate large log files and impact server performance.

Database Maintenance

Clear Database

--clear-database

boolean

default:"false"

Resets the database completely, deleting all servers, clients, channels, and permissions.

DANGER: The --clear-database flag will permanently delete all data. Use with extreme caution and only when you intend to reset your server completely.

# This will DELETE ALL DATA
./tsserver --clear-database

Permission Updates

--no-permission-update

boolean

default:"false"

Do not apply permission changes during server updates.Environment Variable: TSSERVER_SKIP_PERMISSION_UPDATE

By default, TeamSpeak applies permission updates when upgrading to a new version. Use this flag if you have custom permission configurations that should not be modified.

Database Comparison

SQLite
MariaDB

Advantages:

Zero configuration required
No separate database server needed
Fast for small to medium deployments
Simple backup (single file)

Best For:

Small to medium servers (< 100 concurrent users)
Single-server deployments
Development and testing
Simple backup requirements

Limitations:

Single server only (no clustering)
Lower concurrent connection performance
File-based locking

Troubleshooting

Connection Issues

If the server cannot connect to MariaDB:

Verify the database server is running
Check network connectivity from the TeamSpeak server
Confirm the database user has proper permissions
Verify the database name exists
Check firewall rules allow connections on port 3306

# Test MariaDB connection
mysql -h mariadb -P 3306 -u teamspeak -p teamspeak

Database Initialization

If the database fails to initialize:

Ensure sql-create-path matches your database plugin
Verify SQL scripts exist in the specified path
Check database user has CREATE and ALTER permissions
Review server logs for specific error messages

Next Steps

Server Settings

Configure core server parameters

Ports & Networking

Set up ServerQuery and networking

Get Started

Installation

Configuration

Server Query

Operations

Advanced

Database Plugins

SQLite Configuration

SQLite-Specific Options

SQLite Example

MariaDB Configuration

Connection Parameters

MariaDB Example

Common Database Options

SQL Paths

Client Data Retention

Query Logging

Database Maintenance

Clear Database

Permission Updates

Database Comparison

Troubleshooting

Connection Issues

Database Initialization

Next Steps

Server Settings

Ports & Networking

Build docs developers (and LLMs) love

Get Started

Installation

Configuration

Server Query

Operations

Advanced

​Database Plugins

​SQLite Configuration

​SQLite-Specific Options

​SQLite Example

​MariaDB Configuration

​Connection Parameters

​MariaDB Example

​Common Database Options

​SQL Paths

​Client Data Retention

​Query Logging

​Database Maintenance

​Clear Database

​Permission Updates

​Database Comparison

​Troubleshooting

​Connection Issues

​Database Initialization

​Next Steps

Server Settings

Ports & Networking

Build docs developers (and LLMs) love

Database Plugins

SQLite Configuration

SQLite-Specific Options

SQLite Example

MariaDB Configuration

Connection Parameters

MariaDB Example

Common Database Options

SQL Paths

Client Data Retention

Query Logging

Database Maintenance

Clear Database

Permission Updates

Database Comparison

Troubleshooting

Connection Issues

Database Initialization

Next Steps