10.5.2 MySQLCursor.add_attribute() Method

Syntax:

cursor.add_attribute(name, value)

Adds a new named query attribute to the list, as part of MySQL server's Query Attributes functionality.

name: The name must be a string, but no other validation checks are made; attributes are sent as is to the server and errors, if any, will be detected and reported by the server.

value: a value converted to the MySQL Binary Protocol, similar to how prepared statement parameters are converted. An error is reported if the conversion fails.

Query attributes must be enabled on the server, and are disabled by default. A warning is logged when setting query attributes server connection that does not support them. See also Prerequisites for Using Query Attributes for enabling the query_attributes MySQL server component.

Example query attribute usage:

#  Each invocation of `add_attribute` method will add a new query attribute:
    cur.add_attribute("foo", 2)
    cur.execute("SELECT first_name, last_name FROM clients")
	# The query above sent attibute "foo" with value 2.

    cur.add_attribute(*("bar", "3"))
    cur.execute("SELECT * FROM products WHERE price < ?", 10)
	# The query above sent attibutes ("foo", 2)  and ("bar", "3").

	my_attributes = [("page_name", "root"), ("previous_page", "login")]
    for attribute_tuple in my_attributes:
		cur.add_attribute(*attribute_tuple)
    cur.execute("SELECT * FROM offers WHERE publish = ?", 0)
	# The query above sent 4 attibutes.

# To check the current query attributes:

	print(cur.get_attributes())
	# prints:
	[("foo", 2), ("bar", "3"), ("page_name", "root"), ("previous_page", "login")]

# Query attributes are not cleared until the cursor is closed or 
# of the clear_attributes() method is invoked:
    
	cur.clear_attributes()
    print(cur.get_attributes())
	# prints:
	[]
    cur.execute("SELECT first_name, last_name FROM clients")
    # The query above did not send any attibute.

This method was added in Connector/Python 8.0.26.