{"record":{"id":"6c762c8c1e348ee9","repo":"ory/hydra","slug":"dsn-scheme-yugabyte-declares-a-yugabytedb-datab","errorCode":null,"errorMessage":"DSN scheme yugabyte:// declares a YugabyteDB database but the server is not YugabyteDB. Server reported: %q. Use a DSN scheme matching the actual server, or point the service at a YugabyteDB cluster.","messagePattern":"DSN scheme yugabyte:// declares a YugabyteDB database but the server is not YugabyteDB\\. Server reported: %q\\. Use a DSN scheme matching the actual server, or point the service at a YugabyteDB cluster\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"oryx/popx/dialect_check.go","lineNumber":55,"sourceCode":"const (\n\tnamePostgres = \"postgres\"\n\n\t// yugabyteVersionMarker identifies a YugabyteDB server in the output of\n\t// SELECT version() (e.g. \"PostgreSQL 11.2-YB-2025.2.4.0-b122 ...\").\n\tyugabyteVersionMarker = \"-YB-\"\n)\n\nfunc checkDialect(declared, version string, yugabyteDialectSupported bool) error {\n\tdetectedCockroach := strings.Contains(version, \"CockroachDB\")\n\tdetectedYugabyte := strings.Contains(version, yugabyteVersionMarker)\n\tswitch {\n\tcase declared == dbal.DriverCockroachDB && !detectedCockroach:\n\t\treturn errors.Errorf(\n\t\t\t\"DSN scheme cockroach:// declares a CockroachDB database but the server is not CockroachDB. Server reported: %q. Use a postgres:// DSN, or point the service at a CockroachDB cluster.\",\n\t\t\tfirstLine(version),\n\t\t)\n\tcase declared == dbal.DriverYugabyteDB && !detectedYugabyte:\n\t\treturn errors.Errorf(\n\t\t\t\"DSN scheme yugabyte:// declares a YugabyteDB database but the server is not YugabyteDB. Server reported: %q. Use a DSN scheme matching the actual server, or point the service at a YugabyteDB cluster.\",\n\t\t\tfirstLine(version),\n\t\t)\n\tcase declared == namePostgres && detectedCockroach:\n\t\treturn errors.Errorf(\n\t\t\t\"DSN scheme postgres:// declares a PostgreSQL database but the server is CockroachDB. Replace the scheme with cockroach:// so that the service picks the correct migrations and SQL dialect. Server reported: %q\",\n\t\t\tfirstLine(version),\n\t\t)\n\tcase declared == namePostgres && detectedYugabyte && yugabyteDialectSupported:\n\t\treturn errors.Errorf(\n\t\t\t\"DSN scheme postgres:// declares a PostgreSQL database but the server is YugabyteDB. Replace the scheme with yugabyte:// (supported in Ory Enterprise License builds) so that the service picks the correct migrations. Server reported: %q\",\n\t\t\tfirstLine(version),\n\t\t)\n\t}\n\treturn nil\n}\n\nfunc firstLine(s string) string {","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/ory/hydra/blob/4174065ffb052799890f7480f5360a877a67ffc1/oryx/popx/dialect_check.go#L37-L73","documentation":"checkDialect detects YugabyteDB by a version-marker substring. When the DSN scheme is yugabyte:// but version() does not contain the YugabyteDB marker, this error is returned so the service does not apply Yugabyte-specific migrations to a non-Yugabyte server. Note the check also depends on pop.DialectSupported(dbal.DriverYugabyteDB); if that dialect is unsupported, VerifyDialect skips verification entirely.","triggerScenarios":"Connecting with a yugabyte:// DSN to a plain PostgreSQL or CockroachDB server; or using yugabyte:// against an older YugabyteDB build whose version() string lacks the marker while the Yugabyte dialect is supported.","commonSituations":"Scheme swapped in config templating; pointing at a PG dev database with a Yugabyte production config; YugabyteDB version upgrade/downgrade changing the version string; running on a build where Yugabyte dialect support is compiled in but the server is not Yugabyte.","solutions":["Point the DSN at a real YugabyteDB cluster","If the server is PostgreSQL or CockroachDB, change the scheme to postgres:// or cockroach:// respectively","Verify the actual server: psql '<DSN>' -c 'SELECT version()' and look for the Yugabyte marker","If it IS YugabyteDB but fails, check the version string format against yugabyteVersionMarker and upgrade the library"],"exampleFix":"// before\ndsn := \"yugabyte://user@pg-host:5432/db\" // host is PostgreSQL\n// after\ndsn := \"postgres://user@pg-host:5432/db\"","handlingStrategy":"validation","validationCode":"func ensureYugabyteDSN(dsn string, conn *pop.Connection) error {\n    var version string\n    if err := conn.RawQuery(\"SELECT version()\").First(&version); err != nil {\n        return err\n    }\n    if strings.HasPrefix(dsn, \"yugabyte://\") && !strings.Contains(version, \"YugabyteDB\") {\n        return fmt.Errorf(\"DSN declares yugabyte but server reports: %s\", version)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := VerifyDialect(ctx, conn, dsn); err != nil && strings.Contains(err.Error(), \"declares a YugabyteDB database\") {\n    return fmt.Errorf(\"align DSN scheme with actual server: %w\", err)\n}","preventionTips":["Use environment-specific config templates so the scheme matches each cluster type","Verify the YugabyteDB version string still contains the expected marker after upgrades","Run the dialect check in CI integration tests for every DSN variant","If the server is YugabyteDB but the check still fails, upgrade oryx/popx for marker-format fixes"],"tags":["database","yugabytedb","dialect","misconfiguration"],"backgroundTag":"dialect-mismatch","analyzedSha":"4174065ffb052799890f7480f5360a877a67ffc1","analyzedAt":"2026-09-03T14:52:41.581Z","contentChangedAt":"2026-09-03T14:52:41.581Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}