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

版本 9.0

8.4 目前
8.0

8.0 日文

MySQL 9.0 參考手冊 / ... / 使用類似 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
- VERIFY_IDENTITY
重要

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

有關這些模式的資訊，請參閱--ssl-mode 選項說明，位於加密連線的命令選項。
ssl-ca：PEM 格式的 X.509 憑證授權檔案的路徑。
ssl-capath：包含 PEM 格式的 X.509 憑證授權檔案的目錄路徑。
ssl-cert：PEM 格式的 X.509 憑證檔案的路徑。
ssl-cipher：用於 TLS 協定（直到 TLSv1.2）的連線的加密密碼。
ssl-crl：包含 PEM 格式的憑證撤銷清單的檔案路徑。
ssl-crlpath：包含 PEM 格式的憑證撤銷清單檔案的目錄路徑。
ssl-key：PEM 格式的 X.509 金鑰檔案的路徑。
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.1 節，「快取 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.2 節，「SHA-256 可插拔驗證」，以及第 8.4.1.1 節，「快取 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 元件和連線選項的字典轉換為可連線至 MySQL 的有效類似 URI 的連線字串，該字串可用於 MySQL Shell 或實作 X DevAPI 的 MySQL 連接器。

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

與在埠 33065 監聽的本機伺服器執行個體的 X Protocol 連線。
```
mysqlx://user_name@localhost:33065
```
與在埠 3333 監聽的本機伺服器執行個體的傳統 MySQL 通訊協定連線。
```
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' 使用鍵值對指定連線。在每種情況下，系統都會提示輸入密碼。

與在埠 33065 監聽的本機伺服器執行個體的 X Protocol 連線。
```
{user:'user_name', host:'localhost', port:33065}
```
與在埠 3333 監聽的本機伺服器執行個體的傳統 MySQL 通訊協定連線。
```
{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'}

上一步首頁上層下一步