MySQL :: MySQL 8.4 參考手冊 :: 6.2.5 使用類似 URI 的字串或鍵值對連線至伺服器

版本 8.4

9.0
8.0

8.0 日文

MySQL 8.4 參考手冊 / ... / 使用類似 URI 的字串或鍵值對連線至伺服器

6.2.5 使用類似 URI 的字串或鍵值對連線至伺服器

本節說明如何使用類似 URI 的連線字串或鍵值對來指定如何建立與 MySQL 伺服器的連線，例如 MySQL Shell 等用戶端。如需使用命令列選項建立連線的相關資訊，適用於例如 mysql 或 mysqldump 等用戶端，請參閱第 6.2.4 節「使用命令選項連線至 MySQL 伺服器」。如果您無法連線，如需其他資訊，請參閱第 8.2.22 節「疑難排解連線至 MySQL 的問題」。

注意

「類似 URI」一詞表示連線字串的語法類似但不完全等同於 RFC 3986 定義的 URI (統一資源識別碼) 語法。

下列 MySQL 用戶端支援使用類似 URI 的連線字串或鍵值對連線至 MySQL 伺服器

MySQL Shell
實作 X DevAPI 的 MySQL 連接器

本節記錄所有有效的類似 URI 字串和鍵值對連線參數，其中許多參數與使用命令列選項指定的參數相似。

使用類似 URI 的字串指定的參數使用類似 myuser@example.com:3306/main-schema 的語法。如需完整語法，請參閱使用類似 URI 的連線字串連線。
使用鍵值對指定的參數使用類似 {user:'myuser', host:'example.com', port:3306, schema:'main-schema'} 的語法。如需完整語法，請參閱使用鍵值對連線。

連線參數不區分大小寫。每個參數 (如果指定) 只能指定一次。如果某個參數指定多次，則會發生錯誤。

本節涵蓋下列主題

基本連線參數

以下討論說明在指定連線至 MySQL 時可用的參數。這些參數可以使用符合基本類似 URI 語法的字串 (請參閱使用類似 URI 的連線字串連線)，或以鍵值對的形式提供 (請參閱使用鍵值對連線)。

scheme：要使用的傳輸協定。針對 X Protocol 連線使用 mysqlx，針對傳統 MySQL 協定連線使用 mysql。如果未指定協定，伺服器會嘗試猜測協定。支援 DNS SRV 的連接器可以使用 mysqlx+srv 配置 (請參閱使用 DNS SRV 記錄連線)。
user：提供給驗證程序的 MySQL 使用者帳戶。
password：用於驗證程序的密碼。

警告

在連線規格中指定明確密碼是不安全的，不建議這樣做。稍後的討論會說明如何導致出現密碼的互動式提示。
host：伺服器執行個體正在執行的主機。該值可以是主機名稱、IPv4 位址或 IPv6 位址。如果未指定主機，則預設值為 localhost。
port：目標 MySQL 伺服器正在接聽連線的 TCP/IP 網路連接埠。如果未指定連接埠，則 X Protocol 連線的預設值為 33060，傳統 MySQL 協定連線的預設值為 3306。
socket：Unix socket 檔案的路徑或 Windows 具名管道的名稱。值為本機檔案路徑。在類似 URI 的字串中，它們必須經過編碼，使用百分比編碼或以括號括住路徑。括號消除了對字元進行百分比編碼的需要，例如 / 目錄分隔符號字元。例如，若要使用 Unix socket /tmp/mysql.sock 以 root@localhost 的身分連線，請使用百分比編碼指定路徑，如 root@localhost?socket=%2Ftmp%2Fmysql.sock，或使用括號，如 root@localhost?socket=(/tmp/mysql.sock)。
schema：連線的預設資料庫。如果未指定資料庫，則連線沒有預設資料庫。

在 Unix 系統上處理 localhost 的方式取決於傳輸協定的類型。使用傳統 MySQL 協定的連線處理 localhost 的方式與其他 MySQL 用戶端相同，這表示 localhost 被視為基於 socket 的連線。對於使用 X 協定的連線，localhost 的行為有所不同，它被視為代表迴路位址，例如 IPv4 位址 127.0.0.1。

額外連線參數

您可以指定連線的選項，可以透過附加 ?attribute=value 以 URI 類型的字串作為屬性，或作為鍵值對。以下選項可用：

ssl-mode：連線所需的安全性狀態。以下模式是允許的：
- DISABLED (停用)
- PREFERRED (偏好)
- REQUIRED (必要)
- VERIFY_CA (驗證 CA)
- VERIFY_IDENTITY (驗證身分)
重要

VERIFY_CA 和 VERIFY_IDENTITY 是比預設值 PREFERRED 更好的選擇，因為它們有助於防止中間人攻擊。

關於這些模式的資訊，請參閱--ssl-mode 選項的描述，位於加密連線的命令選項。
ssl-ca：X.509 憑證授權檔案（PEM 格式）的路徑。
ssl-capath：包含 X.509 憑證授權檔案（PEM 格式）的目錄路徑。
ssl-cert：X.509 憑證檔案（PEM 格式）的路徑。
ssl-cipher：用於使用 TLS 協定（直到 TLSv1.2）的連線的加密密碼。
ssl-crl：包含憑證撤銷清單（PEM 格式）的檔案路徑。
ssl-crlpath：包含憑證撤銷清單檔案（PEM 格式）的目錄路徑。
ssl-key：X.509 金鑰檔案（PEM 格式）的路徑。
tls-version：允許用於傳統 MySQL 協定加密連線的 TLS 協定。此選項僅由 MySQL Shell 支援。tls-version (單數) 的值是一個以逗號分隔的清單，例如 TLSv1.2,TLSv1.3。詳情請參閱第 8.3.2 節，「加密連線 TLS 協定和密碼」。此選項取決於 ssl-mode 選項未設定為 DISABLED。
tls-versions：允許用於加密 X 協定連線的 TLS 協定。tls-versions (複數) 的值是一個陣列，例如 [TLSv1.2,TLSv1.3]。詳情請參閱第 8.3.2 節，「加密連線 TLS 協定和密碼」。此選項取決於 ssl-mode 選項未設定為 DISABLED。
tls-ciphersuites：允許的 TLS 加密套件。tls-ciphersuites 的值是 IANA 加密套件名稱的清單，如TLS 加密套件中所列。詳情請參閱第 8.3.2 節，「加密連線 TLS 協定和密碼」。此選項取決於 ssl-mode 選項未設定為 DISABLED。
auth-method：用於連線的驗證方法。預設值為 AUTO，表示伺服器會嘗試猜測。以下方法是允許的：
- AUTO (自動)
- MYSQL41
- SHA256_MEMORY
- FROM_CAPABILITIES
- FALLBACK
- PLAIN (純文字)
對於 X 協定連線，任何設定的 auth-method 都會被覆寫為以下驗證方法順序：MYSQL41、SHA256_MEMORY、PLAIN。
get-server-public-key：向伺服器請求基於 RSA 金鑰對的密碼交換所需的公開金鑰。當以 SSL 模式 DISABLED 連線到使用傳統 MySQL 協定的 MySQL 8+ 伺服器時使用。在這種情況下，您必須指定協定。例如：
```
mysql://user@localhost:3306?get-server-public-key=true
```
此選項適用於使用 caching_sha2_password 驗證外掛程式進行驗證的用戶端。對於該外掛程式，除非請求，否則伺服器不會傳送公開金鑰。對於不使用該外掛程式進行驗證的帳戶，將會忽略此選項。如果未使用基於 RSA 的密碼交換（當用戶端使用安全連線連線到伺服器時會發生這種情況），也會忽略此選項。
如果提供 server-public-key-path=file_name 並且指定了一個有效的公開金鑰檔案，它將優先於 get-server-public-key。
有關 caching_sha2_password 外掛程式的資訊，請參閱第 8.4.1.2 節，「快取 SHA-2 可插拔驗證」。
server-public-key-path：PEM 格式檔案的路徑名稱，其中包含伺服器進行基於 RSA 金鑰對的密碼交換所需的公開金鑰的用戶端副本。當以 SSL 模式 DISABLED 連線到使用傳統 MySQL 協定的 MySQL 8+ 伺服器時使用。
此選項適用於使用 sha256_password (已棄用) 或 caching_sha2_password 驗證外掛程式進行驗證的用戶端。對於不使用這些外掛程式之一進行驗證的帳戶，將會忽略此選項。如果未使用基於 RSA 的密碼交換（當用戶端使用安全連線連線到伺服器時會發生這種情況），也會忽略此選項。
如果提供 server-public-key-path=file_name 並且指定了一個有效的公開金鑰檔案，它將優先於 get-server-public-key。
有關 sha256_password (已棄用) 和 caching_sha2_password 外掛程式的資訊，請參閱第 8.4.1.3 節，「SHA-256 可插拔驗證」和第 8.4.1.2 節，「快取 SHA-2 可插拔驗證」。
ssh：用於連線到 SSH 伺服器，以使用 SSH 通道存取 MySQL 伺服器執行個體的 URI。URI 格式為 [user@]host[:port]。使用 uri 選項來指定目標 MySQL 伺服器執行個體的 URI。有關 MySQL Shell 的 SSH 通道連線資訊，請參閱使用 SSH 通道。
uri：要透過 ssh 選項指定的伺服器上的 SSH 通道存取的 MySQL 伺服器執行個體的 URI。URI 格式為 [scheme://][user@]host[:port]。請勿使用基本連線參數 (scheme、user、host、port) 來指定 SSH 通道的 MySQL 伺服器連線，僅使用 uri 選項。
ssh-password：用於連線到 SSH 伺服器的密碼。

警告

在連線規格中明確指定密碼是不安全的，不建議使用。當需要密碼時，MySQL Shell 會以互動方式提示輸入密碼。
ssh-config-file：用於連線到 SSH 伺服器的 SSH 設定檔。如果未指定此選項，您可以使用 MySQL Shell 設定選項 ssh.configFile 將自訂檔案設定為預設值。如果 ssh.configFile 尚未設定，則預設值為標準 SSH 設定檔 ~/.ssh/config。
ssh-identity-file：用於連線到 SSH 伺服器的身分檔案。如果未指定此選項，則預設值為 SSH 代理程式 (如果使用) 或 SSH 設定檔中設定的任何身分檔案，或是 SSH 設定資料夾中的標準私密金鑰檔案 (~/.ssh/id_rsa)。
ssh-identity-pass：由 ssh-identity-file 選項指定的身份檔案的密碼。

警告

在連線規格中明確指定密碼是不安全的，不建議使用。當需要密碼時，MySQL Shell 會以互動方式提示輸入密碼。
connect-timeout：用於設定用戶端（例如 MySQL Shell）在停止嘗試連線到沒有回應的 MySQL 伺服器之前等待的秒數的整數值。
compression：此選項要求或停用連線壓縮。
此選項可用的值為：required，它要求壓縮，如果伺服器不支援壓縮則會失敗；preferred，它要求壓縮，並會回退到未壓縮的連線；以及 disabled，它要求未壓縮的連線，如果伺服器不允許則會失敗。preferred 是 X 協定連線的預設值，而 disabled 是傳統 MySQL 協定連線的預設值。有關 X 外掛程式連線壓縮控制的資訊，請參閱第 22.5.5 節，「使用 X 外掛程式的連線壓縮」。

注意

不同的 MySQL 用戶端以不同的方式實作其對連線壓縮的支援。有關詳細資訊，請參閱用戶端的文件。
compression-algorithms 和 compression-level：這些選項在 MySQL Shell 中可用，以更精細地控制連線壓縮。您可以指定它們來選擇用於連線的壓縮演算法，以及該演算法使用的數值壓縮等級。您也可以使用 compression-algorithms 來代替 compression，以要求連線壓縮。有關 MySQL Shell 的連線壓縮控制資訊，請參閱使用壓縮連線。
connection-attributes：控制應用程式在連線時傳遞給伺服器的鍵值對。有關連線屬性的通用資訊，請參閱第 29.12.9 節，「效能架構連線屬性表格」。用戶端通常會定義一組預設屬性，這些屬性可以停用或啟用。例如：
```
mysqlx://user@host?connection-attributes
mysqlx://user@host?connection-attributes=true
mysqlx://user@host?connection-attributes=false
```
預設行為是傳送預設的屬性集。應用程式可以指定要傳遞的屬性，以補充預設屬性。您可以在連線字串中，以 connection-attributes 參數指定額外的連線屬性。connection-attributes 參數的值必須是空的（與指定 true 相同）、Boolean 值（true 或 false，以啟用或停用預設屬性集），或是以逗號分隔的零個或多個 key=value 指定符號列表（以補充預設屬性集傳送）。在列表中，遺失的鍵值會評估為空字串。更多範例請參考下方。
```
mysqlx://user@host?connection-attributes=[attr1=val1,attr2,attr3=]
mysqlx://user@host?connection-attributes=[]
```
應用程式定義的屬性名稱不能以 _ 開頭，因為此類名稱保留給內部屬性使用。

使用 URI 樣式的連線字串連線

您可以使用 URI 樣式的字串指定與 MySQL 伺服器的連線。此類字串可以與 MySQL Shell 搭配使用，例如透過 --uri 命令選項、MySQL Shell \connect 命令，以及實作 X DevAPI 的 MySQL 連接器。

注意

「類似 URI」一詞表示連線字串的語法類似但不完全等同於 RFC 3986 定義的 URI (統一資源識別碼) 語法。

URI 樣式的連線字串具有下列語法

[scheme://][user[:[password]]@]host[:port][/schema][?attribute1=value1&attribute2=value2...

重要

URI 樣式字串元素中的保留字元必須使用百分比編碼。例如，如果您指定包含 @ 字元的字串，則該字元必須以 %40 取代。如果您在 IPv6 位址中包含區域 ID，則用作分隔符號的 % 字元必須以 %25 取代。

您可以在 URI 樣式的連線字串中使用的參數，請參閱基本連線參數。

MySQL Shell 的 shell.parseUri() 和 shell.unparseUri() 方法可用於解構和組裝 URI 樣式的連線字串。給定 URI 樣式的連線字串，shell.parseUri() 會傳回一個字典，其中包含在字串中找到的每個元素。shell.unparseUri() 會將 URI 組件和連線選項的字典轉換為有效的 URI 樣式連線字串，以連線到 MySQL，此字串可用於 MySQL Shell 或實作 X DevAPI 的 MySQL 連接器。

如果 URI 樣式的字串中未指定密碼（建議這樣做），互動式用戶端會提示輸入密碼。以下範例示範如何使用使用者名稱 user_name 指定 URI 樣式的字串。在每種情況下，系統都會提示輸入密碼。

X Protocol 連線到在本機伺服器執行個體上，於 33065 連接埠接聽的連線。
```
mysqlx://user_name@localhost:33065
```
傳統的 MySQL 通訊協定連線到在本機伺服器執行個體上，於 3333 連接埠接聽的連線。
```
mysql://user_name@localhost:3333
```

使用主機名稱、IPv4 位址和 IPv6 位址，連線到遠端伺服器執行個體的 X Protocol 連線。

mysqlx://user_name@server.example.com/
mysqlx://user_name@198.51.100.14:123
mysqlx://user_name@[2001:db8:85a3:8d3:1319:8a2e:370:7348]

使用 Socket 的 X Protocol 連線，路徑可使用百分比編碼或括號提供。

mysqlx://user_name@/path%2Fto%2Fsocket.sock
mysqlx://user_name@(/path/to/socket.sock)

可以指定選用路徑，表示資料庫。

# use 'world' as the default database
mysqlx://user_name@198.51.100.1/world

# use 'world_x' as the default database, encoding _ as %5F
mysqlx://user_name@198.51.100.2:33060/world%5Fx

可以指定選用查詢，其中包含每個值都以 key=value 配對或單一 key 的形式提供。若要指定多個值，請以 , 字元分隔。可以混用 key=value 和 key 值。值可以是列表類型，列表值依出現順序排列。字串必須進行百分比編碼或以括號括住。以下是等效的。
```
ssluser@127.0.0.1?ssl-ca=%2Froot%2Fclientcert%2Fca-cert.pem\
&ssl-cert=%2Froot%2Fclientcert%2Fclient-cert.pem\
&ssl-key=%2Froot%2Fclientcert%2Fclient-key

ssluser@127.0.0.1?ssl-ca=(/root/clientcert/ca-cert.pem)\
&ssl-cert=(/root/clientcert/client-cert.pem)\
&ssl-key=(/root/clientcert/client-key)
```

指定用於加密連線的 TLS 版本和密碼套件

mysql://user_name@198.51.100.2:3306/world%5Fx?\
tls-versions=[TLSv1.2,TLSv1.3]&tls-ciphersuites=[TLS_DHE_PSK_WITH_AES_128_\
GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256]

先前的範例假設連線需要密碼。對於互動式用戶端，系統會在登入提示時要求輸入指定使用者的密碼。如果使用者帳戶沒有密碼（這是不安全的，不建議這樣做），或者如果使用 Socket 對等認證（例如，使用 Unix Socket 連線），您必須在連線字串中明確指定不提供密碼，而且不需要密碼提示。若要執行此操作，請在字串中的 user_name 後面放置 :，但不要在其後指定密碼。例如

mysqlx://user_name:@localhost

使用索引鍵值配對連線

在 MySQL Shell 和某些實作 X DevAPI 的 MySQL 連接器中，您可以使用索引鍵值配對指定與 MySQL 伺服器的連線，這些索引鍵值配對在實作中以語言自然的結構提供。例如，您可以使用索引鍵值配對，以 JavaScript 中的 JSON 物件或 Python 中的字典形式提供連線參數。無論索引鍵值配對的提供方式為何，概念都相同：本節中說明的索引鍵可以指派用來指定連線的值。您可以使用索引鍵值配對，在 MySQL Shell 的 shell.connect() 方法或 InnoDB Cluster 的 dba.createCluster() 方法中，以及一些實作 X DevAPI 的 MySQL 連接器中指定連線。

一般來說，索引鍵值配對以 { 和 } 字元括住，而 , 字元用作索引鍵值配對之間的分隔符號。: 字元用於索引鍵和值之間，而字串必須定界（例如，使用 ' 字元）。與 URI 樣式的連線字串不同，不必對字串進行百分比編碼。

以索引鍵值配對指定的連線具有下列格式

{ key: value, key: value, ...}

您可以用作連線索引鍵的參數，請參閱基本連線參數。

如果索引鍵值配對中未指定密碼（建議這樣做），互動式用戶端會提示輸入密碼。以下範例示範如何使用索引鍵值配對和使用者名稱 'user_name' 指定連線。在每種情況下，系統都會提示輸入密碼。

X Protocol 連線到在本機伺服器執行個體上，於 33065 連接埠接聽的連線。
```
{user:'user_name', host:'localhost', port:33065}
```
傳統的 MySQL 通訊協定連線到在本機伺服器執行個體上，於 3333 連接埠接聽的連線。
```
{user:'user_name', host:'localhost', port:3333}
```

使用主機名稱、IPv4 位址和 IPv6 位址，連線到遠端伺服器執行個體的 X Protocol 連線。

{user:'user_name', host:'server.example.com'}
{user:'user_name', host:198.51.100.14:123}
{user:'user_name', host:[2001:db8:85a3:8d3:1319:8a2e:370:7348]}

使用 Socket 的 X Protocol 連線。

{user:'user_name', socket:'/path/to/socket/file'}

可以指定選用綱要，表示資料庫。

{user:'user_name', host:'localhost', schema:'world'}

先前的範例假設連線需要密碼。對於互動式用戶端，系統會在登入提示時要求輸入指定使用者的密碼。如果使用者帳戶沒有密碼（這是不安全的，不建議這樣做），或者如果使用 Socket 對等認證（例如，使用 Unix Socket 連線），您必須明確指定不提供密碼，且不需要密碼提示。若要執行此操作，請在使用 password 索引鍵後提供使用 '' 的空字串。例如

{user:'user_name', password:'', host:'localhost'}