mysql.connector.fabric package

Submodules

mysql.connector.fabric.balancing module

Implementing load balancing

class mysql.connector.fabric.balancing.BaseScheduling[source]

Bases: object

Base class for all scheduling classes dealing with load balancing

get_next()[source]

Returns the next member

members

Returns the members of this loadbalancer

ratios

Returns the ratios for all members

set_members(*args)[source]

Set members and ratios

This methods sets the members using the arguments passed. Each argument must be a sequence where the second item is the weight. The first element is an identifier. For example:

(‘server1’, 0.6), (‘server2’, 0.8)

Setting members means that the load will be reset. If the members are the same as previously set, nothing will be reset or set.

If no arguments were given the members will be set to an empty list.

Raises ValueError when weight can’t be converted to a Decimal.

class mysql.connector.fabric.balancing.WeightedRoundRobin(*args)[source]

Bases: mysql.connector.fabric.balancing.BaseScheduling

Class for doing Weighted Round Robin balancing

get_next()[source]

Returns the next member

load

Returns the current load

reset()[source]

Reset the load

set_members(*args)[source]

Set members and ratios

This methods sets the members using the arguments passed. Each argument must be a sequence where the second item is the weight. The first element is an identifier. For example:

(‘server1’, 0.6), (‘server2’, 0.8)

Setting members means that the load will be reset. If the members are the same as previously set, nothing will be reset or set.

If no arguments were given the members will be set to an empty list.

Raises ValueError when weight can’t be converted to a Decimal.

mysql.connector.fabric.caching module

Implementing caching mechanisms for MySQL Fabric

class mysql.connector.fabric.caching.CacheEntry(version=None, fabric_uuid=None, ttl=60)[source]

Bases: object

Base class for MySQL Fabric cache entries

classmethod hash_index(part1, part2=None)[source]

Create hash for indexing

invalid

Returns True if entry is not valid any longer

This property returns True when the entry is not valid any longer. The entry is valid when now > (last updated + ttl), where ttl is in seconds.

invalidate()[source]

Invalidates the cache entry

reset_ttl()[source]

Reset the Time to Live

class mysql.connector.fabric.caching.CacheGroup(group_name, servers)[source]

Bases: mysql.connector.fabric.caching.CacheEntry

Cache entry for a Fabric group

classmethod hash_index(part1, part2=None)[source]

Create hash for indexing

class mysql.connector.fabric.caching.CacheShardTable(shard, version=None, fabric_uuid=None)[source]

Bases: mysql.connector.fabric.caching.CacheEntry

Cache entry for a Fabric sharded table

add_partition(key, group)[source]

Add sharding information for a group

classmethod hash_index(part1, part2=None)[source]

Create hash for indexing

class mysql.connector.fabric.caching.FabricCache(ttl=60)[source]

Bases: object

Singleton class for caching Fabric data

Only one instance of this class can exists globally.

cache_group(group_name, servers)[source]

Cache information about a group

Search cache for a group based on its name

remove_group(entry_hash)[source]

Remove cache entry for group

remove_shardtable(entry_hash)[source]

Remove cache entry for shard

sharding_cache_table(shard, version=None, fabric_uuid=None)[source]

Cache information about a shard

Search cache for a shard based on database and table

mysql.connector.fabric.caching.insort_right_rev(alist, new_element, low=0, high=None)[source]

Similar to bisect.insort_right but for reverse sorted lists

This code is similar to the Python code found in Lib/bisect.py. We simply change the comparison from ‘less than’ to ‘greater than’.

mysql.connector.fabric.connection module

Implementing communication with MySQL Fabric

class mysql.connector.fabric.connection.Fabric(host, username=None, password=None, port=None, connect_attempts=3, connect_delay=1, report_errors=False, ssl_ca=None, ssl_key=None, ssl_cert=None, user=None, protocol='xmlrpc')[source]

Bases: object

Class managing MySQL Fabric instances

execute(group, command, *args, **kwargs)[source]

Execute a Fabric command from given group

This method will execute the given Fabric command from the given group using the given arguments. It returns an instance of FabricSet.

Raises ValueError when group.command is not valid and raises InterfaceError when an error occurs while executing.

Returns FabricSet.

get_fabric_servers(fabric_cnx=None)[source]

Get all MySQL Fabric instances

This method looks up the other MySQL Fabric instances which uses the same metadata. The returned list contains dictionaries with connection information such ass host and port. For example:

[
{‘host’: ‘fabric_prod_1.example.com’, ‘port’: 32274 }, {‘host’: ‘fabric_prod_2.example.com’, ‘port’: 32274 },

]

Returns a list of dictionaries

get_group_server(group, mode=None, status=None)[source]

Get a MySQL server from a group

The method uses MySQL Fabric to get the correct MySQL server for the specified group. You can specify mode or status, but not both.

The mode argument will decide whether the primary or a secondary server is returned. When no secondary server is available, the primary is returned.

Status is used to force getting either a primary or a secondary.

The returned tuple contains host, port and uuid.

Raises InterfaceError on errors; ValueError when both mode and status are given.

Returns a FabricMySQLServer object.

get_group_servers(group, use_cache=True)[source]

Get all MySQL servers in a group

This method returns information about all MySQL part of the given high-availability group. When use_cache is set to True, the cached information will be used.

Raises InterfaceError on errors.

Returns list of FabricMySQLServer objects.

get_instance()[source]

Get a MySQL Fabric Instance

This method will get the next available MySQL Fabric Instance.

Raises InterfaceError when no instance is available or connected.

get_shard_server(tables, key, scope='LOCAL', mode=None)[source]

Get MySQL server information for a particular shard

Raises DatabaseError when the table is unknown or when tables are not on the same shard. ValueError is raised when there is a problem with the methods arguments. InterfaceError is raised for other errors.

get_sharding_information(tables=None, database=None)[source]

Get and cache the sharding information for given tables

This method is fetching sharding information from MySQL Fabric and caches the result. The tables argument must be sequence of sequences contain the name of the database and table. If no database is given, the value for the database argument will be used.

Examples:

tables = [(‘salary’,), (‘employees’,)] get_sharding_information(tables, database=’employees’)

tables = [(‘salary’, ‘employees’), (‘employees’, employees)] get_sharding_information(tables)

Raises InterfaceError on errors; ValueError when something is wrong with the tables argument.

password

Return password used to authenticate with Fabric

report_failure(server_uuid, errno)[source]

Report failure to Fabric

This method sets the status of a MySQL server identified by server_uuid.

reset_cache(group=None)[source]

Reset cached information

This method destroys all cached information.

seed(host=None, port=None)[source]

Get MySQL Fabric Instances

This method uses host and port to connect to a MySQL Fabric server and get all the instances managing the same metadata.

Raises InterfaceError on errors.

ssl_config

Return the SSL configuration

username

Return username used to authenticate with Fabric

class mysql.connector.fabric.connection.FabricConnection(fabric, host, port=32274, connect_attempts=3, connect_delay=1)[source]

Bases: object

Base Class for a class holding a connection to a MySQL Fabric server

connect()[source]

Connect with MySQL Fabric

host

Returns server IP or name of current Fabric connection

is_connected

Check whether connection with Fabric is valid

Return True if we can still interact with the Fabric server; False if Not.

Returns True or False.

port

Returns TCP/IP port of current Fabric connection

uuid

Returns UUID of the Fabric server we are connected with

class mysql.connector.fabric.connection.FabricHTTPSHandler(ssl_config)[source]

Bases: urllib.request.HTTPSHandler

Class handling HTTPS connections

get_https_connection(host, timeout=300)[source]

Returns a HTTPSConnection

https_open(req)[source]

Open HTTPS connection

class mysql.connector.fabric.connection.FabricMySQLConnection(fabric, host, port=32275, connect_attempts=3, connect_delay=1)[source]

Bases: mysql.connector.fabric.connection.FabricConnection

Class holding a connection to a MySQL Fabric server through MySQL protocol

connect()[source]

Connect with MySQL Fabric

connection

Returns the MySQL RPC Connection to Fabric

is_connected

Check whether connection with Fabric is valid

Return True if we can still interact with the Fabric server; False if Not.

Returns True or False.

class mysql.connector.fabric.connection.FabricMySQLResponse(data)[source]

Bases: object

Class used to parse a response got from Fabric with MySQL protocol.

class mysql.connector.fabric.connection.FabricMySQLSet(data)[source]

Bases: mysql.connector.fabric.connection.FabricMySQLResponse

Iterator to navigate through the result set returned from Fabric with MySQL Protocol.

row(index)[source]

Indexing method for a row.

Each row is a named tuple.

rowcount()[source]

The number of rows in the result set.

rows()[source]

Iterate over the rows of the result set.

Each row is a named tuple.

class mysql.connector.fabric.connection.FabricResponse(data)[source]

Bases: object

Class used to parse a response got from Fabric.

SUPPORTED_VERSION = 1
class mysql.connector.fabric.connection.FabricSet(data)[source]

Bases: mysql.connector.fabric.connection.FabricResponse

Iterator to navigate through the result set returned from Fabric

row(index)[source]

Indexing method for a row.

Each row is a named tuple.

rowcount()[source]

The number of rows in the result set.

rows()[source]

Iterate over the rows of the result set.

Each row is a named tuple.

class mysql.connector.fabric.connection.FabricTransport(username, password, verbose=0, use_datetime=False, https_handler=None)[source]

Bases: xmlrpc.client.Transport

Custom XMLRPC Transport for Fabric

request(host, handler, request_body, verbose=0)[source]

Send XMLRPC request

user_agent = 'MySQL Connector Python/2.2.9'
class mysql.connector.fabric.connection.FabricXMLRPCConnection(fabric, host, port=32274, connect_attempts=3, connect_delay=1)[source]

Bases: mysql.connector.fabric.connection.FabricConnection

Class holding a connection to a MySQL Fabric server through XML-RPC

connect()[source]

Connect with MySQL Fabric

is_connected

Check whether connection with Fabric is valid

Return True if we can still interact with the Fabric server; False if Not.

Returns True or False.

proxy

Returns the XMLRPC Proxy of current Fabric connection

uri

Returns the XMLRPC URI for current Fabric connection

class mysql.connector.fabric.connection.MySQLFabricConnection(**kwargs)[source]

Bases: object

Connection to a MySQL server through MySQL Fabric

close()

Close connection to MySQL server

cmd_query(statement)[source]

Send a statement to the MySQL server

Raises whatever MySQLConnection.cmd_query() raises, but raises MySQLFabricError when MySQL returns error ER_OPTION_PREVENTS_STATEMENT.

Returns a dictionary.

cmd_query_iter(statements)[source]

Send one or more statements to the MySQL server

Raises whatever MySQLConnection.cmd_query_iter() raises, but raises MySQLFabricError when MySQL returns error ER_OPTION_PREVENTS_STATEMENT.

Returns a dictionary.

commit()[source]

Commit current transaction

Raises whatever MySQLConnection.commit() raises, but raises MySQLFabricError when MySQL returns error ER_OPTION_PREVENTS_STATEMENT.

cursor(buffered=None, raw=None, prepared=None, cursor_class=None)[source]

Instantiates and returns a cursor

This method is similar to MySQLConnection.cursor() except that it checks whether the connection is available and raises an InterfaceError when not.

cursor_class argument is not supported and will raise a NotSupportedError exception.

Returns a MySQLCursor or subclass.

disconnect()[source]

Close connection to MySQL server

fabric_uuid

Returns the Fabric UUID of the MySQL server

handle_mysql_error(exc)[source]

Handles MySQL errors

This method takes a mysql.connector.errors.Error exception and checks the error code. Based on the value, it takes certain actions such as clearing the cache.

is_connected()[source]

Check whether we are connected with the MySQL server

Returns True or False

properties

Returns connection properties

reset_cache(group=None)[source]

Reset cache for this connection’s group

reset_properties()[source]

Resets the connection properties

This method can be called to reset the connection properties to their default values.

rollback()[source]

Rollback current transaction

Raises whatever MySQLConnection.rollback() raises, but raises MySQLFabricError when MySQL returns error ER_OPTION_PREVENTS_STATEMENT.

set_property(**properties)[source]

Set one or more connection properties

Arguments to the set_property() method will be used as properties. They are validated against the _CNX_PROPERTIES constant.

Raise ValueError in case an invalid property is being set. TypeError is raised when the type of the value is not correct.

To unset a property, set it to None.

store_config(**kwargs)[source]

Store configuration of MySQL connections to use with Fabric

The configuration found in the dictionary kwargs is used when instanciating a MySQLConnection object. The host and port entries are used to connect to MySQL Fabric.

Raises ValueError when the Fabric configuration parameter is not correct or missing; AttributeError is raised when when a paramater is not valid.

class mysql.connector.fabric.connection.MySQLRPCProtocol(fabric, host, port, connect_attempts, connect_delay)[source]

Bases: object

Class using MySQL protocol to query Fabric.

create_params(*args, **kwargs)[source]

Process arguments to create query parameters.

execute(group, command, *args, **kwargs)[source]

Executes the given command with MySQL protocol

Executes the given command with the given parameters.

Returns an iterator to navigate to navigate through the result set returned by Fabric

class mysql.connector.fabric.connection.XMLRPCProtocol(fabric, host, port, connect_attempts, connect_delay)[source]

Bases: object

Class using XML-RPC protocol to query Fabric.

execute(group, command, *args, **kwargs)[source]

Executes the given command with XML-RPC protocol

Executes the given command with the given parameters

Returns an iterator to navigate to navigate through the result set returned by Fabric

mysql.connector.fabric.connection.extra_failure_report(error_codes)[source]

Add MySQL error to be reported to Fabric

This function adds error_codes to the error list to be reported to Fabric. To reset the custom error reporting list, pass None or empty list.

The error_codes argument can be either a MySQL error code defined in the errorcode module, or list of error codes.

Raises AttributeError when code is not an int.

Module contents

MySQL Fabric support

class mysql.connector.fabric.FabricMySQLServer(uuid, group, host, port, mode, status, weight)

Bases: tuple

group

Alias for field number 1

host

Alias for field number 2

mode

Alias for field number 4

port

Alias for field number 3

status

Alias for field number 5

uuid

Alias for field number 0

weight

Alias for field number 6

class mysql.connector.fabric.FabricShard(database, table, column, key, shard, shard_type, group, global_group)

Bases: tuple

column

Alias for field number 2

database

Alias for field number 0

global_group

Alias for field number 7

group

Alias for field number 6

key

Alias for field number 3

shard

Alias for field number 4

shard_type

Alias for field number 5

table

Alias for field number 1

mysql.connector.fabric.connect(**kwargs)[source]

Create a MySQLFabricConnection object

class mysql.connector.fabric.Fabric(host, username=None, password=None, port=None, connect_attempts=3, connect_delay=1, report_errors=False, ssl_ca=None, ssl_key=None, ssl_cert=None, user=None, protocol='xmlrpc')[source]

Bases: object

Class managing MySQL Fabric instances

execute(group, command, *args, **kwargs)[source]

Execute a Fabric command from given group

This method will execute the given Fabric command from the given group using the given arguments. It returns an instance of FabricSet.

Raises ValueError when group.command is not valid and raises InterfaceError when an error occurs while executing.

Returns FabricSet.

get_fabric_servers(fabric_cnx=None)[source]

Get all MySQL Fabric instances

This method looks up the other MySQL Fabric instances which uses the same metadata. The returned list contains dictionaries with connection information such ass host and port. For example:

[
{‘host’: ‘fabric_prod_1.example.com’, ‘port’: 32274 }, {‘host’: ‘fabric_prod_2.example.com’, ‘port’: 32274 },

]

Returns a list of dictionaries

get_group_server(group, mode=None, status=None)[source]

Get a MySQL server from a group

The method uses MySQL Fabric to get the correct MySQL server for the specified group. You can specify mode or status, but not both.

The mode argument will decide whether the primary or a secondary server is returned. When no secondary server is available, the primary is returned.

Status is used to force getting either a primary or a secondary.

The returned tuple contains host, port and uuid.

Raises InterfaceError on errors; ValueError when both mode and status are given.

Returns a FabricMySQLServer object.

get_group_servers(group, use_cache=True)[source]

Get all MySQL servers in a group

This method returns information about all MySQL part of the given high-availability group. When use_cache is set to True, the cached information will be used.

Raises InterfaceError on errors.

Returns list of FabricMySQLServer objects.

get_instance()[source]

Get a MySQL Fabric Instance

This method will get the next available MySQL Fabric Instance.

Raises InterfaceError when no instance is available or connected.

get_shard_server(tables, key, scope='LOCAL', mode=None)[source]

Get MySQL server information for a particular shard

Raises DatabaseError when the table is unknown or when tables are not on the same shard. ValueError is raised when there is a problem with the methods arguments. InterfaceError is raised for other errors.

get_sharding_information(tables=None, database=None)[source]

Get and cache the sharding information for given tables

This method is fetching sharding information from MySQL Fabric and caches the result. The tables argument must be sequence of sequences contain the name of the database and table. If no database is given, the value for the database argument will be used.

Examples:

tables = [(‘salary’,), (‘employees’,)] get_sharding_information(tables, database=’employees’)

tables = [(‘salary’, ‘employees’), (‘employees’, employees)] get_sharding_information(tables)

Raises InterfaceError on errors; ValueError when something is wrong with the tables argument.

password

Return password used to authenticate with Fabric

report_failure(server_uuid, errno)[source]

Report failure to Fabric

This method sets the status of a MySQL server identified by server_uuid.

reset_cache(group=None)[source]

Reset cached information

This method destroys all cached information.

seed(host=None, port=None)[source]

Get MySQL Fabric Instances

This method uses host and port to connect to a MySQL Fabric server and get all the instances managing the same metadata.

Raises InterfaceError on errors.

ssl_config

Return the SSL configuration

username

Return username used to authenticate with Fabric

class mysql.connector.fabric.FabricConnection(fabric, host, port=32274, connect_attempts=3, connect_delay=1)[source]

Bases: object

Base Class for a class holding a connection to a MySQL Fabric server

connect()[source]

Connect with MySQL Fabric

host

Returns server IP or name of current Fabric connection

is_connected

Check whether connection with Fabric is valid

Return True if we can still interact with the Fabric server; False if Not.

Returns True or False.

port

Returns TCP/IP port of current Fabric connection

uuid

Returns UUID of the Fabric server we are connected with

class mysql.connector.fabric.MySQLFabricConnection(**kwargs)[source]

Bases: object

Connection to a MySQL server through MySQL Fabric

close()

Close connection to MySQL server

cmd_query(statement)[source]

Send a statement to the MySQL server

Raises whatever MySQLConnection.cmd_query() raises, but raises MySQLFabricError when MySQL returns error ER_OPTION_PREVENTS_STATEMENT.

Returns a dictionary.

cmd_query_iter(statements)[source]

Send one or more statements to the MySQL server

Raises whatever MySQLConnection.cmd_query_iter() raises, but raises MySQLFabricError when MySQL returns error ER_OPTION_PREVENTS_STATEMENT.

Returns a dictionary.

commit()[source]

Commit current transaction

Raises whatever MySQLConnection.commit() raises, but raises MySQLFabricError when MySQL returns error ER_OPTION_PREVENTS_STATEMENT.

cursor(buffered=None, raw=None, prepared=None, cursor_class=None)[source]

Instantiates and returns a cursor

This method is similar to MySQLConnection.cursor() except that it checks whether the connection is available and raises an InterfaceError when not.

cursor_class argument is not supported and will raise a NotSupportedError exception.

Returns a MySQLCursor or subclass.

disconnect()[source]

Close connection to MySQL server

fabric_uuid

Returns the Fabric UUID of the MySQL server

handle_mysql_error(exc)[source]

Handles MySQL errors

This method takes a mysql.connector.errors.Error exception and checks the error code. Based on the value, it takes certain actions such as clearing the cache.

is_connected()[source]

Check whether we are connected with the MySQL server

Returns True or False

properties

Returns connection properties

reset_cache(group=None)[source]

Reset cache for this connection’s group

reset_properties()[source]

Resets the connection properties

This method can be called to reset the connection properties to their default values.

rollback()[source]

Rollback current transaction

Raises whatever MySQLConnection.rollback() raises, but raises MySQLFabricError when MySQL returns error ER_OPTION_PREVENTS_STATEMENT.

set_property(**properties)[source]

Set one or more connection properties

Arguments to the set_property() method will be used as properties. They are validated against the _CNX_PROPERTIES constant.

Raise ValueError in case an invalid property is being set. TypeError is raised when the type of the value is not correct.

To unset a property, set it to None.

store_config(**kwargs)[source]

Store configuration of MySQL connections to use with Fabric

The configuration found in the dictionary kwargs is used when instanciating a MySQLConnection object. The host and port entries are used to connect to MySQL Fabric.

Raises ValueError when the Fabric configuration parameter is not correct or missing; AttributeError is raised when when a paramater is not valid.

class mysql.connector.fabric.FabricSet(data)[source]

Bases: mysql.connector.fabric.connection.FabricResponse

Iterator to navigate through the result set returned from Fabric

row(index)[source]

Indexing method for a row.

Each row is a named tuple.

rowcount()[source]

The number of rows in the result set.

rows()[source]

Iterate over the rows of the result set.

Each row is a named tuple.