Why the Grafana 9 to 10 upgrade needs planning before the binary changes
The Grafana 9 to 10 upgrade is mostly a permissions and identity exercise, not a binary swap. A self-hosted Grafana 9 instance often carries years of folder permissions, team memberships and login habits that teams depend on daily, and Grafana 10.0 changes how several of those behave. Before you schedule the change, inventory who signs in, how they authenticate, and which dashboards and folders rely on permissions that will be evaluated differently afterward.
Two changes in 10.0 drive most of the planning. Role-based access control is always on in 10.0 and cannot be turned off, so any permission model you currently run in legacy mode must be validated under RBAC before the upgrade. Usernames and email addresses also become case-insensitive, which matters if your users are not on MySQL, because identity conflicts can appear at login. Check for accounts that differ only by letter case, and review the user identity conflict tool described in the 10.0 upgrade guide before any users are affected.
Treat timing and the starting point as decisions to confirm, not defaults. Grafana's upgrade guidance describes major releases once a year in April or May, minor releases every other month, and patch releases at least monthly, with each minor supported for 9 months and the last minor of a major for 15 months. Confirm the minimum 9.x version that the 10.0 upgrade guide supports for your path, and schedule the move so that your current 9.x release still receives support while you test.
What changes in Grafana 10 and what each change requires
This table lists the Grafana 10.0 changes that affect a 9.x upgrade, the impact of each on users and data, and the action to take before or after the upgrade. Read each row against your current authentication setup, database engine and any downgrade history, since those determine how much work applies to you.
| Change | Impact | Action needed |
|---|---|---|
| RBAC always on | Role-based access control is enabled in 10.0 and cannot be turned off, so permissions behave under the RBAC model after the upgrade. | Review existing teams, roles and folder permissions in a test copy before upgrading, and confirm who needs which access afterward. |
| Case-insensitive usernames and emails | Usernames and email addresses are treated without regard to case, which can change how existing accounts match at login. | Search your user table for names or emails that differ only by case before upgrading. |
| Identity conflicts outside MySQL | Users on databases other than MySQL may hit login identity conflicts once case is ignored. | Run the Grafana CLI user identity conflict tool to find and resolve conflicts before upgrading, as described in the 10.0 upgrade guide. |
| Removed dashboard previews | Dashboard preview images are no longer shown as part of the 10.0 change set. | Confirm the exact removal details and any replacement in the 10.0 upgrade guide, and tell dashboard owners what they will see. |
| Downgrade and re-upgrade cleanup | After a downgrade with RBAC disabled, legacy and RBAC permissions can fall out of sync and cause access errors on re-upgrade. | Back up the database, run the SQL cleanup queries from the 10.0 upgrade guide before re-upgrading, and verify permissions afterward. |
Where identity conflicts appear: MySQL versus other databases
The 10.0 upgrade guide singles out installations that are not on MySQL for identity conflicts, so MySQL is the case where you should confirm the exposure first rather than assume it. Do not read this tab as a guarantee of safe behavior on MySQL. It simply describes what the guide flags for other databases, and you should still check your own user table before upgrading.
- Inventory mixed-case accounts: List usernames and email addresses that contain uppercase letters, since these are the values that matter once matching becomes case-insensitive.
- Check duplicate addresses: Look for two accounts whose emails differ only by case, and for the same address appearing in more than one directory.
- Note the login source: Record whether each account was created through LDAP, generic OAuth, or auth proxy, because the directory is often the place where the second identity came from.
- Test in a copy: Restore a copy of the database into a non-production Grafana, upgrade it to 10.x, and attempt logins for the flagged accounts.
- Run the tool when needed: Use the Grafana CLI user identity conflict tool to resolve any conflicts you find before the production upgrade, and record each decision.
Confirm your MySQL version and collation settings with your database team, and treat the result of the copy test as the basis for your go or no-go decision.
The 10.0 upgrade guide states that users not on MySQL may hit identity conflicts at login. PostgreSQL installations therefore fall into the group the guide warns about, and the inventory should be completed before the upgrade window opens. The concern is two accounts that were distinct under case-sensitive matching becoming one account under the new rules.
- Inventory mixed-case accounts: Query the user table for usernames and emails with uppercase characters and export the list for review.
- Check duplicate addresses: Compare emails in a case-insensitive way to find pairs that would collide after the upgrade.
- Note the login source: Identify accounts created through LDAP, generic OAuth, or auth proxy, and check whether the upstream directory treats the two spellings as the same person.
- Test in a copy: Take a backup, restore it to a staging instance on the same PostgreSQL major version, upgrade, and log in with each affected account.
- Run the tool when needed: Run the user identity conflict tool against the staging copy first, and only then against production, keeping the output with your change record.
Confirm with your team which PostgreSQL version and backup method you will use for the staging restore.
SQLite is the default backend for a single-node install, and the guide's warning about non-MySQL databases applies to it as well. The database is a single file, so the inventory and test steps are simpler to run, but the same identity conflicts can appear at login. SQLite is not supported for production or high availability, so any conflict found here is also a sign to plan a move to MySQL or PostgreSQL.
- Inventory mixed-case accounts: Open a copy of
grafana.dbread-only and query the user table for uppercase usernames and emails. - Check duplicate addresses: Look for emails that match when case is ignored, including accounts that were created by different login methods.
- Note the login source: Record whether each account came from LDAP, generic OAuth, or auth proxy, since these sources often supply the second identity.
- Test in a copy: Stop the service, copy
grafana.dbwith the service stopped, run the upgrade against the copy, and test logins. - Run the tool when needed: Use the user identity conflict tool on the copy before touching the live file, and keep a backup of the original database.
Confirm your backup and restore procedure with the person who owns the host, since a copy taken while Grafana is running can be inconsistent.
What to prepare before touching the 10.0 binary
Most Grafana 9 to 10 upgrade problems start before the binary changes. The cards below cover the backups, inventories and staging work that make the upgrade reversible and make identity changes predictable. Work through them in order, because the identity audit and dependency list depend on the inventory.
Full database and config backup
Take a complete copy of the Grafana database, whether that is grafana.db on SQLite or the MySQL or PostgreSQL database, along with grafana.ini, environment overrides and all provisioning files. A backup is only useful if it restores cleanly, so record the Grafana version and database engine next to it. Confirm the exact backup procedure for your deployment method: package, container or Helm chart.
Inventory of users, teams and permissions
Export the users, teams, folders and dashboard and data source permissions that role-based access control will now govern. In 10.0, RBAC is always on, so permissions that worked through legacy settings must map to RBAC roles. Record who holds admin or editor rights today so you can confirm the same people keep access after the upgrade.
Identity audit for case collisions
Grafana 10.0 makes usernames and email addresses case-insensitive. List accounts whose login or email differs only by letter case, such as Alice@Example.com and alice@example.com. Databases other than MySQL may hit identity conflicts at login, so resolve duplicates before the upgrade using the Grafana CLI user identity conflict tool.
Dependencies on user and permission state
List every data source, plugin, dashboard link and alert rule that relies on user identity, team membership or folder permissions. Include API tokens, service accounts and provisioned alert routing that refers to named users. These items may fail or change behavior once permissions are enforced through RBAC, so note the owner and expected access for each one before the upgrade window.
Staging copy from a recent backup
Restore a recent backup into a staging instance that matches production's database engine, plugins and provisioning. Run the 10.0 upgrade there first and check logins, permissions, dashboards and alert evaluation. Staging is also where you test the downgrade and re-upgrade path, since that path has its own SQL cleanup steps. Keep staging on the same network controls as production so data source connectivity is tested too.
Rollback owner and window in writing
Name one person who can declare a rollback and the time window in which a rollback is still practical. Write down the restore steps, who holds the backup, and how users will be told about downtime. If you roll back to 9.x, RBAC must be disabled before the upgrade is repeated, and the SQL cleanup queries in the guide must run first. Agree on these steps in writing before work starts.
How to sequence the upgrade with checks and rollback points
This sequence moves a Grafana 9 instance to 10.0 through a staging copy first, so identity conflicts and permission changes surface before production users are affected. Each step closes with a check and names the rollback point that still exists.
Freeze changes and confirm the backup
Pause dashboard, folder, user and data source edits for the duration of the work, and tell the users and administrators who edit Grafana that the freeze has started. Take a backup of the database (SQLite, MySQL or PostgreSQL), the configuration files and the plugin directory, then restore that backup to a separate test host to confirm it is readable. The step is done when the restore test completes and someone other than the person who took the backup has signed off on it. The backup is the rollback point for everything that follows, so keep it until production has been stable for a period you agree in advance.
Upgrade a staging copy and run identity checks
Build a staging Grafana 9 instance from the production backup, then upgrade it to 10.0 using the steps in the Grafana 10.0 upgrade guide. Before any user logs in, query the user table for usernames and email addresses that differ only in letter case, since 10.0 treats them as the same identity. Confirm each command and file path against the exact version you run, because package names and paths can change between releases. The step is done when the staging duplicate query returns no rows or every row has a documented resolution. Staging is your main rollback point here, because production has not changed yet.
Resolve identity conflicts with the CLI tool or by hand
On databases other than MySQL, use the Grafana CLI user identity conflict tool to find and resolve conflicting usernames and emails before login is attempted. Where the tool does not cover a case, correct the records by hand in a transaction, recording the original values so you can reverse them. Ask the account owners which record is authoritative, because the tool cannot decide that for you. The step is done when the conflict list is empty on staging and a test login succeeds for each affected identity. Keep the pre-change export of the user table as the rollback point for this step.
Schedule the production upgrade in a window
Agree a change window with the people who depend on Grafana dashboards and alerts, and publish the rollback decision owner and the criteria for rolling back. Repeat the backup from step one immediately before the window opens, so the rollback point matches the state you are upgrading from. Confirm that the staging run used the same versions of Grafana, plugins and database driver as production. The step is done when the change record names the owner, the rollback criteria and the backup location, and all three are approved. Do not start the upgrade without a fresh backup taken inside the window.
Verify logins, access, queries and alerting
Upgrade production following the same steps used on staging, then test each sign-in path: local accounts, and each external identity source configured in your environment. Check that a sample of users can open their dashboards and folders, that data source queries return results, and that alert rules evaluate and route notifications as they did before the upgrade. Use a test account that matches each role, and record which user, dashboard, data source and alert rule you checked. The step is done when every check in the test record passes or has a logged, accepted exception. If a critical check fails, use the production backup as the rollback point and reverse the upgrade.
Monitor for permission complaints
For a period you agree with the business owners, watch for support tickets and messages about missing folders, dashboards that now show errors, and users who cannot edit resources they could edit before. Review the Grafana server logs for authorization errors and compare them with the access list you recorded before the upgrade. Assign one person to triage each report and decide whether it is an identity conflict, a role mapping issue or an expected change in 10.0 permissions. The step is done when the monitoring period ends with no open access reports, or with each open report assigned to an owner. Permission problems found here are usually fixed by correcting roles, not by rolling back.
Close out the upgrade and record the evidence
Remove the freeze, document the final version, the backup location, the identity conflicts resolved and the test results, and store this record with your change management system. Confirm that the staging and production backups are retained according to your retention policy, and schedule the removal of temporary exports created during the work. If you plan to downgrade later, note that the 10.0 guide gives SQL cleanup queries to run before re-upgrading, so keep that step visible in the record. The step is done when the record is signed off and the freeze is lifted. This closes the sequence, and the record is what your auditors or reviewers will ask for.
Why a downgrade and re-upgrade can leave permissions out of sync
A downgrade from Grafana 10 back to 9 and a later re-upgrade is the path where permissions most often break. The Grafana 10.0 upgrade guide says that if you downgrade, you must disable role-based access control before you upgrade again, and that legacy permissions and RBAC permissions can then fall out of sync. Because RBAC is always on in 10.0 and cannot be turned off, the downgrade step itself is where the team has to plan the change. Before you start, confirm in the guide how RBAC is disabled for the exact versions you run, since the procedure is version specific.
The guide provides SQL cleanup queries to run before you re-upgrade. Treat these as a controlled change, not a routine fix. Review each query against your database engine, since the same intent can behave differently on SQLite, MySQL and PostgreSQL. Run them first on a restored copy of the database, not on production. Record row counts for the affected permission tables before and after each statement, and keep those counts with the change record so you can explain what moved. Do not write or adapt queries from memory or from forum posts. A query that is almost right can remove the access that your users and automation depend on.
A downgrade should be an exception path. The safer choice is to restore a backup taken before the upgrade, which returns the database to a state the older version understands, rather than trying to repair permissions after the fact. Confirm that your pre-upgrade backup covers the database and configuration, and test the restore before you depend on it. If you still need to downgrade, plan a restored-copy rehearsal, a named approver for the cleanup queries and a verification pass on user and team permissions before users return.
What makes a Grafana 9 to 10 upgrade take longer
This table lists the factors that change how much work a Grafana 9 to 10 upgrade needs, why each one adds effort, and what to check in your environment before you start. Use it to see where your instance sits on each driver, then ask for an effort estimate tied to a written scope rather than a generic figure. The main takeaway is that identity data, permission layout and downgrade readiness usually matter more than the upgrade command itself.
| Driver | Why it adds effort | What to check |
|---|---|---|
| Users and teams with mixed-case identifiers | Grafana 10.0 makes usernames and email addresses case-insensitive, so accounts that differ only by case can collide at login outside MySQL. | Export user logins and emails and look for duplicates that differ only by letter case, then confirm the Grafana CLI user identity conflict tool steps with your database owner. |
| Identity sources in use (LDAP, OAuth, auth proxy, JWT) | Each source stores or maps identifiers differently, so a case change can affect how an existing user matches an incoming login. | List every configured identity source, how it maps usernames and emails, and whether any users sign in through more than one path. |
| Database engine and size | Identity conflict handling differs on non-MySQL databases, and a larger database takes longer to back up, restore and run cleanup queries against. | Confirm the engine and version, current database size, and whether backups and a restore test have been run recently. |
| Permission complexity (folders, nested teams, custom roles) | RBAC is always on in Grafana 10.0, so legacy permissions must map onto role-based permissions, and deep folder trees or custom roles need more review. | Count folders with custom permissions, nested team structures, and custom roles, and document who owns each access boundary. |
| Provisioned resources managed as code | Provisioned data sources, dashboards and alerting resources need their files reviewed and may need edits to match the new behavior. | Inventory provisioning files and any Terraform or Git Sync workflows, and confirm which ones your team can change during the window. |
| Plugins and data sources with access rules | Plugin compatibility and data source permissions both shape what users can see after the upgrade, and each needs its own test. | List installed plugins with versions, data sources with restricted access, and any plugin that has no current upstream maintenance. |
| Number of environments and high availability nodes | Each environment and each active-active node needs the same version and configuration, and HA setups need a planned order of operations. | Count development, test and production instances and nodes behind the load balancer, and confirm the rollout order and any alerting configuration for HA. |
| Downgrade plan | If you downgrade, disable RBAC and upgrade again, and the upgrade guide gives SQL cleanup queries to run before re-upgrading, which adds steps and verification. | Confirm a tested database backup, the configuration and plugin backups, and whether your team can run and check the cleanup queries before any re-upgrade. |
What buyers ask before hiring help for the Grafana 10 upgrade
What drives the cost of a Grafana 10 upgrade?
The main cost driver is how much preparation and verification the upgrade needs in your environment, not the upgrade command itself. Effort rises with the number of Grafana instances, the database engine and size, the number of users and identity sources, how many custom plugins and provisioned resources you run, and how many environments (test, staging, production) must be upgraded and checked. A written scope should separate one-time work (assessment, backup and rollback plan, upgrade runbook, identity review, cutover and verification) from any recurring support or retainer. Ask each quote to name who performs each task, what is excluded, and what assumptions about access and change windows it depends on.
How long does the Grafana 10 upgrade take?
This page does not give a duration because the answer depends on your instance count, database, user base, plugin inventory and how many environments need testing before production. Ask for a timeline in the written scope that lists the phases, the client actions each phase needs, and the dates on which your team must provide access or approvals. Also ask how the plan handles a failed test, since a blocked identity conflict or plugin issue can extend the schedule more than the upgrade itself.
What does the upgrade need from our team?
Plan to provide the following before work starts:
- Administrative access to the Grafana servers, the database, and the hosts or containers that run Grafana, along with the deployment method used.
- A verified backup of the database and configuration, taken by your team or confirmed with the partner, with a tested restore path.
- Named owners for identity providers and user directories, who can confirm how logins and email addresses are stored.
- Test users and representative dashboards, data sources and alert rules to check after the upgrade.
- An approved change window for each environment, with a rollback decision point agreed in advance.
Can our internal team upgrade Grafana 10 without a partner?
Yes, many teams do, provided they have the skills and time to run the work properly. The team needs Linux or container administration experience, database administration skills for the engine in use, familiarity with Grafana provisioning and plugin management, and someone who can read the Grafana 10.0 upgrade guide and make decisions about identity data and RBAC. Testing against a copy of production is the step most often under-resourced. Decide early whether the team has capacity for the full cycle, and if not, scope a partner for specific parts such as the identity review or the test plan.
How do we find and resolve identity conflicts after the upgrade?
Grafana 10.0 makes usernames and email addresses case-insensitive. Users whose databases are not MySQL may hit identity conflicts at login when two accounts differ only in case. Before the upgrade, review your user table and identity provider records for accounts that would collide once case is ignored, and plan how each conflict will be resolved with the owner of the account. The Grafana CLI user identity conflict tool, described in the Grafana 10.0 upgrade guide, is the first option to check for resolving these cases. Confirm its exact commands and behavior against the version you run, and test the resolution in staging before production.
Is downgrading after a Grafana 10 upgrade advisable?
Avoid downgrading unless you have no other option, and plan your rollback as a restore from backup rather than a reversal. The Grafana 10.0 upgrade guide warns that if you downgrade, you should disable RBAC and upgrade again, because legacy and RBAC permissions can fall out of sync. The guide gives SQL cleanup queries to run before re-upgrading. Run those queries only after confirming them against your database and a backup, and test the full downgrade and re-upgrade in a non-production copy first. Ask any partner to state how they will verify permissions after each step.
Does the upgrade engagement include post-upgrade support?
It depends on the written scope, so check it line by line. A fixed-scope upgrade usually covers the agreed phases, verification and handover, and may include a defined period of post-cutover checks. Ongoing support, minor and patch upgrades, and continuous testing are available as retainers and are priced separately. Ask the quote to state what counts as the end of the engagement, how issues found after cutover are handled, what documentation you receive, and whether the next Grafana release cycle is included or excluded.
How DeployOpen works on this
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, and that includes Grafana 9 to 10 upgrades. We start with a written scope that names your data sources, identity setup and database, then carry the upgrade through to a documented, supported result in your environment.
How we scope
- Inventory your Grafana 9 instances, versions, database engine and identity provider before any change is planned.
- Check whether your database is MySQL, where identity conflicts are less likely, or PostgreSQL or SQLite, where usernames and emails need review.
- Agree in writing which users, teams, dashboards and API consumers are in scope, and which are excluded.
How we build
- Run the upgrade first in a staging copy of your instance with production-like data and plugins.
- Review role-based access control changes, since RBAC is always on in Grafana 10, and test representative user permissions.
- Test login, dashboard and alerting behavior against a documented rollback path before any production change.
How we hand over
- Deliver a written runbook covering the upgrade steps, validation checks, backup points and rollback procedure.
- Document any identity conflict resolution, cleanup queries and configuration changes, with the reasons for each.
- Walk your operations and security teams through the results and confirm acceptance against the agreed scope.
How we support
- Engagements are fixed-scope, and the scope, deliverables and timelines are agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer if your team wants continued help.
- Ask any partner to confirm how it will handle minor releases and patch releases in your environment after handover.
