golang-migrate/migrate · error

x-migrations-table must be quoted (for instance '"migrate"."

Error message

x-migrations-table must be quoted (for instance '"migrate"."schema_migrations"') when x-migrations-table-quoted is enabled, current value is: %s

What it means

This error comes from the postgres driver's Open() when both x-migrations-table and x-migrations-table-quoted=true are set in the connection URL. The quoted flag tells the driver to treat the migrations table name as fully quoted SQL (e.g. "migrate"."schema_migrations"), so the value must already start and end with a double quote. If it does not, the driver refuses to build a safely quoted identifier and fails fast.

Source

Thrown at database/postgres/postgres.go:172

	if err != nil {
		return nil, err
	}

	db, err := sql.Open("postgres", migrate.FilterCustomQuery(purl).String())
	if err != nil {
		return nil, err
	}

	migrationsTable := purl.Query().Get("x-migrations-table")
	migrationsTableQuoted := false
	if s := purl.Query().Get("x-migrations-table-quoted"); len(s) > 0 {
		migrationsTableQuoted, err = strconv.ParseBool(s)
		if err != nil {
			return nil, fmt.Errorf("unable to parse option x-migrations-table-quoted: %w", err)
		}
	}
	if (len(migrationsTable) > 0) && (migrationsTableQuoted) && ((migrationsTable[0] != '"') || (migrationsTable[len(migrationsTable)-1] != '"')) {
		return nil, fmt.Errorf("x-migrations-table must be quoted (for instance '\"migrate\".\"schema_migrations\"') when x-migrations-table-quoted is enabled, current value is: %s", migrationsTable)
	}

	statementTimeoutString := purl.Query().Get("x-statement-timeout")
	statementTimeout := 0
	if statementTimeoutString != "" {
		statementTimeout, err = strconv.Atoi(statementTimeoutString)
		if err != nil {
			return nil, err
		}
	}

	multiStatementMaxSize := DefaultMultiStatementMaxSize
	if s := purl.Query().Get("x-multi-statement-max-size"); len(s) > 0 {
		multiStatementMaxSize, err = strconv.Atoi(s)
		if err != nil {
			return nil, err
		}
		if multiStatementMaxSize <= 0 {

View on GitHub (pinned to 01a9643f14)

Solutions

1. Wrap the value in double quotes in the URL, percent-encoding them if your client requires: x-migrations-table=%22migrate%22.%22schema_migrations%22
2. Set x-migrations-table-quoted=false (or remove it) if quoting is not actually needed
3. Rename the migrations table to a lowercase, non-reserved name and drop the quoted flag

Example fix

// before
dsn := "postgres://u:p@host/db?x-migrations-table=migrate.schema_migrations&x-migrations-table-quoted=true"
// after
dsn := "postgres://u:p@host/db?x-migrations-table=%22migrate%22.%22schema_migrations%22&x-migrations-table-quoted=true"

func validateMigrationsTable(dsn *url.URL) error {
    table := dsn.Query().Get("x-migrations-table")
    quoted, _ := strconv.ParseBool(dsn.Query().Get("x-migrations-table-quoted"))
    if quoted && table != "" && !(strings.HasPrefix(table, "\"") && strings.HasSuffix(table, "\"")) {
        return fmt.Errorf("x-migrations-table must be wrapped in double quotes: %q", table)
    }
    return nil
}

When it happens

Trigger: Calling Open or New with a postgres URL like postgres://user:pass@host/db?x-migrations-table=migrate.schema_migrations&x-migrations-table-quoted=true where the table value lacks leading/trailing double quotes.

Common situations: Developers enable x-migrations-table-quoted to support mixed-case or reserved-word table names but forget that the flag requires the value itself to be pre-quoted with escaped double quotes in the URL; this is common after copying a plain x-migrations-table value from an unquoted config.

Related errors

• "%s" MigrationsTable contains too many dot characters
• URL cannot be empty
• no config
• no database name
• no schema

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