bytebase/bytebase · error

failed to prepare query: %s

Error message

failed to prepare query: %s

What it means

listPartitionTables prepares the partition-metadata query against information_schema.PARTITIONS with database.DatabaseScopeToMySQLDatabaseName(...). PrepareContext fails before execution — the SQL could not be compiled/validated by the server or the driver. The wrapper includes the full query text for diagnosis.

Source

Thrown at backend/plugin/db/tidb/sync.go:590

func (d *Driver) listPartitionTables(ctx context.Context, databaseName string) (map[db.TableKey][]*storepb.TablePartitionMetadata, error) {
	const query string = `
		SELECT
			TABLE_NAME,
			PARTITION_NAME,
			SUBPARTITION_NAME,
			PARTITION_METHOD,
			SUBPARTITION_METHOD,
			PARTITION_EXPRESSION,
			SUBPARTITION_EXPRESSION,
			PARTITION_DESCRIPTION
		FROM INFORMATION_SCHEMA.PARTITIONS
		WHERE TABLE_SCHEMA = ? AND PARTITION_NAME IS NOT NULL
		ORDER BY TABLE_NAME ASC, PARTITION_NAME ASC, SUBPARTITION_NAME ASC, PARTITION_ORDINAL_POSITION ASC, SUBPARTITION_ORDINAL_POSITION ASC;
	`
	// Prepare the query statement.
	stmt, err := d.db.PrepareContext(ctx, query)
	if err != nil {
		return nil, errors.Wrapf(err, "failed to prepare query: %s", query)
	}
	defer stmt.Close()
	rows, err := stmt.QueryContext(ctx, databaseName)
	if err != nil {
		return nil, util.FormatErrorWithQuery(err, query)
	}
	defer rows.Close()

	type partitionKey struct {
		tableName     string
		partitionName string
	}

	partitionMap := make(map[partitionKey]int)
	result := make(map[db.TableKey][]*storepb.TablePartitionMetadata)

	for rows.Next() {
		var tableName, partitionName, partitionMethod string

View on GitHub (pinned to 1870550677)

Solutions

1. Retry the sync — prepare failures over a healthy network are usually transient connection issues.
2. Verify connectivity to TiDB (ping/Telnet to host:port) and check that credentials and the DSN are valid.
3. Check server logs for aborted connections; raise proxy/LB idle timeouts if connections are being dropped.
4. Inspect the wrapped error text — if it names SQL syntax or privilege problems, fix those specifically (though this static query rarely fails for those reasons).

// check connectivity before sync
if err := sqlDB.PingContext(ctx); err != nil {
	return fmt.Errorf("database unreachable before sync: %w", err)
}

When it happens

Trigger: Calling listPartitionTables when the database connection is broken/closed, the context is canceled before prepare completes, or the server rejects the statement (rare for static SQL; more commonly a dead connection or driver issue).

Common situations: Connection dropped by TiDB or a proxy between syncs; context deadline exceeded while the server is overloaded; using a connection pool after the database was restarted; unix-socket vs TCP misconfiguration making the server unreachable at prepare time.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• failed to iterate mysql.user
• failed to iterate rows
• failed to fetch table comments
• failed to get connection
• expecting variable %s, but got %s

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/ab9c5d98e09e0b8e. Report an issue: GitHub.