Connection Object

class pymysql.connections.Connection(*, user=None, password='', host=None, database=None, unix_socket=None, port=0, charset='', collation=None, sql_mode=None, read_default_file=None, conv=None, use_unicode=True, client_flag=0, cursorclass=<class 'pymysql.cursors.Cursor'>, init_command=None, connect_timeout=10, read_default_group=None, autocommit=False, local_infile=False, max_allowed_packet=16777216, defer_connect=False, auth_plugin_map=None, read_timeout=None, write_timeout=None, bind_address=None, binary_prefix=False, program_name=None, server_public_key=None, ssl=None, ssl_ca=None, ssl_cert=None, ssl_disabled=None, ssl_key=None, ssl_key_password=None, ssl_verify_cert=None, ssl_verify_identity=None, compress=None, named_pipe=None, passwd=None, db=None)

Representation of a socket with a mysql server.

The proper way to get an instance of this class is to call connect().

Establish a connection to the MySQL database. Accepts several arguments:

Parameters:

  • host – Host where the database server is located.

  • user – Username to log in as.

  • password – Password to use.

  • database – Database to use, None to not use a particular one.

  • port – MySQL port to use, default is usually OK. (default: 3306)

  • bind_address – When the client has multiple network interfaces, specify the interface from which to connect to the host. Argument can be a hostname or an IP address.

  • unix_socket – Use a unix socket rather than TCP/IP.

  • read_timeout – The timeout for reading from the connection in seconds. (default: None - no timeout)

  • write_timeout – The timeout for writing to the connection in seconds. (default: None - no timeout)

  • charset (str) – Charset to use.

  • collation (str) – Collation name to use.

  • sql_mode – Default SQL_MODE to use.

  • read_default_file – Specifies my.cnf file to read these parameters from under the [client] section.

  • conv – Conversion dictionary to use instead of the default one. This is used to provide custom marshalling and unmarshalling of types. See converters.

  • use_unicode – Whether or not to default to unicode strings. This option defaults to true.

  • client_flag – Custom flags to send to MySQL. Find potential values in constants.CLIENT.

  • cursorclass – Custom cursor class to use.

  • init_command – Initial SQL statement to run when connection is established.

  • connect_timeout – The timeout for connecting to the database in seconds. (default: 10, min: 1, max: 31536000)

  • ssl – A dict of arguments similar to mysql_ssl_set()’s parameters or an ssl.SSLContext.

  • ssl_ca – Path to the file that contains a PEM-formatted CA certificate.

  • ssl_cert – Path to the file that contains a PEM-formatted client certificate.

  • ssl_disabled – A boolean value that disables usage of TLS.

  • ssl_key – Path to the file that contains a PEM-formatted private key for the client certificate.

  • ssl_key_password – The password for the client certificate private key.

  • ssl_verify_cert – Set to true to check the server certificate’s validity.

  • ssl_verify_identity – Set to true to check the server’s identity.

  • read_default_group – Group to read from in the configuration file.

  • autocommit – Autocommit mode. None means use server default. (default: False)

  • local_infile – Boolean to enable the use of LOAD DATA LOCAL command. (default: False)

  • max_allowed_packet – Max size of packet sent to server in bytes. (default: 16MB) Only used to limit size of “LOAD LOCAL INFILE” data packet smaller than default (16KB).

  • defer_connect – Don’t explicitly connect on construction - wait for connect call. (default: False)

  • auth_plugin_map – A dict of plugin names to a class that processes that plugin. The class will take the Connection object as the argument to the constructor. The class needs an authenticate method taking an authentication packet as an argument. For the dialog plugin, a prompt(echo, prompt) method can be used (if no authenticate method) for returning a string from the user. (experimental)

  • server_public_key – SHA256 authentication plugin public key value. (default: None)

  • binary_prefix – Add _binary prefix on bytes and bytearray. (default: False)

  • compress – Not supported.

  • named_pipe – Not supported.

  • db – DEPRECATED Alias for database.

  • passwd – DEPRECATED Alias for password.

See Connection in the specification.

begin()

Begin transaction.

close()

Send the quit message and close the socket.

See Connection.close() in the specification.

Raises:

Error – If the connection is already closed.

commit()

Commit changes to stable storage.

See Connection.commit() in the specification.

cursor(cursor=None)

Create a new cursor to execute queries with.

Parameters:

cursor (Cursor, SSCursor, DictCursor, or SSDictCursor.) – The type of cursor to create. None means use Cursor.

property open

Return True if the connection is open.

ping(reconnect=True)

Check if the server is alive.

Parameters:

reconnect (boolean) – If the connection is closed, reconnect.

Raises:

Error – If the connection is closed and reconnect=False.

rollback()

Roll back the current transaction.

See Connection.rollback() in the specification.

select_db(db)

Set current db.

Parameters:

db – The name of the db.

set_character_set(charset, collation=None)

Set charaset (and collation)

Send “SET NAMES charset [COLLATE collation]” query. Update Connection.encoding based on charset.

set_charset(charset)

Deprecated. Use set_character_set() instead.

show_warnings()

Send the “SHOW WARNINGS” SQL command.