pydoc > pymysql

man perldoc info pydoc3 ri search

🏷️ NAME

pymysql - PyMySQL: A pure-Python MySQL client library.

🚀 Quick Reference

Use Case	Command	Description
🔌 Connect	pymysql.connect(host='...', user='...', password='...', database='...')	Open a MySQL connection
📋 Execute query	cursor.execute("SELECT * FROM t")	Run a SQL statement
📥 Fetch one row	cursor.fetchone()	Get next result row
📥 Fetch all rows	cursor.fetchall()	Get all remaining rows
💾 Commit	connection.commit()	Save transaction changes
⏪ Rollback	connection.rollback()	Undo transaction changes
🔄 Autocommit	connection.autocommit(True)	Enable automatic commit
🚪 Close	connection.close()	Close the connection
🐍 Dict cursor	pymysql.cursors.DictCursor	Return rows as dictionaries
🛡️ SSL connection	pymysql.connect(..., ssl_ca='ca.pem', ssl_cert='cert.pem', ssl_key='key.pem')	Secure connection with certificates

📖 DESCRIPTION

Copyright (c) 2010-2016 PyMySQL contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

📦 PACKAGE CONTENTS

• _auth
• charset
• connections
• constants (package)
• converters
• cursors
• err
• optionfile
• protocol
• times

🔌 SUBMODULES

• FIELD_TYPE

🏛️ CLASSES

Exception hierarchy:

builtins.Exception(builtins.BaseException)
    pymysql.err.MySQLError
        pymysql.err.Error
            pymysql.err.DatabaseError
                pymysql.err.DataError
                pymysql.err.IntegrityError
                pymysql.err.InternalError
                pymysql.err.NotSupportedError
                pymysql.err.OperationalError
                pymysql.err.ProgrammingError
            pymysql.err.InterfaceError
        pymysql.err.Warning(builtins.Warning, pymysql.err.MySQLError)
builtins.Warning(builtins.Exception)
    pymysql.err.Warning(builtins.Warning, pymysql.err.MySQLError)
builtins.frozenset(builtins.object)
    DBAPISet
builtins.object
    datetime.date
        datetime.datetime
    datetime.time
    pymysql.connections.Connection

🧩 Connection

Connect = class Connection(builtins.object) — Alias for pymysql.connections.Connection.

Representation of a socket with a mysql server. The proper way to get an instance is to call connect().

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

• ⚙️ 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: 3306).
• 🌐 bind_address: Interface to connect from (hostname or IP).
• 🔗 unix_socket: Use a unix socket rather than TCP/IP.
• ⏱️ read_timeout: Timeout for reading in seconds (default: None).
• ⏱️ write_timeout: Timeout for writing in seconds (default: None).
• 🔤 charset: Charset to use.
• 🔤 collation: Collation name to use.
• 📐 sql_mode: Default SQL_MODE.
• 📄 read_default_file: Specifies my.cnf file to read parameters from under the [client] section.
• 🔄 conv: Conversion dictionary for custom marshalling/unmarshalling. See converters.
• 🔡 use_unicode: Whether to default to unicode strings (default: True).
• 🏳️ client_flag: Custom flags to send to MySQL (values in constants.CLIENT).
• 🖱️ cursorclass: Custom cursor class to use (default: pymysql.cursors.Cursor).
• 🚀 init_command: Initial SQL statement to run when connection is established.
• ⏳ connect_timeout: Timeout for connecting (default: 10, min: 1, max: 31536000).
• 🛡️ ssl: An ssl.SSLContext, or a dict (deprecated; use individual ssl_* params).
• 📜 ssl_ca: Path to PEM-formatted CA certificate.
• 📜 ssl_cert: Path to PEM-formatted client certificate.
• 🚫 ssl_disabled: Disable TLS (True prohibits TLS even if server supports it).
• 🔐 ssl_key: Path to PEM-formatted private key.
• 🔑 ssl_key_password: Password for the client certificate private key.
• ✅ ssl_verify_cert: Check server certificate's validity.
• ✅ ssl_verify_identity: Check server's identity.
• 📂 read_default_group: Group to read from in the configuration file.
• 🔄 autocommit: Autocommit mode (None = server default; default: False).
• 📂 local_infile: Enable LOAD DATA LOCAL command (default: False).
• 📦 max_allowed_packet: Max size of packet sent to server (default: 16MB).
• ⏸️ defer_connect: Don't connect on construction; wait for connect call (default: False).
• 🧩 auth_plugin_map: Dict of plugin names to classes for authentication (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.

🛠️ Connection Methods

• __del__ = _force_close(self)
• __enter__(self)
• __exit__(self, *exc_info)
• __init__(self, *, 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) — Initialize self.
• affected_rows(self)
• autocommit(self, value)
• begin(self) — Begin transaction.
• character_set_name(self)
• close(self) — Send the quit message and close the socket. See Connection.close(). Raises Error if already closed.
• commit(self) — Commit changes to stable storage. See Connection.commit().
• connect(self, sock=None)
• cursor(self, cursor=None) — Create a new cursor to execute queries with. cursor type: Cursor, SSCursor, DictCursor, or SSDictCursor.
• escape(self, obj, mapping=None) — Escape whatever value is passed. Non‑standard, internal use only.
• escape_string(self, s)
• get_autocommit(self)
• get_host_info(self)
• get_proto_info(self)
• get_server_info(self)
• insert_id(self)
• kill(self, thread_id)
• literal(self, obj) — Alias for escape(). Non‑standard, internal use only.
• next_result(self, unbuffered=False)
• ping(self, reconnect=False) — Check if the server is alive. reconnect is deprecated; create a new connection. Raises Error if closed and reconnect=False.
• query(self, sql, unbuffered=False) — # The following methods are INTERNAL USE ONLY (called from Cursor)
• rollback(self) — Roll back the current transaction. See Connection.rollback().
• select_db(self, db) — Set current db.
• set_character_set(self, charset, collation=None) — Send "SET NAMES" query, update Connection.encoding.
• set_charset(self, charset) — Deprecated. Use set_character_set().
• show_warnings(self) — Send "SHOW WARNINGS".
• thread_id(self) — # _mysql support
• write_packet(self, payload) — Writes an entire mysql packet to the network adding its length and sequence number.

📖 Readonly Properties

• open — Return True if the connection is open.

📊 Data Descriptors

• __dict__ — dictionary for instance variables
• __weakref__ — list of weak references to the object

📊 Data and Other Attributes

DataError = <class 'pymysql.err.DataError'>
DatabaseError = <class 'pymysql.err.DatabaseError'>
Error = <class 'pymysql.err.Error'>
IntegrityError = <class 'pymysql.err.IntegrityError'>
InterfaceError = <class 'pymysql.err.InterfaceError'>
InternalError = <class 'pymysql.err.InternalError'>
NotSupportedError = <class 'pymysql.err.NotSupportedError'>
OperationalError = <class 'pymysql.err.OperationalError'>
ProgrammingError = <class 'pymysql.err.ProgrammingError'>
Warning = <class 'pymysql.err.Warning'>

🧩 DBAPISet

class DBAPISet(builtins.frozenset)

Methods defined here:

• __eq__(self, other) — Return self==value.
• __hash__(self) — Return hash(self).
• __ne__(self, other) — Return self!=value.

Inherits from frozenset (all set operations).

❌ DataError

class DataError(DatabaseError)

Exception raised for errors due to problems with processed data (division by zero, numeric value out of range, etc.).

Inherits from DatabaseError → Error → MySQLError → Exception.

❌ DatabaseError

class DatabaseError(Error)

Exception raised for errors related to the database.

❌ Error

class Error(MySQLError)

Base class of all error exceptions (not Warning).

❌ IntegrityError

class IntegrityError(DatabaseError)

Exception raised when relational integrity is affected (foreign key check fails, duplicate key, etc.).

❌ InterfaceError

class InterfaceError(Error)

Exception raised for errors related to the database interface rather than the database itself.

❌ InternalError

class InternalError(DatabaseError)

Exception raised when the database encounters an internal error (cursor invalid, transaction out of sync, etc.).

❌ NotSupportedError

class NotSupportedError(DatabaseError)

Exception raised when a method or database API is used that is not supported by the database (e.g., .rollback() on a connection without transactions).

❌ OperationalError

class OperationalError(DatabaseError)

Exception raised for errors related to the database's operation (unexpected disconnect, data source name not found, transaction processing failure, memory allocation error, etc.).

❌ ProgrammingError

class ProgrammingError(DatabaseError)

Exception raised for programming errors (table not found or already exists, syntax error in SQL, wrong number of parameters, etc.).

⚠️ Warning

class Warning(builtins.Warning, MySQLError)

Exception raised for important warnings (data truncations while inserting, etc.).

🕰️ Date

Date = class date(builtins.object)
date(year, month, day) → date object

Standard Python datetime.date.

🕰️ Time

Time = class time(builtins.object)
time([hour[, minute[, second[, microsecond[, tzinfo]]]]]) → a time object

Standard Python datetime.time.

🕰️ Timestamp

Timestamp = class datetime(date)
datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])

Standard Python datetime.datetime.

❌ MySQLError

class MySQLError(builtins.Exception)

Exception related to operation with MySQL.

🛠️ FUNCTIONS

• Binary(x) — Return x as a binary type.
• DateFromTicks(ticks)
• TimeFromTicks(ticks)
• TimestampFromTicks(ticks)
• get_client_info()
• install_as_MySQLdb() — After this function is called, any application that imports MySQLdb will unwittingly actually use pymysql.

📊 DATA

BINARY = DBAPISet({249, 250, 251, 252})
DATE = DBAPISet({10, 14})
NULL = 'NULL'
NUMBER = DBAPISet({0, 1, 3, 4, 5, 8, 9, 13})
ROWID = DBAPISet()
STRING = DBAPISet({253, 254, 247})
TIME = DBAPISet({11})
TIMESTAMP = DBAPISet({12, 7})
__all__ = ['BINARY', 'Binary', 'Connect', 'Connection', 'DATE', 'Date'...]
apilevel = '2.0'
paramstyle = 'pyformat'
threadsafety = 1
version_info = (2, 2, 8, 'final', 1)

🔢 VERSION

2.2.8

📁 FILE

/home/chedong/.local/lib/python3.10/site-packages/pymysql/__init__.py

🏷️ NAME 🚀 Quick Reference 📖 DESCRIPTION 📦 PACKAGE CONTENTS 🔌 SUBMODULES 🏛️ CLASSES 🛠️ FUNCTIONS 📊 DATA 🔢 VERSION 📁 FILE