Skip to main content

Self-hosted Ory on YugabyteDB

Availability

YugabyteDB requires an Ory Enterprise License (OEL) image for Ory Identities, Ory OAuth2 & OpenID Connect, and Ory Permissions. Ory Polis supports YugabyteDB in both open source and OEL builds.

YugabyteDB is a distributed SQL database with horizontal scalability, strong consistency, and PostgreSQL wire-protocol compatibility. It's a viable backend for self-hosted Ory deployments that need a distributed database without adopting CockroachDB.

Availability​

ProductAvailabilityConfiguration
Ory IdentitiesOEL images onlydsn: yugabyte://…
Ory OAuth2 & OpenID ConnectOEL images onlydsn: yugabyte://…
Ory PermissionsOEL images onlydsn: yugabyte://…
Ory PolisOpen source and OELDB_TYPE=yugabytedb

How it works​

YugabyteDB speaks the PostgreSQL wire protocol. Ory registers it as a distinct database dialect rather than treating it as PostgreSQL, so each service selects the migrations and SQL that YugabyteDB accepts.

Point the dsn configuration key at your YugabyteDB cluster using the yugabyte:// scheme. The yugabytedb:// scheme is an accepted synonym:

yugabyte://user:password@host:5433/database?sslmode=verify-full
yugabyte://user:password@host:5433/database?sslmode=disable

Port 5433 is the default YSQL port. YugabyteDB accepts the same DSN parameters as PostgreSQL, including sslmode, application_name, search_path, the sslcert, sslkey, and sslrootcert certificate paths, and the connection pool settings. See PostgreSQL supported parameters for the full list.

Use the yugabyte:// scheme, not postgres://​

A postgres:// DSN pointed at a YugabyteDB cluster makes the service select the PostgreSQL migrations, some of which YugabyteDB rejects. OEL images detect this at startup and refuse to start with an error naming the scheme to use instead. Always set the scheme to match the server you connect to.

Migrations​

Run migrations the same way as on any other database, for example kratos migrate sql for Ory Identities and the equivalent command for the other services.

YugabyteDB applies schema changes with autocommit, so a migration file doesn't run inside a transaction. Older PostgreSQL migration files inherited by YugabyteDB can contain more than one statement. If such a migration is interrupted partway, the first statements are applied without a row in the schema_migration table, and rerunning the migration fails because those statements can't be replayed. Current Ory versions no longer ship multi-statement migrations and are safe to rerun.

If a migration is interrupted, compare the live schema against the migration file to find which statements were applied, then either apply the remaining statements or reverse the applied ones before rerunning the migration command.

What differs from CockroachDB​

Both databases are distributed and PostgreSQL-compatible, but several Ory features are built on CockroachDB-specific capabilities and behave differently on YugabyteDB:

  • Row-level TTL retention isn't available. The row-level TTL retention migrations require CockroachDB and fail when the DSN points at another database.
  • Multi-region table localities don't apply. REGIONAL BY ROW and GLOBAL table localities are CockroachDB features, so the multi-region migrations aren't applied on YugabyteDB.
  • Eventually consistent reads have no effect. Requests that ask for eventual read consistency are served with strong consistency, because follower reads are a CockroachDB feature. The request succeeds; only the latency benefit is absent.
  • Transactions use the standard retry path. YugabyteDB maps READ COMMITTED to snapshot isolation unless yb_enable_read_committed_isolation is enabled on the cluster, so Ory retries serialization failures instead of lowering the isolation level.

Ory Polis​

Ory Polis selects YugabyteDB through its own environment variables rather than a DSN scheme. YugabyteDB has no dedicated driver in Polis and reuses the PostgreSQL one:

DB_ENGINE=sql
DB_TYPE=yugabytedb
DB_URL=postgresql://yugabyte@localhost:5433/yugabyte

See Ory Polis environment variables for the remaining database settings.

Resources​