可以使用 mysql.connector.connect() 函数或 mysql.connector.MySQLConnection() 类建立与 MySQL 服务器的连接。

cnx = mysql.connector.connect(user='joe', database='test')
cnx = MySQLConnection(user='joe', database='test')

下表描述了可用于启动连接的参数。参数后面的星号 (*) 表示同义参数名，仅为了与其他 Python MySQL 驱动程序兼容。Oracle 建议不要使用这些备用名称。

MySQL 身份验证选项

使用 MySQL 进行身份验证通常使用 username 和 password。

当给出 database 参数时，当前数据库将设置为给定的值。要稍后更改当前数据库，请执行 USE SQL 语句或设置 MySQLConnection 实例的 database 属性。

默认情况下，Connector/Python 会尝试连接到本地主机上运行的 MySQL 服务器，使用 TCP/IP。host 参数默认为 IP 地址 127.0.0.1，port 默认为 3306。通过设置 unix_socket 支持 Unix 套接字。不支持 Windows 平台上的命名管道。

Connector/Python 支持从 MySQL 8.0 开始提供的身份验证插件，包括首选的 caching_sha2_password 身份验证插件。

已弃用的 mysql_native_password 插件受支持，但从 MySQL 服务器 8.4.0 开始默认情况下已禁用，从 MySQL 服务器 9.0.0 开始已被移除。

connect() 方法支持 auth_plugin 参数，该参数可用于强制使用特定身份验证插件。

Connector/Python 支持 Kerberos 身份验证协议 以实现无密码身份验证。Linux 客户端从 Connector/Python 8.0.26 开始支持，Windows 支持是在 Connector/Python 8.0.27 中使用 C 扩展实现添加的，并在 Connector/Python 8.0.29 中使用纯 Python 实现添加的。对于 Windows，相关的 kerberos_auth_mode 连接选项是在 8.0.32 中添加的，用于将模式配置为 SSPI（默认）或 GSSAPI（通过纯 Python 实现，或从 8.4.0 开始的 C 扩展实现）。虽然 Windows 支持这两种模式，但 Linux 仅支持 GSSAPI。

以下示例假设 LDAP 可插拔身份验证 已设置好以使用 GSSAPI/Kerberos SASL 身份验证

import mysql.connector as cpy
import logging

logging.basicConfig(level=logging.DEBUG)

SERVICE_NAME = "ldap"
LDAP_SERVER_IP = "server_ip or hostname"  # e.g., winexample01

config = {
    "host": "127.0.0.1",
    "port": 3306,
    "user": "[email protected]",
    "password": "s3cret",
    "use_pure": True,
    "krb_service_principal": f"{SERVICE_NAME}/{LDAP_SERVER_IP}"
}

with cpy.connect(**config) as cnx:
    with cnx.cursor() as cur:
        cur.execute("SELECT @@version")
        res = cur.fetchone()
        print(res[0])

Connector/Python 从 v8.0.28 开始支持多因素身份验证 (MFA)，方法是使用 password1（password 的别名）、password2 和 password3 连接选项。

Connector/Python 从 Connector/Python 8.2.0 开始支持 WebAuthn 可插拔身份验证，该功能在 MySQL 企业版中受支持。可以选择使用 Connector/Python 的 webauthn_callback 连接选项来通知用户需要触摸硬件设备。此功能存在于 C 实现中（使用 libmysqlclient），但纯 Python 实现需要 FIDO2 依赖项，该依赖项未与 MySQL 连接器一起提供，并假定已存在于您的环境中。可以使用以下命令独立安装它

$> pip install fido2

以前，现在已删除（从 8.4.0 版本开始）的 authentication_fido MySQL 服务器插件使用 fido_callback 选项支持，该选项存在于 C 扩展实现中。

字符编码

默认情况下，来自 MySQL 的字符串以 Python Unicode 字符串形式返回。要更改此行为，请将 use_unicode 设置为 False。您可以通过 charset 参数更改客户端连接的字符集设置。要更改连接到 MySQL 后的字符集，请设置 MySQLConnection 实例的 charset 属性。此方法优先于直接使用 SET NAMES SQL 语句。与 charset 属性类似，您可以设置当前 MySQL 会话的 collation。

事务

autocommit 值默认为 False，因此不会自动提交事务。在执行一组相关的插入、更新和删除操作后，在您的应用程序中调用 MySQLConnection 实例的 commit() 方法。为了数据一致性和写入操作的高吞吐量，最好在使用 InnoDB 或其他事务表时关闭 autocommit 配置选项。

时区

可以使用 time_zone 参数为每个连接设置时区。例如，如果 MySQL 服务器设置为 UTC，并且应将 TIMESTAMP 值通过 MySQL 转换为 PST 时区返回，则此方法非常有用。

SQL 模式

MySQL 支持所谓的 SQL 模式，这些模式会全局或按连接更改服务器的行为。例如，要将警告作为错误引发，请将 sql_mode 设置为 TRADITIONAL。有关更多信息，请参见 服务器 SQL 模式。

故障排除和错误处理

将 get_warnings 设置为 True 时，会自动获取查询生成的警告。您还可以通过将 raise_on_warnings 设置为 True 来立即引发异常。请考虑使用 MySQL 的 sql_mode 设置将警告转换为错误。

要设置连接的超时值，请使用 connection_timeout。

使用客户端标志启用和禁用功能

MySQL 使用 客户端标志 来启用或禁用功能。使用 client_flags 参数，您可以控制设置的内容。要找出有哪些标志可用，请使用以下命令

from mysql.connector.constants import ClientFlag
print '\n'.join(ClientFlag.get_full_info())

如果未指定 client_flags（即为零），则对 MySQL 4.1 及更高版本使用默认值。如果指定大于 0 的整数，请确保正确设置所有标志。单独设置和取消设置标志的更好方法是使用列表。例如，要设置 FOUND_ROWS，但禁用默认的 LONG_FLAG

flags = [ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG]
mysql.connector.connect(client_flags=flags)

结果集处理

默认情况下，MySQL Connector/Python 不会缓冲或预取结果。这意味着在执行查询后，您的程序负责获取数据。这可以避免在查询返回大型结果集时过度使用内存。如果您知道结果集足够小，可以一次性处理所有结果，则可以通过将 buffered 设置为 True 来立即获取结果。也可以为每个游标设置此值（参见 第 10.2.6 节，“MySQLConnection.cursor() 方法”）。

查询生成的結果通常不会在客户端程序获取它们之前读取。要自动使用和丢弃结果集，请将 consume_results 选项设置为 True。结果是读取所有结果，对于大型结果集而言，这可能很慢。（在这种情况下，最好关闭并重新打开连接。）

类型转换

默认情况下，结果集中的 MySQL 类型会自动转换为 Python 类型。例如，DATETIME 列值将变为 datetime.datetime 对象。要禁用转换，请将 raw 选项设置为 True。您可能会这样做来获得更好的性能或自行执行不同类型的转换。

通过 SSL 连接

当您的 Python 安装支持 SSL 时，可以使用 SSL 连接，即当它针对 OpenSSL 库进行编译时。当您提供 ssl_ca、ssl_key 和 ssl_cert 选项时，连接将切换到 SSL，并且 client_flags 选项将自动包含 ClientFlag.SSL 值。您可以将其与 compressed 选项设置为 True 结合使用。

从 Connector/Python 2.2.2 开始，如果 MySQL 服务器支持 SSL 连接，Connector/Python 将尝试默认建立安全（加密）连接，否则将回退到非加密连接。

从 Connector/Python 1.2.1 到 Connector/Python 2.2.1，可以使用仅 ssl_ca 选项建立 SSL 连接。ssl_key 和 ssl_cert 参数是可选的。但是，如果给出了其中一个，则必须给出两个，否则会引发 AttributeError。

# Note (Example is valid for Python v2 and v3)
from __future__ import print_function

import sys

#sys.path.insert(0, 'python{0}/'.format(sys.version_info[0]))

import mysql.connector
from mysql.connector.constants import ClientFlag

config = {
    'user': 'ssluser',
    'password': 'password',
    'host': '127.0.0.1',
    'client_flags': [ClientFlag.SSL],
    'ssl_ca': '/opt/mysql/ssl/ca.pem',
    'ssl_cert': '/opt/mysql/ssl/client-cert.pem',
    'ssl_key': '/opt/mysql/ssl/client-key.pem',
}

cnx = mysql.connector.connect(**config)
cur = cnx.cursor(buffered=True)
cur.execute("SHOW STATUS LIKE 'Ssl_cipher'")
print(cur.fetchone())
cur.close()
cnx.close()

连接池

当存在 pool_name 或 pool_size 参数时，Connector/Python 会创建新的池。如果未给出 pool_name 参数，则 connect() 调用会自动生成名称，该名称由给出的 host、port、user 和 database 连接参数组成，顺序为从左到右。如果未给出 pool_size 参数，则默认大小为 5 个连接。

pool_reset_session 允许控制将连接返回到池时是否重置会话变量。默认行为是重置它们。

有关连接池的更多信息，请参见 第 9.4 节，“Connector/Python 连接池”。

协议压缩

布尔值 compress 参数指示是否使用压缩的客户端/服务器协议（默认值为 False）。这为设置 ClientFlag.COMPRESS 标志提供了一种更简单的替代方法。此参数从 Connector/Python 1.1.2 开始可用。

转换器类

converter_class 参数接受一个类并在配置连接时设置它。如果自定义转换器类不是 conversion.MySQLConverterBase 的子类，则会引发 AttributeError。

服务器故障转移

connect() 方法接受一个 failover 参数，该参数提供有关在连接失败时用于服务器故障转移的信息。参数值是字典的元组或列表（元组更可取，因为它不可变）。每个字典都包含故障转移序列中给定服务器的连接参数。允许的字典值是：user、password、host、port、unix_socket、database、pool_name、pool_size。此故障转移选项是在 Connector/Python 1.2.1 中添加的。

选项文件支持

从 Connector/Python 2.0.0 开始，选项文件使用两个选项支持 connect()

有关更多信息，请参见 第 7.2 节，“Connector/Python 选项文件支持”。

LOAD DATA LOCAL INFILE

在 Connector/Python 2.0.0 之前，要启用使用 LOAD DATA LOCAL INFILE，客户端必须显式设置 ClientFlag.LOCAL_FILES 标志。从 2.0.0 开始，此标志默认启用。要禁用它，可以在连接时将 allow_local_infile 连接选项设置为 False（默认值为 True）。

与其他连接接口的兼容性

passwd、db 和 connect_timeout 对其他 MySQL 接口有效，分别与 password、database 和 connection_timeout 相同。后者的优先级更高。数据源名称语法或 dsn 不使用；如果指定了它，则会引发 NotSupportedError 异常。

客户端/服务器协议实现

Connector/Python 可以使用纯 Python 接口连接到 MySQL，也可以使用使用 MySQL C 客户端库的 C 扩展。 use_pure mysql.connector.connect() 连接参数决定使用哪个。Connector/Python 8 中的默认值从 True（使用纯 Python 实现）更改为 False。设置 use_pure 会更改所使用的实现。

use_pure 参数从 Connector/Python 2.1.1 开始可用。有关 C 扩展的更多信息，请参见 第 8 章，Connector/Python C 扩展。