golang-migrate/migrate · error

unable to parse option x-migrations-table-quoted: %w

Error message

unable to parse option x-migrations-table-quoted: %w

What it means

When opening a pgx/v5 Postgres connection via URL, golang-migrate reads the x-migrations-table-quoted query option and parses it with strconv.ParseBool. If the value is not a valid boolean ('true', 'false', '1', '0', etc.), Open fails with this wrapped parse error. It is a URL-configuration validation error, not a database failure.

Source

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

		return nil, err
	}

	// Driver is registered as pgx, but connection string must use postgres schema
	// when making actual connection
	// i.e. pgx://user:password@host:port/db => postgres://user:password@host:port/db
	purl.Scheme = "postgres"

	db, err := sql.Open("pgx/v5", 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)

View on GitHub (pinned to 01a9643f14)

Solutions

1. Set x-migrations-table-quoted to a value strconv.ParseBool accepts: 1, t, T, TRUE, true, True, 0, f, F, FALSE, false, False
2. Remove the x-migrations-table-quoted parameter entirely if you don't need a quoted migrations table name
3. Verify the value has no surrounding whitespace or shell-mangled characters in the URL
4. Check the underlying strconv error wrapped via %w to see exactly which value failed to parse

Example fix

// before
dsn := "postgres://user:pass@host/db?x-migrations-table-quoted=yes"
// after
dsn := "postgres://user:pass@host/db?x-migrations-table-quoted=true"

u, _ := url.Parse(dsn)
if v := u.Query().Get("x-migrations-table-quoted"); v != "" {
    if _, err := strconv.ParseBool(v); err != nil {
        return fmt.Errorf("invalid x-migrations-table-quoted %q: %w", v, err)
    }
}

func validBoolOption(v string) bool {
    _, err := strconv.ParseBool(v)
    return err == nil
}

if err := m.Up(); err != nil {
    var parseErr *strconv.NumError
    if strings.Contains(err.Error(), "unable to parse option x-migrations-table-quoted") {
        log.Fatalf("fix the DSN boolean option: %v", err)
    }
    _ = parseErr
}

When it happens

Trigger: Calling postgres.Withpgx5/Driver Open (or database/sql registration) with a connection URL containing x-migrations-table-quoted set to a non-boolean value, e.g. postgres://user:pass@host/db?x-migrations-table-quoted=yes or =TRUE (uppercase is invalid for ParseBool).

Common situations: Typo in the option value, copying 'True'/'yes'/'on' from documentation or another library, shell quoting stripping or mangling the value, or programmatically interpolating a non-boolean variable into the DSN.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• unable to parse option x-multi-statement: %w
• unable to parse option x-migrations-table-quoted: %w
• no database name
• x-migrations-table must be quoted (for instance '"migrate"."
• unable to parse option x-multi-statement: %w

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