MySQL :: MySQL Connector/J 開發人員指南 :: 6.2 連線 URL 語法

MySQL Connector/J 開發人員指南 / Connector/J 參考 / 連線 URL 語法

6.2 連線 URL 語法

本節說明用於連線至 MySQL 的 URL 語法。

這是連線 URL 的一般格式

protocol//[hosts][/database][?properties]

URL 由下列部分組成

重要

任何在連線 URL 的任何部分中出現的 URL 保留字元 (例如，/、:、@、(、)、[、]、&、#、=、? 和空格) 都必須經過百分比編碼。

`protocol`

以下是連線的可能協定

jdbc:mysql: 用於一般和基本 JDBC 容錯移轉連線。
jdbc:mysql:loadbalance: 用於負載平衡 JDBC 連線。如需詳細資訊，請參閱第 9.3 節，「設定 Connector/J 的負載平衡」。
jdbc:mysql:replication: 用於 JDBC 複寫連線。如需詳細資訊，請參閱第 9.4 節，「設定 Connector/J 的來源/複本複寫」。
mysqlx: 用於 X DevAPI 連線。
jdbc:mysql+srv: 用於使用 DNS SRV 記錄的一般和基本容錯移轉 JDBC 連線。
jdbc:mysql+srv:loadbalance: 用於使用 DNS SRV 記錄的負載平衡 JDBC 連線。
jdbc:mysql+srv:replication: 用於使用 DNS SRV 記錄的複寫 JDBC 連線。
mysqlx+srv: 用於使用 DNS SRV 記錄的 X DevAPI 連線。

`hosts`

根據情況，host 部分可能僅包含主機名稱，或者它可以是包含各種元素 (例如多個主機名稱、連接埠號碼、主機特定的屬性和使用者認證) 的複雜結構。

單一主機
- 未新增主機特定屬性的單一主機連線
  - hosts 部分以 host:port 的格式撰寫。以下是一個簡單單一主機連線 URL 的範例
    
    jdbc:mysql://host1:33060/sakila
  - host 可以是 IPv4 或 IPv6 主機名稱字串，在後者的情況下，必須將其放在方括號內，例如「[1000:2000::abcd]。」如果未指定host，則使用預設值 localhost。
  - port 是標準連接埠號碼，也就是介於 1 到 65535 之間的整數。一般 MySQL 連線的預設連接埠號碼是 3306，而使用 X Protocol 連線的預設連接埠號碼是 33060。如果未指定port，則會使用對應的預設值。
- 新增主機特定屬性的單一主機連線
  - 在這種情況下，主機定義為一系列 key=value 配對。索引鍵用於識別主機、連接埠，以及任何主機特定的屬性。有兩種替代格式可用於指定索引鍵
    
    「address-equals」形式
    
    address=(host=host_or_ip)(port=port)(key1=value1)(key2=value2)...(keyN=valueN)
    
    以下是使用「address-equals」形式的 URL 範例
    
    jdbc:mysql://address=(host=myhost)(port=1111)(key1=value1)/db
    
    「key-value」形式
    
    (host=host,port=port,key1=value1,key2=value2,...,keyN=valueN)
    
    以下是使用「key-value」形式的 URL 範例
    
    jdbc:mysql://(host=myhost,port=1111,key1=value1)/db
  - 主機和連接埠由索引鍵 host 和 port 識別。沒有主機特定屬性的單一主機中host 和 port 的格式和預設值說明也適用於此處。
  - 可以新增的其他索引鍵包括 user、password、protocol 等。它們會覆寫在 URL 的properties 部分中設定的全域值。將覆寫限制為使用者、密碼、網路逾時，以及陳述式和中繼資料快取大小；其他每個主機覆寫的效果未定義。
  - 不同的協定可能需要不同的索引鍵。例如，mysqlx: 配置使用兩個特殊索引鍵，address 和 priority。address 是 host:port 配對，而 priority 則是整數。例如
    
    mysqlx://(address=host:1111,priority=1,key1=value1)/db
  - key 區分大小寫。僅大小寫不同的兩個索引鍵會被視為衝突，而且無法保證將使用哪一個。

多個主機

有兩種格式可指定多個主機

將主機列在以逗號分隔的清單中

host1,host2,...,hostN

每個主機都可以使用單一主機中描述的三種方式中的任何一種來指定。以下是一些範例

jdbc:mysql://myhost1:1111,myhost2:2222/db
jdbc:mysql://address=(host=myhost1)(port=1111)(key1=value1),address=(host=myhost2)(port=2222)(key2=value2)/db
jdbc:mysql://(host=myhost1,port=1111,key1=value1),(host=myhost2,port=2222,key2=value2)/db
jdbc:mysql://myhost1:1111,(host=myhost2,port=2222,key2=value2)/db
mysqlx://(address=host1:1111,priority=1,key1=value1),(address=host2:2222,priority=2,key2=value2)/db

將主機列在以逗號分隔的清單中，然後將清單括在方括號內
```
[host1,host2,...,hostN]
```
這稱為主機子清單形式，可讓清單中的所有主機共用使用者認證，如同它們是單一主機。清單中的每個主機都可以使用單一主機中描述的三種方式中的任何一種來指定。以下是一些範例
```
jdbc:mysql://sandy:secret@[myhost1:1111,myhost2:2222]/db
jdbc:mysql://sandy:secret@[address=(host=myhost1)(port=1111)(key1=value1),address=(host=myhost2)(port=2222)(key2=value2)]/db
jdbc:mysql://sandy:secret@[myhost1:1111,address=(host=myhost2)(port=2222)(key2=value2)]/db
```
雖然無法以遞迴方式寫入主機子清單，但主機清單可能會包含主機子清單作為其成員主機。

使用者憑證

使用者憑證可以在連線 URL 之外設定，例如，當從 java.sql.DriverManager 取得連線時作為引數（詳情請參閱第 6.3 節， “組態屬性”）。當使用連線 URL 設定時，有幾種方式可以指定它們
- 在單一主機、主機子列表（請參閱多個主機）或主機列表中的任何主機的前面加上使用者憑證，並使用 @ 符號
```
 user:password@host_or_host_sublist
```
  例如
```
mysqlx://sandy:secret@[(address=host1:1111,priority=1,key1=value1),(address=host2:2222,priority=2,key2=value2))]/db
```
- 使用鍵 user 和 password 來指定每個主機的憑證
```
(user=sandy)(password=mypass)
```
  例如
```
jdbc:mysql://[(host=myhost1,port=1111,user=sandy,password=secret),(host=myhost2,port=2222,user=finn,password=secret)]/db
jdbc:mysql://address=(host=myhost1)(port=1111)(user=sandy)(password=secret),address=(host=myhost2)(port=2222)(user=finn)(password=secret)/db
```
在這兩種形式中，當指定多個使用者憑證時，左邊的優先權較高—也就是說，在連線字串中從左到右，找到的第一個適用於主機的憑證會被使用。

在主機子列表內部，沒有主機可以使用 @ 格式的使用者憑證，但是個別的主機可以使用鍵格式指定使用者憑證。

`database`

預設要開啟的資料庫或目錄。如果未指定資料庫，則會建立不含預設資料庫的連線。在這種情況下，可以在 Connection 執行個體上呼叫 setCatalog() 方法，或是在您的 SQL 陳述式中使用資料庫名稱指定表格名稱（也就是 SELECT dbname.tablename.colname FROM dbname.tablename...）。通常，只有在建立處理多個資料庫的工具（例如 GUI 資料庫管理員）時，才會有用處。

注意

在 JDBC 應用程式中，請一律使用 Connection.setCatalog() 方法來指定所需的資料庫，而不是使用 USE database 陳述式。

`properties`

一連串套用至所有主機的全域屬性，前面加上 ?，並以 key=value 鍵值對的形式寫入，並以符號 “&” 分隔。以下是一些範例

jdbc:mysql://(host=myhost1,port=1111),(host=myhost2,port=2222)/db?key1=value1&key2=value2&key3=value3

以下適用於鍵值對

key 和 value 只是字串。適當的類型轉換和驗證會在 Connector/J 內部執行。
key 區分大小寫。只有大小寫不同的兩個鍵會被視為衝突，而且不確定會使用哪一個。
如具有主機特定屬性的單一主機和多個主機以上所述，使用鍵值對指定的任何主機特定值，都會覆寫這裡設定的全域值。

請參閱第 6.3 節，「組態屬性」，以取得有關組態屬性的詳細資訊。