如何使用 JDBC 和 PSQL 連線至虛擬倉庫執行個體 - Hologres

當 Hologres 執行個體擁有多個虛擬倉庫時，您可以在連線時指定目標倉庫，或在工作階段期間切換倉庫而無需重新連線。本文說明如何在 JDBC 和 psql 連線字串中指定虛擬倉庫，以及如何在連線後使用 SQL 切換倉庫。

使用 JDBC 連線

連線字串格式

不指定虛擬倉庫（使用您的預設虛擬倉庫）：

jdbc:postgresql:<Endpoint>:<Port>/<database_name>

指定虛擬倉庫：

jdbc:postgresql://<Endpoint>:<Port>/<database_name>@<warehouse_name>

參數說明

參數	是否必填	描述
`Endpoint`	是	Hologres 執行個體的 Endpoint。前往 Hologres 控制台，在左側導覽列中點擊執行個體列表，點擊目標執行個體，在網路資訊區域（位於執行個體詳情頁面）中找到 Endpoint。請選擇與您網路環境相符的 Endpoint，使用錯誤的 Endpoint 會導致連線失敗。
`Port`	是	Hologres 執行個體的連接埠。可在相同的網路資訊區域中找到。
`database_name`	是	Hologres 資料庫的名稱。執行個體建立後，系統會自動建立 postgres 資料庫。postgres 資料庫資源有限，如需用於業務負載，請建立專用資料庫。範例：`demo`。
`warehouse_name`	否	此連線要使用的虛擬倉庫。若省略，則連線使用您的預設虛擬倉庫。若要在連線後切換倉庫，請使用 `SET current_warehouse`。

範例

不指定虛擬倉庫——連線至 demo 資料庫，使用預設虛擬倉庫：

jdbc:postgresql://hgpostcn-cn-zz4xxxxxxxxxx-cn-shenzhen-vpc-st.hologres.aliyuncs.com:80/demo

指定虛擬倉庫——連線至 demo 資料庫，使用 warehouse_1：

jdbc:postgresql://hgpostcn-cn-zz4xxxxxxxxxx-cn-shenzhen-vpc-st.hologres.aliyuncs.com:80/demo@warehouse_1

虛擬倉庫路由優先順序

當連線字串未明確指定虛擬倉庫時，Hologres 按照以下優先順序為連線解析虛擬倉庫：

連線字串中指定的虛擬倉庫，如前述範例所示。
您的使用者預設虛擬倉庫（若您已透過呼叫 hg_set_user_default_warehouse 進行設定）。
執行個體預設虛擬倉庫 init_warehouse，僅在上述兩者均未設定時使用。

若要檢查目前連線實際使用的虛擬倉庫，請執行：

SELECT current_warehouse();

寫入請求 (DML) 的自動路由

Grand Unified Configuration (GUC) 參數 hg_experimental_enable_warehouse_dml_auto_routing 控制寫入請求 (DML) 在虛擬倉庫之間的路由方式。此參數預設為 on。若要確認目前的值，請執行 SHOW hg_experimental_enable_warehouse_dml_auto_routing;。當此參數為 on 時，寫入請求會自動路由至 leader 虛擬倉庫執行，因此即使您的連線使用的是非 leader 虛擬倉庫，寫入操作也能成功。

若將此參數設為 off，在非 leader 虛擬倉庫上發出的寫入請求將被拒絕。直接在 leader 虛擬倉庫上發出的寫入請求不受影響，仍可正常成功。

使用 psql 連線

連線字串格式

不指定虛擬倉庫（使用您的預設虛擬倉庫）：

PGUSER="<AccessKey_ID>" PGPASSWORD="<AccessKey_Secret>" psql -h <Endpoint> -p <Port> -d <database_name>

指定虛擬倉庫：

PGUSER="<AccessKey_ID>" PGPASSWORD="<AccessKey_Secret>" psql -h <Endpoint> -p <Port> -d <database_name>@<warehouse_name>

說明

-d 旗標接受 <database_name>@<warehouse_name> 作為單一值。@<warehouse_name> 部分不是獨立的旗標——它直接附加在資料庫名稱之後。

參數說明

參數	是否必填	描述
`AccessKey_ID`	是	阿里雲帳號：您的 AccessKey ID。可從AccessKey 管理取得。自訂帳號：您的使用者名稱，例如 `BASIC$abc`。
`AccessKey_Secret`	是	阿里雲帳號：您的 AccessKey Secret。自訂帳號：您的密碼。
`Endpoint`	是	Hologres 執行個體的 Endpoint。可在 Hologres 控制台的執行個體詳情頁面中找到。
`Port`	是	Hologres 執行個體的連接埠。可在相同的執行個體詳情頁面中找到。
`database_name`	是	Hologres 資料庫的名稱。執行個體建立後，系統會自動建立 postgres 資料庫。postgres 資料庫資源有限，如需用於業務負載，請建立專用資料庫。範例：`demo`。
`warehouse_name`	否	此連線要使用的虛擬倉庫。附加至 `database_name` 後方，格式為 `<database_name>@<warehouse_name>`。若省略，則連線使用您的預設虛擬倉庫。

範例

命令列——不指定虛擬倉庫：

PGUSER="xxx" PGPASSWORD="xxx" psql -h hgpostcn-cn-zz4xxxxxxxxxx-cn-shenzhen-vpc-st.hologres.aliyuncs.com -p 80 -d demo

命令列——指定虛擬倉庫：

PGUSER="xxx" PGPASSWORD="xxx" psql -h hgpostcn-cn-zz4xxxxxxxxxx-cn-shenzhen-vpc-st.hologres.aliyuncs.com -p 80 -d demo@warehouse_1

使用 SQL 切換虛擬倉庫

適用於 Hologres V4.0 及更高版本。

使用 SET current_warehouse 可為目前連線切換虛擬倉庫，無需重新連線。若要隨時檢查目前使用的倉庫，請執行 SHOW current_warehouse。

基本用法：

-- Switch to a different virtual warehouse
SET current_warehouse = <warehouse_name>;

-- Verify the active virtual warehouse
SHOW current_warehouse;

切換並還原——若您需要暫時使用其他倉庫，然後恢復原始倉庫：

-- Record the current warehouse
SHOW current_warehouse;

-- Switch to a different warehouse
SET current_warehouse = warehouse_2;

-- Verify the switch
SHOW current_warehouse;

-- Restore the original warehouse when done
SET current_warehouse = <original_warehouse_name>;

使用說明

切換倉庫會保留所有工作階段狀態，包括 Grand Unified Configuration (GUC) 變數和預處理陳述式。
此設定僅適用於工作階段層級。嘗試在資料庫或使用者層級設定時會傳回錯誤：This can only be set at session level.
目前使用者必須擁有目標虛擬倉庫的權限。若無所需權限，命令會傳回：Permission denied for warehouse "xxx".
不支援對具有作用中暫存資料表 (TEMP TABLE) 的連線進行切換。