Skip to main content
This guide covers migrating your Homarr instance between different database systems, upgrading to new versions, and handling breaking changes safely.

​
Database Migration Overview

Homarr supports three database types:

SQLite

better-sqlite3Best for:
  • Single-user instances
  • Low traffic
  • Simple setup

MySQL

mysql2Best for:
  • Multi-user environments
  • Higher traffic
  • Shared hosting

PostgreSQL

node-postgresBest for:
  • Enterprise deployments
  • Advanced features
  • High concurrency
You may need to migrate when:
  • Scaling from SQLite to a more robust database
  • Moving to a managed database service
  • Consolidating with existing database infrastructure
  • Performance optimization

​
Pre-Migration Checklist

Before starting a migration:
1

Backup Everything

Create a complete backup of your current system:
  • Database backup
  • Configuration files (.env, docker-compose.yml)
  • Data directory
See the Backup and Restore Guide for detailed instructions.
Never attempt a migration without a tested backup. Ensure you can restore from backup before proceeding.
2

Document Current Configuration

Record your current setup:
  • Database type and version
  • Homarr version
  • Environment variables
  • Custom configurations
3

Test in Development

If possible, test the migration process in a development environment first to identify potential issues.
4

Plan Downtime

Schedule migration during low-usage periods. Inform users of expected downtime.

​
Migrating Between Database Types

Homarr uses Drizzle ORM for database management, which handles schema differences between database types automatically.

​
Migration Strategy

The recommended approach is to:
  1. Export data from the old database
  2. Set up the new database
  3. Run migrations on the new database
  4. Import data into the new database
Direct database-to-database migration tools (like pg_dump | mysql) won’t work due to schema differences. You’ll need to export and import data through Homarr or use database-specific tools.

​
SQLite to MySQL/PostgreSQL

1

Export Data from SQLite

Create a complete backup of your SQLite database:
# Stop Homarr
docker compose down

# Backup SQLite database
cp /path/to/db.sqlite /path/to/backups/db-backup.sqlite
2

Set Up New Database

Install and configure your target database (MySQL or PostgreSQL).MySQL Example:
# docker-compose.yml
services:
  db:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: homarrdb
      MYSQL_USER: homarr
      MYSQL_PASSWORD: homarr_password
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:
PostgreSQL Example:
# docker-compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: homarrdb
      POSTGRES_USER: homarr
      POSTGRES_PASSWORD: homarr_password
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
3

Update Homarr Configuration

Modify your .env file to point to the new database:For MySQL:
DB_DRIVER='mysql2'
DB_URL='mysql://homarr:homarr_password@db:3306/homarrdb'
For PostgreSQL:
DB_DRIVER='node-postgres'
DB_URL='postgres://homarr:homarr_password@db:5432/homarrdb'
Keep your SECRET_ENCRYPTION_KEY unchanged! Changing this will make encrypted integration data unrecoverable.
4

Run Migrations

Start Homarr to run automatic migrations on the new database:
docker compose up -d

# Watch logs for migration progress
docker compose logs -f homarr
You should see messages like:
Migration complete
Created group 'everyone' through seed
Created onboarding step through seed
5

Migrate Data

Currently, Homarr doesn’t include a built-in tool for data migration between database types. You have two options:Option A: Manual Recreation (Small Instances)
  • Manually recreate boards, widgets, and settings in the new instance
  • Use this for small configurations
Option B: Custom Migration Script (Large Instances)
  • Export data from SQLite to JSON
  • Write a script to import JSON into the new database
  • See the migration script examples below

​
Migration Script Example

For advanced users, here’s an example of exporting data from SQLite: 
// export-data.js
import Database from 'better-sqlite3';
import fs from 'fs';

const db = new Database('db.sqlite', { readonly: true });

const tables = [
  'user',
  'group',
  'groupMember',
  'board',
  'item',
  'integration',
  'serverSetting',
];

const data = {};

for (const table of tables) {
  const rows = db.prepare(`SELECT * FROM ${table}`).all();
  data[table] = rows;
}

fs.writeFileSync('homarr-export.json', JSON.stringify(data, null, 2));
console.log('Export complete!');
Consider reaching out to the Homarr community on Discord for migration assistance. Others may have created migration tools you can use.

​
MySQL to PostgreSQL (or vice versa)

The process is similar to SQLite migration:
  1. Backup current database
  2. Set up new database
  3. Update .env with new connection details
  4. Run migrations
  5. Migrate data using export/import or custom scripts

​
Upgrading Homarr Versions

Homarr uses semantic versioning: MAJOR.MINOR.PATCH (e.g., 0.15.3)

​
Upgrade Types

Risk Level: LowPatch releases contain:
  • Bug fixes
  • Security patches
  • Minor improvements
No breaking changes. Safe to upgrade directly.
Risk Level: MediumMinor releases may contain:
  • New features
  • Database schema changes
  • Deprecated features
  • Performance improvements
Usually safe, but review release notes for migration notes.
Risk Level: HighMajor releases may contain:
  • Breaking changes
  • Significant architecture changes
  • Removed features
  • Major database schema changes
Requires careful planning and testing.

​
Standard Upgrade Procedure

1

Check Release Notes

Review the changelog for:
  • Breaking changes
  • Migration instructions
  • New features
  • Known issues
2

Backup Current Instance

Create a complete backup before upgrading:
# Backup database
docker compose exec -T db mysqldump -u homarr -p homarrdb > backup-pre-upgrade.sql

# Backup configs
cp .env .env.backup
cp docker-compose.yml docker-compose.backup.yml
3

Update Version

Update the Homarr version in your Docker Compose file:
services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest  # or specific version like 0.15.3
Or for Docker:
docker pull ghcr.io/homarr-labs/homarr:latest
4

Stop Current Instance

docker compose down
5

Start Updated Instance

docker compose up -d

# Monitor logs for migration progress
docker compose logs -f homarr
Database migrations run automatically on startup.
6

Verify Upgrade

Check that:
  • Application starts successfully
  • Database migrations completed
  • All boards load correctly
  • Widgets function properly
  • Integrations still work

​
Rolling Back an Upgrade

If the upgrade fails:
1

Stop the New Version

docker compose down
2

Restore Configuration

cp .env.backup .env
cp docker-compose.backup.yml docker-compose.yml
3

Restore Database

# MySQL example
mysql -u homarr -p homarrdb < backup-pre-upgrade.sql

# PostgreSQL example
psql -U homarr -d homarrdb < backup-pre-upgrade.sql
4

Start Previous Version

docker compose up -d

​
Handling Database Migrations

​
Automatic Migrations

Homarr automatically runs database migrations on startup using Drizzle ORM. Migration Process:
  1. Homarr starts
  2. Checks current database schema version
  3. Applies pending migrations in order
  4. Seeds default data if needed
  5. Runs custom migrations
You’ll see logs like: 
Migration complete
Created group 'everyone' through seed
Created 3 default search engines through seeding process

​
Manual Migration Execution

For advanced scenarios, you can run migrations manually: SQLite: 
node packages/db/migrations/sqlite/migrate.js ./migrations
MySQL: 
node packages/db/migrations/mysql/migrate.js ./migrations
PostgreSQL: 
node packages/db/migrations/postgresql/migrate.js ./migrations

​
Custom Migrations

Homarr includes custom migrations for complex data transformations. These are located in packages/db/migrations/custom/. Example custom migrations:
  • 0000_release_widget_provider_to_options.ts - Migrates release widget settings
  • 0001_opnsense_credentials.ts - Updates OPNsense integration format
  • 0002_app_widget_show_description_tooltip_to_display_mode.ts - Updates app widget settings
Custom migrations run after standard schema migrations.

​
Handling Breaking Changes

Breaking changes are documented in release notes. Common types include:

​
Configuration Changes

Example: Environment Variable Renamed Old: 
DB_CONNECTION_STRING='sqlite://./data/db.sqlite'
New: 
DB_URL='sqlite://./data/db.sqlite'
Migration: Update your .env file with the new variable name.

​
Widget Configuration Changes

Some updates change how widgets store their configuration. Example: Display Mode Migration The custom migration 0002_app_widget_show_description_tooltip_to_display_mode.ts automatically converts: 
// Old format
{ showDescriptionTooltip: true }

// New format
{ displayMode: 'tooltip' }
These conversions happen automatically during migration.

​
API Changes

If you use Homarr’s tRPC API, breaking changes may affect your integrations. Migration: Review the API changelog and update your API calls accordingly.

​
Removed Features

Occasionally, features may be removed or replaced. Migration:
  • Check release notes for alternatives
  • Update your configuration to use replacement features
  • Remove references to deprecated features

​
Migration Best Practices

Test First

  • Always test migrations in a development environment
  • Verify all features work after migration
  • Document any issues encountered
  • Plan for rollback if needed

Backup Everything

  • Full database backup before migration
  • Configuration file backups
  • Test restoration before proceeding
  • Keep multiple backup versions

Version Control

  • Track configuration changes in git
  • Document migration steps
  • Keep notes on issues and resolutions
  • Share knowledge with your team

Gradual Rollout

  • Upgrade patch versions regularly
  • Don’t skip multiple minor versions
  • Read all intermediate release notes
  • Plan major upgrades carefully

​
Troubleshooting Migrations

Cause: Database schema is out of sync with expected state.Solution:
  1. Check if you skipped versions
  2. Review database schema manually
  3. Restore from backup and re-run migration
  4. Contact support if issue persists
Cause: Migration script may have data transformation issues.Solution:
  1. Stop Homarr immediately
  2. Restore from backup
  3. Check migration logs for errors
  4. Report issue on GitHub with logs
Cause: Database indexes may need rebuilding.Solution:
-- MySQL
ANALYZE TABLE board, item, widget;

-- PostgreSQL
VACUUM ANALYZE;
Cause: SECRET_ENCRYPTION_KEY changed or is missing.Solution:
  1. Verify SECRET_ENCRYPTION_KEY in .env matches original
  2. If key was lost, you’ll need to reconfigure integrations
  3. Integration secrets are encrypted and can’t be recovered without the original key

​
Version-Specific Migration Notes

​
Upgrading to 0.15.x

  • New board layout system with sections
  • Widget configuration format updated
  • Custom migrations handle most conversions automatically
  • Review widget settings after upgrade

​
Upgrading to 0.14.x

  • Introduction of integration permissions system
  • Group-based access control
  • May require reassigning user permissions
Always check the specific release notes for the version you’re upgrading to. Version-specific instructions may override general guidance.

​
Next Steps

Backup Guide

Learn comprehensive backup strategies

Database Configuration

Configure database connections and settings

Troubleshooting

Get help with migration issues

Release Notes

View all version releases and changelogs

Build docs developers (and LLMs) love

Get started for freeTalk to us