Database Configuration

This page covers [database]

Which database to connect to, how large the connection pool should be, and how many startup retries to attempt. Not sure which one to choose for a first deployment? Use SQLite. It is easy to change later.

[database]
url = "sqlite://asterdrive.db?mode=rwc"
pool_size = 10
retry_count = 3

Choose a Database Type First

• SQLite - Best for single-node, NAS, personal, or small-team deployments. It has the least operational overhead.
• PostgreSQL 14 or later - Use it if you already run PostgreSQL or want to integrate with an existing operations stack.
• MySQL 8.0.13 or later - Use it if you already use MySQL and want to keep the stack consistent.

Use SQLite for the first deployment

SQLite is enough for most scenarios. When the deployment grows, you can switch with AsterDrive’s built-in cross-database migration tool instead of being locked into the initial choice.

Database Version Support

Backend	Minimum Supported Version	Current Validation Coverage
PostgreSQL	14	PostgreSQL 14.24 passes a complete fresh migration, revision-ledger upgrade/rollback/reapply coverage, the production-database smoke suite, and real server startup. Continuous integration runs the complete integration suite on PostgreSQL 16. PostgreSQL 13.23 also completes a fresh migration, but upstream support ended on November 13, 2025, so the project support baseline starts at 14.
MySQL	8.0.13	A complete fresh migration passes on MySQL 8.0.13; 8.0.12 stops at the functional key parts used by the baseline. Continuous integration runs the complete migration and integration suites on MySQL 8.4.
MariaDB	Not yet in the support matrix	Complete fresh migrations on MariaDB 11.4.12 and 11.8.8 both stop at the same point: MariaDB does not accept the MySQL functional-key-part index syntax used by the baseline, so there is no minimum version to declare yet.

AsterDrive does not block startup based on the version string returned by the database. The table describes the boundary that the project actually supports and has validated, rather than a hard-coded runtime version allowlist. Even when a release meets the minimum version, rehearse production upgrades on a database copy, especially for large deployments.

Options

Option	Default	Purpose
url	"sqlite://asterdrive.db?mode=rwc"	Database connection string
pool_size	10	Connection pool size
retry_count	3	Number of retries when the database connection fails during startup

Common Examples

SQLite

url = "sqlite://asterdrive.db?mode=rwc"

A more common Docker example:

url = "sqlite:///data/asterdrive.db?mode=rwc"

PostgreSQL

Use PostgreSQL 14 or later; see the version-support table above for the minimum version and current validation coverage.

url = "postgres://user:password@localhost:5432/asterdrive"

When a username or password contains reserved characters such as @, :, /, ?, or #, prefer structured raw credentials. Forge injects and encodes them safely:

url = { base_url = "postgres://localhost:5432/asterdrive", username = "RAW_USERNAME", password = "RAW_PASSWORD" }

MySQL

Use MySQL 8.0.13 or later. AsterDrive migrations execute the required generated-column, index, and constraint DDL directly; see the version-support table above for the minimum version and current validation coverage.

url = "mysql://user:password@localhost:3306/asterdrive"

MySQL supports the same structured form:

url = { base_url = "mysql://localhost:3306/asterdrive", username = "RAW_USERNAME", password = "RAW_PASSWORD" }

In structured mode, username and password are raw values and must not be percent-encoded in advance; base_url must not contain userinfo. AsterDrive does not write these two fields into serialized configuration, Debug output, health details, or doctor output. Restrict access to data/config.toml; on Kubernetes, prefer mounting the complete configuration from a Secret instead of placing credentials in command arguments or ordinary logs.

Nested environment variables are also supported:

ASTER__DATABASE__URL__BASE_URL=postgres://database.internal:5432/asterdrive
ASTER__DATABASE__URL__USERNAME=RAW_USERNAME
ASTER__DATABASE__URL__PASSWORD=RAW_PASSWORD

What Happens During Startup

On every startup, AsterDrive will:

1. Open the database connection
2. Apply migrations automatically to update the schema
3. Continue starting the service

So daily upgrades do not require you to run migration commands manually.

Do Not Change url Directly When Switching Database Backends

Upgrading within the same database type is OK. Switching across database types is not.

• Normal upgrades within the same database type - restart directly, and the schema will be completed automatically
• Switching from SQLite to PostgreSQL/MySQL - do not just change url and restart

Startup migrations only “update the target database schema”; they do not move business data from the old database. For this scenario, first use the database-migrate command in the operations CLI to migrate the data, then switch the production instance.

SQLite Path Semantics

When SQLite uses a relative path, it is resolved relative to the directory containing data/config.toml.

Deployment Method	Default Location
Run locally	./data/asterdrive.db
systemd	WorkingDirectory/data/asterdrive.db
Docker (sqlite:///data/asterdrive.db?mode=rwc)	/data inside the container

For long-running deployments, write the SQLite path as a fixed directory or mount it on a persistent volume to avoid surprises from working directory changes.

How to Tune pool_size and retry_count

• Single-node or small-team deployment: keep the defaults
• External database starts slowly, such as when orchestration starts the DB later than AsterDrive: increase retry_count
• High concurrency and the database itself allows more connections: then consider increasing pool_size

Environment Variables

ASTER__DATABASE__URL="sqlite:///data/asterdrive.db?mode=rwc"
ASTER__DATABASE__POOL_SIZE=10
ASTER__DATABASE__RETRY_COUNT=3