Config Migration Guide

This guide documents the operational workflow for migrating configuration file settings to the database using the tmi-dbtool import config mode. After migration, those settings can be changed at runtime via the admin API without restarting the server.

When to Migrate

Consider migrating settings to the database when you want to:

• Change settings at runtime without restarting the server
• Manage a fleet where individual instances need different settings but share the same config file
• Delegate settings management to administrators who use the admin API rather than editing files on disk

You do not need to migrate all settings. Infrastructure keys (database connection, logging, TLS, etc.) must always remain in the config file. See Configuration-Management for the full list of infrastructure keys.

Prerequisites

• The tmi-dbtool binary, built with make build-dbtool (or make build-dbtool-oci for Oracle)
• A running and accessible database (PostgreSQL or Oracle)
• The config file you want to migrate

Step-by-Step Workflow

1. Preview what will happen

Use --dry-run to see which settings would be migrated to the database and which would stay in the config file:

tmi-dbtool --import-config --input-file=config-production.yml --dry-run

The output lists settings in two groups:

• Infrastructure settings that will stay in the config file
• DB-eligible settings that will be written to the database

2. Run the migration

tmi-dbtool --import-config --input-file=config-production.yml --output=config-production-migrated.yml

This does two things:

1. Writes DB-eligible settings to the system_settings table
2. Generates a new config file (config-production-migrated.yml) containing only infrastructure keys

If you omit --output, the tool generates a filename automatically by appending -migrated before the file extension (e.g., config-production-migrated.yml).

3. Backup and swap

cp config-production.yml config-production.yml.backup
mv config-production-migrated.yml config-production.yml

4. Restart the server

The server will now read infrastructure settings from the config file and all other settings from the database.

What Stays in the Config File

Infrastructure keys are automatically kept in the config file during migration. These include settings for logging, observability, database connection, server bootstrap, secrets, auth bootstrap, and administrator lockout prevention. See Configuration-Management for the complete table.

Overwrite Behavior

By default, existing database settings are skipped. If a setting already exists in the system_settings table, it is left unchanged. This protects runtime changes made via the admin API.

To replace existing database values with the config file values, use the --overwrite flag:

tmi-dbtool --import-config --input-file=config-production.yml --overwrite

Encryption

If a secrets provider is configured (via the secrets.* keys in the config file), secret settings are encrypted at rest when written to the database. The tmi-dbtool initializes the encryptor automatically during config migration.

To rotate encryption keys after migration, use the admin API endpoint:

curl -X POST http://localhost:8080/admin/settings/reencrypt \
  -H "Authorization: Bearer $TOKEN"

Rollback

To roll back a migration:

1. Restore the backup config file:

   cp config-production.yml.backup config-production.yml
   

2. Restart the server.

The database settings remain in place, but the config file values take priority over database values. The server will use the config file values for any settings that exist in both places.

To fully remove the migrated settings from the database, use the admin API to delete them individually, or reset the system_settings table.

See Also

• Configuration-Management -- Three-tier priority system and infrastructure keys
• Configuration-Reference -- Full list of all configuration keys and their defaults
• Database-Tool-Reference -- Complete reference for the tmi-dbtool CLI tool