可以使用 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 嘗試使用 TCP/IP 連接到本機執行的 MySQL 伺服器。 host 引數預設為 IP 位址 127.0.0.1，而 port 預設為 3306。透過設定 unix_socket 支援 Unix socket。Windows 平台上的具名管道則不支援。

Connector/Python 支援 MySQL 8.0 起可用的驗證外掛程式，包括建議使用的 caching_sha2_password 驗證外掛程式。

已棄用的 mysql_native_password 外掛程式受到支援，但從 MySQL Server 8.4.0 起預設為停用，並從 MySQL Server 9.0.0 起移除。

connect() 方法支援 auth_plugin 引數，可用於強制使用特定的驗證外掛程式。

Connector/Python 支援用於無密碼驗證的 Kerberos 驗證協定。從 Connector/Python 8.0.26 起支援 Linux 用戶端，而 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": "myuser@example.com",
    "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])

從 v8.0.28 起，Connector/Python 透過使用 password1 (別名為 password)、password2 和 password3 連線選項來支援多重要素驗證 (MFA)。

從 Connector/Python 8.2.0 起，Connector/Python 支援 WebAuthn 可插拔驗證，此功能在 MySQL Enterprise Edition 中受支援。您也可以選擇使用 Connector/Python 的 webauthn_callback 連線選項來通知使用者他們需要觸碰硬體裝置。此功能存在於 C 實作 (使用 libmysqlclient) 中，但純 Python 實作需要 FIDO2 相依性，該相依性未與 MySQL 連接器一起提供，並假設已存在於您的環境中。可以使用以下方式單獨安裝

$> pip install fido2

先前，使用 C 擴充功能實作中提供的 fido_callback 選項，支援目前已移除 (從 8.4.0 版起) 的 authentication_fido MySQL Server 外掛程式。

字元編碼

預設情況下，來自 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 值應由轉換為 PST 時區的 MySQL 傳回，則此功能會很有用。

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 時 (亦即，當它是根據 OpenSSL 程式庫編譯時)，可以使用 SSL 連線。當您提供 ssl_ca、ssl_key 和 ssl_cert 選項時，連線會切換到 SSL，且 client_flags 選項會自動包含 ClientFlag.SSL 值。您可以將此功能與設定為 True 的 compressed 選項搭配使用。

從 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 擴充功能。