hasura/graphql-engine · error

database driver: unknown driver %v

Error message

database driver: unknown driver %v

What it means

migrate/database.Open returns this when the URL scheme of the database URL does not match any registered driver. The registry (drivers map) is keyed by scheme such as 'hasura' or 'postgres'.

Source

Thrown at cli/migrate/database/driver.go:141

	u, err := nurl.Parse(url)
	if err != nil {
		log.Debug(err)

		return nil, errors.E(op, err)
	}

	driversMu.RLock()

	if u.Scheme == "" {
		return nil, errors.E(op, stderrors.New("database driver: invalid URL scheme"))
	}

	driversMu.RUnlock()

	d, ok := drivers[u.Scheme]
	if !ok {
		return nil, errors.E(op, fmt.Errorf("database driver: unknown driver %v", u.Scheme))
	}

	if logger == nil {
		logger = log.New()
	}

	driver, err := d.Open(url, isCMD, logger, hasuraOpts)
	if err != nil {
		return driver, errors.E(op, err)
	}

	return driver, nil
}

func Register(name string, driver Driver) {
	driversMu.Lock()
	defer driversMu.Unlock()

View on GitHub (pinned to 724551b9ae)

Solutions

1. Use a supported scheme, typically the hasura:// endpoint for CLI migrations
2. Fix typos in the database URL scheme
3. Ensure the driver package providing the scheme is imported/registered before Open

Example fix

// before
url := "mysql://user:pass@host/db"
db, err := database.Open(url, false)
// after
url := "hasura://localhost:8080"
db, err := database.Open(url, false)

u, err := url.Parse(dbURL)
if err != nil { return err }
switch u.Scheme {
case "hasura", "postgres", "postgresql":
default:
    return fmt.Errorf("unsupported scheme %q", u.Scheme)
}

When it happens

Trigger: Calling database.Open with a URL whose scheme is not registered, e.g. mysql://... when only hasura/postgres drivers are compiled in, or a mistyped scheme.

Common situations: Passing a generic database URL instead of a Hasura endpoint, typo in the scheme, or using a driver package that was never imported (driver registration happens in init).

Related errors

• error in creation of new migrate instance %w
• unable to initialize migrations driver: %w
• unable to marshal run_sql args in %s: %w
• unable to unmarshal run_sql args in %s: %w
• creating Version table failed %s

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/2d677dd8c68cda3e. Report an issue: GitHub.