Homarr supports three database systems: SQLite, MySQL, and PostgreSQL. This guide covers setup, migrations, and maintenance.
Supported Databases
SQLite is the default database and recommended for most users. It’s a file-based database that requires no additional setup.Advantages
- Zero configuration
- No separate database server required
- Perfect for single-instance deployments
- Easy backups (just copy the file)
Configuration
DB_DRIVER='better-sqlite3'
DB_URL='/path/to/your/database/db.sqlite'
DB_URL must be an absolute path, not a relative path.
Production Default
In production environments, if DB_URL is not set, Homarr defaults to:Setup
- Set the environment variables in your
.env file
- Start Homarr - the database file will be created automatically
- Migrations run automatically on first startup
MySQL/MariaDB is recommended for high-traffic deployments or when you need to share the database across multiple Homarr instances.Advantages
- Proven reliability at scale
- Better for multi-instance deployments
- Advanced backup and replication options
Configuration Method 1: Connection URL
DB_DRIVER='mysql2'
DB_URL='mysql://user:password@host:port/database'
DB_DRIVER='mysql2'
DB_URL='mysql://homarr:mypassword@localhost:3306/homarr'
Configuration Method 2: Individual Parameters
DB_DRIVER='mysql2'
DB_HOST='localhost'
DB_PORT='3306'
DB_USER='homarr'
DB_PASSWORD='mypassword'
DB_NAME='homarr'
Setup
- Create a database and user:
CREATE DATABASE homarr;
CREATE USER 'homarr'@'%' IDENTIFIED BY 'mypassword';
GRANT ALL PRIVILEGES ON homarr.* TO 'homarr'@'%';
FLUSH PRIVILEGES;
- Set environment variables in
.env
- Start Homarr - migrations run automatically
Requirements
- MySQL 5.7+ or MariaDB 10.2+
- InnoDB storage engine (default)
PostgreSQL is recommended for enterprise deployments requiring advanced features and strict ACID compliance.Advantages
- Advanced features and extensibility
- Excellent for complex queries
- Strong data integrity guarantees
Configuration Method 1: Connection URL
DB_DRIVER='node-postgres'
DB_URL='postgres://user:password@host:port/database'
DB_DRIVER='node-postgres'
DB_URL='postgres://homarr:mypassword@localhost:5432/homarr'
Configuration Method 2: Individual Parameters
DB_DRIVER='node-postgres'
DB_HOST='localhost'
DB_PORT='5432'
DB_USER='homarr'
DB_PASSWORD='mypassword'
DB_NAME='homarr'
Setup
- Create a database and user:
CREATE DATABASE homarr;
CREATE USER homarr WITH PASSWORD 'mypassword';
GRANT ALL PRIVILEGES ON DATABASE homarr TO homarr;
- Set environment variables in
.env
- Start Homarr - migrations run automatically
Requirements
Database Migrations
Homarr uses Drizzle ORM for database migrations. Migrations are automatically applied when Homarr starts.
Migration Files
Migrations are located in the packages/db/migrations/ directory:
packages/db/migrations/
├── sqlite/ # SQLite-specific migrations
├── mysql/ # MySQL-specific migrations
├── postgresql/ # PostgreSQL-specific migrations
└── custom/ # Custom data migrations
Automatic Migrations
Migrations run automatically in the following order:
- Schema migrations - Create/update tables and columns
- Seed data - Insert default data (groups, settings)
- Custom migrations - Data transformations and updates
You’ll see output like this on startup:
Manual Migration (Development)
For development, you can run migrations manually:
pnpm --filter @homarr/db migrate:sqlite
Custom Migrations
Homarr includes custom migrations for data transformations:
- 0000_release_widget_provider_to_options.ts - Migrates widget provider data to options format
- 0001_opnsense_credentials.ts - Updates OPNsense integration credentials
- 0002_app_widget_show_description_tooltip_to_display_mode.ts - Migrates tooltip settings to display mode
These run automatically after schema migrations.
Connection Troubleshooting
SQLite Issues
Ensure the directory exists and Homarr has write permissions:mkdir -p /path/to/database
chmod 755 /path/to/database
SQLite doesn’t support multiple concurrent writers. Ensure only one Homarr instance is using the database file.
MySQL Issues
Verify user permissions:SHOW GRANTS FOR 'homarr'@'%';
GRANT ALL PRIVILEGES ON homarr.* TO 'homarr'@'%';
FLUSH PRIVILEGES;
Check if MySQL is running and accessible:mysql -h localhost -u homarr -p
DB_HOST and DB_PORT are correct. PostgreSQL Issues
Check PostgreSQL is running:psql -h localhost -U homarr -d homarr
postgresql.conf to ensure PostgreSQL listens on the correct interface:
Backup and Restore
SQLite Backup
SQLite databases are simple files - just copy them:
# Backup
cp /path/to/db.sqlite /path/to/backup/db.sqlite.backup
# Restore
cp /path/to/backup/db.sqlite.backup /path/to/db.sqlite
Stop Homarr before backing up to ensure data consistency.
MySQL Backup
# Backup
mysqldump -u homarr -p homarr > homarr_backup.sql
# Restore
mysql -u homarr -p homarr < homarr_backup.sql
PostgreSQL Backup
# Backup
pg_dump -U homarr -d homarr > homarr_backup.sql
# Restore
psql -U homarr -d homarr < homarr_backup.sql
Database Maintenance
SQLite Maintenance
Optimize database periodically:
sqlite3 /path/to/db.sqlite 'VACUUM;'
MySQL Maintenance
Optimize tables:
OPTIMIZE TABLE table_name;
ANALYZE TABLE table_name;
PostgreSQL Maintenance
Vacuum and analyze:
Reindex for better performance:
Migrating Between Databases
To migrate from one database type to another:
- Export data from old database
- Set up new database with correct
DB_DRIVER
- Start Homarr (migrations will run)
- Use database-specific tools to migrate data
There’s no automated migration tool between different database systems. Plan carefully and test in a staging environment.
SQLite
# In SQLite shell
PRAGMA journal_mode = WAL; # Write-Ahead Logging
PRAGMA synchronous = NORMAL;
PRAGMA cache_size = 10000;
MySQL
Edit my.cnf:
innodb_buffer_pool_size = 1G
innodb_log_file_size = 256M
max_connections = 200
PostgreSQL
Edit postgresql.conf:
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 16MB
maintenance_work_mem = 128MB
Next Steps
