Skip to main content
TinyCloud uses a relational database for metadata, sessions, and delegation records. Three database backends are supported.

​
Supported Databases

DatabaseConnection StringRecommended For
SQLitesqlite:./path/to/db.dbDevelopment, single-node
PostgreSQLpostgres://user:pass@host:5432/dbnameProduction
MySQLmysql://user:pass@host:3306/dbnameProduction (alternative)

​
SQLite

SQLite is the default and requires no external dependencies. Ideal for development, testing, and single-node deployments.

​
Configuration

[storage]
database = "sqlite:./data/caps.db"
Or use an in-memory database for testing: 
[storage]
database = "sqlite::memory:"

​
Environment Variable

TINYCLOUD_STORAGE__DATABASE="sqlite:./data/caps.db"
SQLite stores everything in a single file. Make sure the directory exists and is writable by the TinyCloud process (UID 1000 in Docker).

​
PostgreSQL

PostgreSQL is the recommended database for production deployments. It supports concurrent connections, replication, and scales well with traffic.

​
Configuration

[storage]
database = "postgres://tinycloud:password@localhost:5432/tinycloud"

​
Environment Variable

TINYCLOUD_STORAGE__DATABASE="postgres://tinycloud:password@localhost:5432/tinycloud"

​
Setup

1

Create the database

psql -U postgres -c "CREATE USER tinycloud WITH PASSWORD 'password';"
psql -U postgres -c "CREATE DATABASE tinycloud OWNER tinycloud;"
2

Configure TinyCloud

Set the connection string in your config or environment:
TINYCLOUD_STORAGE__DATABASE="postgres://tinycloud:password@localhost:5432/tinycloud"
3

Start TinyCloud

Migrations are applied automatically on startup. No manual migration step is needed.
docker compose up -d

​
Connection String Format

postgres://[user]:[password]@[host]:[port]/[database]
ComponentDescriptionExample
userDatabase usernametinycloud
passwordDatabase passwordpassword
hostDatabase hostlocalhost, db, 10.0.0.5
portDatabase port5432
databaseDatabase nametinycloud
In production, use strong passwords and restrict database network access. Do not expose the database port publicly.

​
MySQL

MySQL is supported as an alternative to PostgreSQL.

​
Configuration

[storage]
database = "mysql://tinycloud:password@localhost:3306/tinycloud"

​
Environment Variable

TINYCLOUD_STORAGE__DATABASE="mysql://tinycloud:password@localhost:3306/tinycloud"

​
Setup

mysql -u root -p -e "CREATE DATABASE tinycloud;"
mysql -u root -p -e "CREATE USER 'tinycloud'@'%' IDENTIFIED BY 'password';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON tinycloud.* TO 'tinycloud'@'%';"
mysql -u root -p -e "FLUSH PRIVILEGES;"

​
Automatic Migrations

TinyCloud runs database migrations automatically when the node starts. This means:
  • No manual migration commands are needed
  • Schema updates happen on deploy when you upgrade the node version
  • The node will exit with an error if migrations fail
Migration logs appear at startup. Check them if the node fails to start after an upgrade.

​
Connection Pooling

TinyCloud uses connection pooling to manage database connections efficiently:
  • Maximum connections: 100 (default)
  • Connections are shared across all concurrent requests
  • Idle connections are released back to the pool
For high-traffic deployments, ensure your database server can handle the maximum connection count. PostgreSQL’s default max_connections is typically 100, which you may need to increase: 
-- In postgresql.conf
-- max_connections = 200
ALTER SYSTEM SET max_connections = 200;

​
Choosing a Database

Best for: Development, testing, low-traffic single-node deployments.Advantages:
  • Zero configuration
  • No external dependencies
  • Single file, easy to back up
Limitations:
  • Single writer at a time
  • Not suitable for multi-node deployments
  • Performance degrades under high concurrency