{"record":{"id":"1cd1236cc23e4858","repo":"ory/hydra","slug":"dsn-scheme-cockroach-declares-a-cockroachdb-dat","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"oryx/popx/dialect_check.go","lineNumber":50,"sourceCode":"\t\treturn errors.Wrap(err, \"could not query database version to verify dialect\")\n\t}\n\treturn checkDialect(declared, version, pop.DialectSupported(dbal.DriverYugabyteDB))\n}\n\nconst (\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)","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/ory/hydra/blob/4174065ffb052799890f7480f5360a877a67ffc1/oryx/popx/dialect_check.go#L32-L68","documentation":"checkDialect compares the declared DSN scheme with the server's version() output. When the DSN scheme is cockroach:// but the version string does not contain 'CockroachDB', the library refuses to run, because migrations and SQL dialect differ between PostgreSQL and CockroachDB. The %q is the server's reported version first line.","triggerScenarios":"Connecting VerifyDialect/migration manager with a cockroach:// DSN to a server that is actually PostgreSQL (or YugabyteDB or another PG-compatible fork).","commonSituations":"Copy-pasting a DSN and only swapping the scheme; a proxy/load balancer routing 'cockroach' DSNs to a plain Postgres instance; switching infrastructure but leaving the old DSN scheme in config.","solutions":["Point the DSN at a real CockroachDB cluster","If the server truly is PostgreSQL, change the scheme to postgres://","Verify with: psql '<DSN>' -c 'SELECT version()' and check for 'CockroachDB'","Fix config templating that injects the wrong scheme per environment"],"exampleFix":"// before\ndsn := \"cockroach://user@pg-host:5432/db\" // host is PostgreSQL\n// after\ndsn := \"postgres://user@pg-host:5432/db\"","handlingStrategy":"validation","validationCode":"func dsnSchemeMatchesServer(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, \"cockroach://\") && !strings.Contains(version, \"CockroachDB\") {\n        return fmt.Errorf(\"DSN declares cockroach 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 CockroachDB database\") {\n    return fmt.Errorf(\"fix DSN scheme in config: %w\", err)\n}","preventionTips":["Keep DSN scheme and actual server type in the same config template per environment","Run SELECT version() in CI against integration-test databases with the same scheme","Never rename just the scheme when migrating configs between environments","Document which scheme each environment's cluster requires"],"tags":["database","cockroachdb","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"}