ory/hydra · error

could not query database version to verify dialect

Error message

could not query database version to verify dialect

What it means

VerifyDialect validates that the declared DSN dialect (postgres, cockroach, yugabyte) matches the actual server by running SELECT version(). If the raw query fails to return a version row, the check cannot proceed and wraps the driver error with this message. It is a pre-flight guard, not a connection failure per se.

Source

Thrown at oryx/popx/dialect_check.go:32

)

// VerifyDialect makes sure the declared SQL dialect matches the actual
// database server. It distinguishes PostgreSQL, CockroachDB, and YugabyteDB:
// all three speak the Postgres wire protocol, so an operator can easily point
// a service configured for one at a server running another. That mismatch
// silently selects the wrong dialect-specific migrations and produces broken
// schemas.
//
// Other dialects (MySQL, SQLite) are skipped.
func VerifyDialect(ctx context.Context, conn *pop.Connection) error {
	declared := conn.Dialect.Name()
	if declared != namePostgres && declared != dbal.DriverCockroachDB && declared != dbal.DriverYugabyteDB {
		return nil
	}

	var version string
	if err := conn.WithContext(ctx).RawQuery("SELECT version() AS version").First(&version); err != nil {
		return errors.Wrap(err, "could not query database version to verify dialect")
	}
	return checkDialect(declared, version, pop.DialectSupported(dbal.DriverYugabyteDB))
}

const (
	namePostgres = "postgres"

	// yugabyteVersionMarker identifies a YugabyteDB server in the output of
	// SELECT version() (e.g. "PostgreSQL 11.2-YB-2025.2.4.0-b122 ...").
	yugabyteVersionMarker = "-YB-"
)

func checkDialect(declared, version string, yugabyteDialectSupported bool) error {
	detectedCockroach := strings.Contains(version, "CockroachDB")
	detectedYugabyte := strings.Contains(version, yugabyteVersionMarker)
	switch {
	case declared == dbal.DriverCockroachDB && !detectedCockroach:
		return errors.Errorf(

View on GitHub (pinned to 4174065ffb)

Solutions

1. Check the underlying wrapped error for the real cause (connection refused, auth, timeout)
2. Test connectivity manually: psql '<DSN>' -c 'SELECT version()'
3. Verify the DB user has permission to run SELECT version()
4. Confirm network/firewall/keepalives allow the connection to stay up during migration start

Example fix

// verify before starting
psql "postgres://user@host/db" -c 'SELECT version();'
// if it errors, fix network/credentials before running migrations

func checkDBReady(db *pop.Connection) error {
    var v string
    return db.WithContext(context.Background()).RawQuery("SELECT version() AS version").First(&v)
}

if err := VerifyDialect(ctx, conn, dsn); err != nil {
    if strings.Contains(err.Error(), "could not query database version") {
        return fmt.Errorf("database unreachable or unauthorized during dialect check: %w", err)
    }
    return err
}

When it happens

Trigger: Calling VerifyDialect with a connection whose query 'SELECT version() AS version' fails: connection dropped mid-check, insufficient permissions, or the target server does not support version().

Common situations: Network interruption between connect and the dialect check; user lacking permission to execute SELECT version(); pointing at a non-PostgreSQL-protocol server that accepts connections but rejects the query.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• unsupported dialect
• DSN scheme cockroach:// declares a CockroachDB database but
• DSN scheme yugabyte:// declares a YugabyteDB database but th
• %s
• The DSN connection string looks like a SQLite connection, bu

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/495e71a97bdcc4c3. Report an issue: GitHub.