golang-migrate/migrate · error

no schema

Error message

no schema

What it means

ErrNoSchema is returned by the postgres-family drivers when a schema name is required but empty. For lib/pq's postgres driver, Open/WithInstance return it when x-schema-name is absent while the driver requires one; the sentinel is shared and re-declared in pgx copies.

Source

Thrown at database/postgres/postgres.go:40

)

func init() {
	db := Postgres{}
	database.Register("postgres", &db)
	database.Register("postgresql", &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")
	ErrDatabaseDirty  = fmt.Errorf("database is dirty")
)

type Config struct {
	MigrationsTable       string
	MigrationsTableQuoted bool
	MultiStatementEnabled bool
	DatabaseName          string
	SchemaName            string
	migrationsSchemaName  string
	migrationsTableName   string
	StatementTimeout      time.Duration
	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. Add x-schema-name=<schema> to the connection URL, e.g. ?x-schema-name=myschema
2. Set Config.SchemaName in the Config struct for WithInstance/WithConnection
3. Use 'public' explicitly if you intended the default schema
4. Match with errors.Is(err, postgres.ErrNoSchema) to surface a friendly message

Example fix

// before
dsn := "postgres://u:p@host/db"
// after
dsn := "postgres://u:p@host/db?x-schema-name=myschema"

if cfg != nil && cfg.SchemaName == "" {
    return errors.New("Config.SchemaName must be set (use \"public\" for the default schema)")
}

if err := m.Up(); err != nil {
    if errors.Is(err, postgres.ErrNoSchema) {
        log.Fatal("schema missing: add ?x-schema-name=<schema> to the DSN or set Config.SchemaName")
    }
    panic(err)
}

When it happens

Trigger: Calling postgres.Open with a URL missing x-schema-name when the driver instance requires a schema, or WithInstance/WithConnection with Config{SchemaName: ""}; the pgx variant at database/pgx/pgx.go:109 returns it when schemaName resolves to length 0.

Common situations: Migrating within a specific Postgres schema but forgetting the x-schema-name URL parameter; empty env var interpolation for the schema; confusing database name with schema name in the config.

Related errors

• no schema
• no database name
• no schema
• no config
• no database name

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