golang-migrate/migrate · error

no database name

Error message

no database name

What it means

ErrNoDatabaseName is the sentinel error returned by the pgx v5 driver when Config.DatabaseName is empty in WithInstance, WithConnection, or Open. Several operations (e.g. ensuring the migrations table exists in the right database) require an explicit database name, and the driver refuses to guess. Callers can match it with errors.Is.

Source

Thrown at database/pgx/v5/pgx.go:40

	"github.com/jackc/pgx/v5/pgconn"
	_ "github.com/jackc/pgx/v5/stdlib"
)

func init() {
	db := Postgres{}
	database.Register("pgx5", &db)
}

var (
	multiStmtDelimiter = []byte(";")

	DefaultMigrationsTable       = "schema_migrations"
	DefaultMultiStatementMaxSize = 10 * 1 << 20 // 10 MB
)

var (
	ErrNilConfig      = fmt.Errorf("no config")
	ErrNoDatabaseName = fmt.Errorf("no database name")
	ErrNoSchema       = fmt.Errorf("no schema")
)

type Config struct {
	MigrationsTable       string
	DatabaseName          string
	SchemaName            string
	migrationsSchemaName  string
	migrationsTableName   string
	StatementTimeout      time.Duration
	MigrationsTableQuoted bool
	MultiStatementEnabled bool
	MultiStatementMaxSize int
}

type Postgres struct {
	// Locking and unlocking need to use the same connection
	conn     *sql.Conn

View on GitHub (pinned to 01a9643f14)

Solutions

1. Set Config.DatabaseName explicitly, e.g. &pgxv5.Config{DatabaseName: "myapp"}.
2. Include the database in the DSN: postgres://user:pass@host:5432/myapp.
3. Validate required env vars (DB name) before constructing Config so empty strings fail early in your own code.
4. Use errors.Is(err, pgxv5.ErrNoDatabaseName) to branch and prompt for/derive the missing database name.

Example fix

// before
cfg := &pgxv5.Config{MigrationsTable: "schema_migrations"} // no DatabaseName
// after
cfg := &pgxv5.Config{MigrationsTable: "schema_migrations", DatabaseName: os.Getenv("DB_NAME")}

if cfg.DatabaseName == "" {
    return fmt.Errorf("DatabaseName is required for pgx migrations")
}

func isConfigComplete(c *pgxv5.Config) bool { return c != nil && c.DatabaseName != "" }

drv, err := pgxv5.WithInstance(conn, cfg)
if err != nil {
    if errors.Is(err, pgxv5.ErrNoDatabaseName) {
        return fmt.Errorf("set Config.DatabaseName or include /dbname in the DSN: %w", err)
    }
    return err
}

When it happens

Trigger: Passing &pgxv5.Config{} (or a Config with DatabaseName: "") to WithInstance/WithConnection, or opening with a connection string lacking both a database path component and a DatabaseName — e.g. `postgres://host:5432` with no `/dbname`.

Common situations: Building Config programmatically from env vars where the DB name env var is unset; using DSNs built by string concatenation that drop the database segment; connecting to a specific connection endpoint (e.g. via a sidecar proxy) that omits the database in the URL.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• no schema
• unable to parse option x-migrations-table-quoted: %w
• x-migrations-table must be quoted (for instance '"migrate"."
• unable to parse option x-multi-statement: %w
• unknown lock strategy "%s"

AI-assisted analysis of golang-migrate/migrate@01a9643f14 (2026-09-02). Data as JSON: /api/errors/b8275b547f33ce76. Report an issue: GitHub.