Migrate Grafana from SQLite to PostgreSQL (2026)

Migrating Grafana’s database from SQLite to PostgreSQL is a common task, often driven by performance needs or the desire for more robust features as your monitoring scales. The core challenge lies in ensuring data integrity and minimizing downtime during the switch.

Here’s how you can approach this migration, focusing on a robust and reliable process.

The Process

Grafana provides a built-in tool for this exact purpose. You don’t need to manually export and import data; the grafana-cli utility handles the heavy lifting.

1. Preparation is Key

Backup Your Current SQLite Database: Before you do anything, back up your existing grafana.db file. This is your safety net. Locate it in your Grafana configuration directory (often /var/lib/grafana/ on Linux).

Install PostgreSQL: Ensure you have a PostgreSQL server running and accessible. You’ll need to create a dedicated database and user for Grafana.

-- Connect to your PostgreSQL server as a superuser
CREATE DATABASE grafana OWNER grafana_user;
-- Replace 'grafana_user' and 'your_strong_password' with your desired credentials
CREATE USER grafana_user WITH PASSWORD 'your_strong_password';
GRANT ALL PRIVILEGES ON DATABASE grafana TO grafana_user;

Update Grafana Configuration: You need to tell Grafana to use PostgreSQL. Edit your grafana.ini file (location varies, often /etc/grafana/grafana.ini or within the Grafana installation directory). Uncomment and configure the [database] section:
```
[database]
# type = sqlite3  <-- Comment this out or remove it
type = postgres
host = localhost:5432  # Or your PostgreSQL server IP/hostname and port
name = grafana
user = grafana_user
password = your_strong_password
ssl-mode = disable  # Or 'require' if you've set up SSL
```
Important: Make sure the host, name, user, and password exactly match your PostgreSQL setup. If PostgreSQL is on a different server, update host accordingly.

2. The Migration Command

With Grafana stopped and your configuration updated, you can run the migration command.

Stop Grafana: This is crucial to prevent any writes to the SQLite database during the migration.
```
sudo systemctl stop grafana-server
```
Run the grafana-cli Command: Navigate to your Grafana installation’s bin directory (e.g., /usr/sbin/ or /usr/local/sbin/). The command to run the migration is:
```
sudo grafana-cli --homepath "/usr/share/grafana" migrate-sql
```
- --homepath: This tells grafana-cli where your Grafana installation is. Adjust this path if yours is different. The default is often /usr/share/grafana.
- migrate-sql: This is the command that performs the database migration.
This command will read data from your existing SQLite database and insert it into the PostgreSQL database configured in grafana.ini. It handles schema changes and data transformation.

3. Verification and Restart

Check PostgreSQL for Data: You can connect to your PostgreSQL database and run some basic queries to see if tables and data have been populated.

-- Connect to your Grafana PostgreSQL database
\dt  -- List tables
SELECT count(*) FROM users; -- Check user count
SELECT count(*) FROM dashboards; -- Check dashboard count

Start Grafana:
```
sudo systemctl start grafana-server
```
Test Grafana: Access your Grafana instance in a web browser. Check your dashboards, users, data sources, and alert rules to ensure everything is present and functioning correctly.

Why This Works

The grafana-cli migrate-sql command is designed by the Grafana developers to understand the internal structure of both SQLite and PostgreSQL databases as used by Grafana. It reads the schema and data from the default SQLite location (or wherever it’s configured) and then uses the database connection details from grafana.ini to create the equivalent schema and insert the data into PostgreSQL. This ensures that all your Grafana entities – users, dashboards, data sources, preferences, API keys, and alert rules – are accurately transferred.

Common Pitfalls and Troubleshooting

Incorrect grafana.ini Configuration: Double-check host, name, user, and password. A typo here is the most frequent cause of migration failure. Ensure the PostgreSQL user has write permissions to the database.
Grafana Not Stopped: If Grafana is running, changes might occur in SQLite during the migration, leading to data inconsistencies or incomplete transfers. Always stop Grafana first.
Permissions Issues: The user running grafana-cli needs read access to the SQLite file and write access to the PostgreSQL database.
PostgreSQL Version Compatibility: While generally good, ensure your PostgreSQL version is supported by the Grafana version you are running. Refer to Grafana’s documentation for specific compatibility matrices.
Large Databases: For very large SQLite databases, the migration might take a significant amount of time. Monitor your system’s resources. You might see increased CPU and disk I/O on both the Grafana server and the PostgreSQL server.

The Next Hurdle

After successfully migrating to PostgreSQL, the next common issue you’ll encounter is optimizing PostgreSQL for Grafana’s read/write patterns, which often involves tuning shared_buffers, work_mem, and potentially setting up connection pooling.