Apply upgrades

Follow this guide when upgrading Ory Hydra to a newer version.

danger

Back up your data! Applying upgrades can lead to data loss if handled incorrectly.

1. Read the release notes. We try to make our release notes as comprehensive as possible, so make sure to give them a good read. They might contain information that is specific to your deployment.
2. Review breaking changes. Visit the CHANGELOG.md to see if breaking changes have been introduced in the version you are upgrading to.
3. Backup your data.
4. Update the Ory Hydra SDK if used in your application.
5. Install the new version of Ory Hydra.
6. Run hydra migrate sql to run the SQL migrations to the new database schema.

Should you run into problems with the upgrade, consider a stepped upgrade and please visit the community chat or start a discussion.

Upgrade from Hydra 1.0.0-rc or earlier

Hydra versions before 1.0.0, released in June 2019, tracked applied migrations in four per-component tables instead of the schema_migration table used today. Hydra 1.0.0 and later converted those tables on the first hydra migrate sql up and then removed them. Hydra no longer performs that conversion, so a database that still has the old tables needs a stepped upgrade.

Almost no deployments are affected. If you have run hydra migrate sql up at any point since June 2019, the old tables are already gone. To confirm, run:

SELECT table_name FROM information_schema.tables
WHERE table_name IN (
  'hydra_client_migration',
  'hydra_jwk_migration',
  'hydra_oauth2_authentication_consent_migration',
  'hydra_oauth2_migration'
);

An empty result means you can upgrade normally.

If the query returns rows, back up your database, then run hydra migrate sql up once with any Hydra release from 1.0.0 up to the release before this one. That converts the migration tables. You can then install the current version and run hydra migrate sql up again.

Upgrading directly stops at the migration step with an error such as relation "hydra_client" already exists, because Hydra doesn't recognize the old tables and tries to apply the 2019 migrations to a schema that already has them. Your data isn't modified when this happens, and the stepped upgrade above resolves it.

Migrate from Hydra v1 to v2

Some consents may be erased when migrating to Hydra 2.0. We assume that only a very small number of sessions, issued by pre-1.0 Hydra, will be affected. Please contact us if this assumption doesn't apply or if the deletion adversely affects your deployment.

The below query displays the numbers of consents that will be deleted by the v2 migration. Make sure that you are happy with these consents being deleted before you proceed.

-- postgresql
SELECT
  COUNT(*) AS count,
  DATE_TRUNC('month', requested_at) AS month
FROM hydra_oauth2_consent_request
WHERE login_challenge IS NULL
GROUP BY month;