開發規范
如果用戶在APP的開發中，使用了連接池機制，那么需要遵循如下規范，否則，連接池里面的連接就是有狀態的，會對用戶后續使用連接池進行操作的正確性帶來影響。
- 如果在連接中設置了GUC參數，那么在將連接歸還連接池之前，必須使用“SET SESSION AUTHORIZATION DEFAULT;RESET ALL;”將連接的狀態清空。
- 如果使用了臨時表，那么在將連接歸還連接池之前，必須將臨時表刪除。
下載JDBC或ODBC驅動
JDBC或ODBC驅動程序用于連接DWS 集群，用戶可以在管理控制臺下載DWS 提供的JDBC或ODBC驅動程序，也可以使用開源的JDBC或ODBC驅動程序。
支持的開源JDBC或ODBC驅動程序
DWS 也支持開源的JDBC驅動程序：PostgreSQL JDBC驅動程序9.3-1103或更高版本。
DWS 也支持開源的ODBC驅動程序：PostgreSQL ODBC 09.01.0200或更高版本。
下載JDBC或ODBC驅動程序
- 登錄DWS 管理控制臺。
- 在左側導航欄中，單擊“連接管理”。
- 在“下載驅動程序”區域，選擇一個驅動下載。
JDBC驅動
選擇“DWS JDBC Driver”，然后單擊“下載”可以下載與現有集群版本匹配的JDBC驅動。驅動包名為“dws_8.1.x_jdbc_driver.zip”，解壓后有兩個JDBC的驅動jar包，分別為“gsjdbc4.jar”和“gsjdbc200.jar”。
如果同時擁有不同版本的集群，單擊“下載”時會下載與集群最低版本相對應的JDBC驅動。如果當前沒有集群，單擊“下載”時將下載到低版本的JDBC驅動。DWS 集群可向下兼容低版本的JDBC驅動。
單擊“歷史版本”可根據集群版本下載相應版本的JDBC驅動，建議按集群版本進行下載。
JDBC驅動包支持在所有平臺所有版本中使用，且依賴JDK 1.6及以上版本。
ODBC驅動
選擇相應的版本，然后單擊“下載”可以下載與集群版本匹配的ODBC驅動。如果同時擁有不同版本的集群，單擊“下載”時會下載與集群最低版本相對應的ODBC驅動。如果當前沒有集群，單擊“下載”時將下載到低版本的ODBC驅動。DWS 集群可向下兼容低版本的ODBC驅動。
單擊“歷史版本”可根據操作系統和集群版本下載相應版本的ODBC驅動，建議按集群版本進行下載。
ODBC驅動支持在以下系統中使用：
- “Microsoft Windows”驅動支持在以下系統中使用：
Windows 7及以上。
Windows Server 2008及以上。
- Euler Kunpeng_64”驅動支持在以下系統中使用：
EulerOS 2.8。
- “Redhat_Kunpeng_64”驅動支持在以下系統中使用：
CentOS 7.5,7.6。
NeoKylin 7.6。
- ”Redhat x86_64”驅動支持在以下系統中使用：
RHEL 6.4~7.6。
CentOS 6.4~7.4。
EulerOS 2.3。
- ”SUSE x86_64”驅動支持在以下系統中使用：
SLES 11.1~11.4。
SLES 12.0~12.3。
說明Windows驅動只支持32位版本，可以在32或64位操作系統使用，但是應用程序必須為32位。
使用JDBC連接數據庫
DWS 支持在Linux或Windows環境下使用JDBC應用程序連接數據庫。應用程序可以在云平臺環境的彈性云主機中，或者互聯網環境連接數據庫。
用戶通過JDBC連接DWS 集群時，可以選擇是否采用SSL認證方式。SSL認證用于加密客戶端和服務器之間的通訊數據，為敏感數據在Internet上的傳輸提供了一種安全保障手段。DWS 管理控制臺提供了自簽的證書供用戶下載。使用該證書，用戶需要配置客戶端程序，使證書可用，此過程依賴于openssl工具以及java自帶的keytool工具。
說明SSL模式安全性高于普通模式，建議在使用JDBC連接DWS 集群時采用SSL模式。
JDBC接口的使用方法，請自行查閱官方文檔。
前提條件
- 已安裝JDK 1.6或以上版本，并配置環境變量。
- 已下載JDBC驅動，請參見上方：下載JDBC或ODBC驅動。
DWS 也支持開源的JDBC驅動程序：PostgreSQL JDBC驅動程序9.3-1103或更高版本。
- 已下載SSL證書文件，請參見使用SSL進行安全的TCP/IP連接-“在gsql客戶端配置SSL認證相關的數字證書參數”章節中的“下載SSL證書”。
使用JDBC連接數據庫
在Linux和Windows環境下操作方法相同，以下步驟以Windows環境為例。
- 是否采用SSL方式連接DWS 集群。
是，參見使用SSL進行安全的TCP/IP連接-設置SSL連接章節中的開啟SSL連接，默認為開啟。執行步驟2。
否，參見使用SSL進行安全的TCP/IP連接-設置SSL連接章節中的關閉SSL連接，執行步驟4。
- （可選）如果使用Linux環境，使用WinScp工具將SSL證書上傳到Linux環境上。
- 配置證書以使用SSL加密連接。
a.下載windows版本的OpenSSL工具。當前不支持OpenSSL 3.0.0，請選擇下載“Win64 OpenSSL v1.1.1L Light”版本。
b.雙擊安裝包“Win64OpenSSL_Light-1_1_1L.exe”安裝到C盤默認路徑即可，選擇復制DLLs文件到OpenSSL目錄下，如下圖，剩余步驟默認單擊下一步直到安裝成功。
c.安裝環境變量。單擊本地PC左下角“開始”，右擊“此電腦”，選擇“更多 > 屬性 > 高級系統設置”，切換到“高級”，單擊“環境變量”。
d.在下方“系統變量”，雙擊“Path”變量，單擊“新建”，在最后一行增加Openssl的bin路徑，例如“C:\Program Files\OpenSSL-Win64\bin”，單擊“確定”，再次單擊“確定”，配置變量成功。
e.解壓壓縮包得到證書文件。假設解壓路徑為“C:\”。
證書文件建議保存在英文路徑，配置證書時需要根據實際情況指定路徑，否則可能提示文件不存在。
f.打開“命令提示符”程序，切換到“C:\dws_ssl_cert\sslcert”路徑下，執行以下兩條命令，轉化根證書并導入到trustStore中。
openssl x509 -in cacert.pem -out cacert.crt.der -outform der
keytool -keystore mytruststore -alias cacert -import -file cacert.crt.der
?“cacert.pem”為解壓后獲取的根證書。
?“cacert.crt.der”為生成的中間文件。根據實際情況，可以填寫保存到其他路徑，也可以自定義文件名稱。
?“mytruststore”為生成的可信庫名稱，“cacert”為別名用戶，二者可以根據需要進行修改。
請用戶根據提示信息輸入自定義的可信庫密碼并確認密碼，然后輸入“y”確認信任證書。
g.執行以下命令轉化客戶端私鑰。
openssl pkcs12 -export -out client.pkcs12 -in client.crt -inkey client.key
需要輸入客戶端私鑰的密碼“Gauss@MppDB”，然后輸入并確認用戶自定義的私鑰密碼。
h.執行以下命令，將私鑰導入到keyStore中。
keytool -importkeystore -deststorepass Gauss@MppDB -destkeystore client.jks -
srckeystore client.pkcs12 -srcstorepass password -srcstoretype PKCS12 -alias 1
說明
命令中“ *password* ”為示例自定義密碼，具體請根據用戶實際輸入密碼為準。
回顯如下類似信息且沒有報錯，則表示導入成功。此時“C:\dws_ssl_cert\sslcert”下會生成目標密鑰文件：client.jks。
- 下載包名為dws_8.1.x_jdbc_driver.zip的驅動包，解壓后有兩個JDBC的驅動jar包“gsjdbc4.jar”和“gsjdbc200.jar”，用戶可根據需求選擇。
- 在應用程序的工程中，設置引用Jar包。
以Eclipse工程為例，先將jar包存放在工程目錄下，例如將jar包放在工程目錄的lib目錄下，然后在Eclipse工程中，右鍵單擊lib目錄下的該jar包，再選擇菜單“Build Path”，即可引用此jar包。
詳見下圖：引用jar包
- 加載驅動。
支持以下兩種方法加載：
- 在代碼中隱含裝載：Class.forName("org.postgresql.Driver");
- 在JVM啟動時參數傳遞：java -Djdbc.drivers=org.postgresql.Driver jdbctest
說明DWS 下載的JDBC驅動包中提供gsjdbc.jar。
?gsjdbc4.jar：與PostgreSQL保持兼容，其中類名、類結構與PostgreSQL驅動完全一致，曾經運行于PostgreSQL的應用程序可以直接移植到當前系統中使用。
- 調用JDBC的數據庫連接方法DriverManager.getConnection()連接DWS 數據庫。
JDBC接口不提供重試連接的能力，您需要在業務代碼中實現重試處理。
DriverManager.getConnection()方法支持以下重載：
- DriverManager.getConnection(String url);
- DriverManager.getConnection(String url, Properties info);
- DriverManager.getConnection(String url, String user, String password);
數據庫連接參數
| 參數 | 描述 |
|---|---|
| url | 數據庫連接描述符，可以在管理控制臺查看，具體步驟請參見獲取集群連接地址。 url的格式如下： jdbc:postgresql:database jdbc:postgresql://host/database jdbc:postgresql://host:port/database jdbc:postgresql://host:port[,host:port][...]/database 說明 使用gsjdbc200.jar時，將“jdbc:postgresql”修改為“jdbc:gaussdb” database為要連接的數據庫名稱。 host為數據庫服務器名稱或IP地址。 DWS管理控制臺上集群的連接IP，根據網絡環境判斷，如果連接DWS的機器跟DWS集群在同一個網絡下，則選擇內網IP，不在同一個網絡下，則選擇公網IP。 port為數據庫服務器端口。缺省情況下，會嘗試連接到localhost的8000端口的database。 支持多ip端口配置形式，jdbc自動實現了負載均衡，多ip端口配置形式是采取隨機訪問+failover的方式，這個過程系統會自動忽略不可達IP。 以","隔開，例如jdbc:postgresql://10.10.0.13:8000,10.10.0.14:8000/database 使用JDBC連接集群時集群鏈接地址只支持指定jdbc連接參數，不支持增加變量參數。 |
| info | 數據庫連接屬性。常用的屬性如下： user：String類型。表示創建連接的數據庫用戶。 password：String類型。表示數據庫用戶的密碼。 ssl：Boolean類型。表示是否使用SSL連接。 loggerLevel：string類型。為LogStream或LogWriter設置記錄進DriverManager當前值的日志信息量。目前支持"OFF"、"DEBUG"和"TRACE"。 值為"DEBUG"時，表示只打印DEBUG級別以上的日志，將記錄非常少的信息。值等于TRACE時，表示打印DEBUG和TRACE級別的日志，將產生詳細的日志信息。默認值為OFF，表示不打印日志。 prepareThreshold：integer類型。用于確定在轉換為服務器端的預備語句之前，要求執行方法PreparedStatement的次數。缺省值是5。 batchMode : boolean類型，用于確定是否使用batch模式連接。 fetchsize：integer類型，用于設置數據庫鏈接所創建statement的默認fetchsize。 ApplicationName：string類型。應用名稱，在不做設置時，缺省值為PostgreSQL JDBC Driver。 allowReadOnly:boolean類型，用于設置connection是否允許設置readonly模式，默認為false，若該參數不被設置為true，則執行connection.setReadOnly不生效。 blobMode:string類型，用于設置setBinaryStream方法為不同的數據類型賦值，設置為on時表示為blob數據類型賦值，設置為off時表示為bytea數據類型賦值，默認為on。 connectionExtraInfo：Boolean類型。表示驅動是否上報當前驅動的部署路徑、進程屬主用戶到數據庫。 說明 取值范圍：true或false，默認值為true。設置connectionExtraInfo為true，JDBC驅動會將當前驅動的部署路徑、進程屬主用戶上報到數據庫中，記錄在connection_info參數里；同時可以在PG_STAT_ACTIVITY和PGXC_STAT_ACTIVITY中查詢到。 |
| user | 數據庫用戶。 |
| password | 數據庫用戶的密碼。 |
以SSL證書方式加密連接樣例代碼如下：
//以下代碼將獲取數據庫SSL連接操作封裝為一個接口。
public static Connection GetConnection(String username, String passwd)
{
//定義驅動類。
String driver = "org.postgresql.Driver";
//設置keystore。
System.setProperty("javax.net.ssl.trustStore", "mytruststore");
System.setProperty("javax.net.ssl.keyStore", "client.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "password");
System.setProperty("javax.net.ssl.keyStorePassword", "password");
Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", passwd);
props.setProperty("ssl", "true");
String url = "jdbc:postgresql://" + "10.10.0.13" + ':'
+ "8000" + '/'
+ "gaussdb";
Connection conn = null;
try
{
//加載驅動。
Class.forName(driver);
}
catch( Exception e )
{
e.printStackTrace();
return null;
}
try
{
//創建連接。
conn = DriverManager.getConnection(url, props );
System.out.println("Connection succeed!");
}
catch(Exception e)
{
e.printStackTrace();
return null;
}
return conn;
}
- 執行SQL語句。
a.創建語句對象。
Statement stmt = con.createStatement();
b.執行語句對象。
int rc = stmt.executeUpdate("CREATE TABLE tab1(id INTEGER, name VARCHAR(32));");
c.釋放語句對象。
stmt.close();
- 調用方法close()關閉連接。
示例代碼
此示例將演示如何基于DWS 提供的JDBC接口開發應用程序。
說明在完成以下示例前，需要先創建存儲過程。具體請參見《[數據倉庫服務用戶開發指南](//www.daliqc.cn/document/10014061/10025616)》中的“教程：使用JDBC或ODBC開發”章節。
create or replace procedure testproc
(
psv_in1 in integer,
psv_in2 in integer,
psv_inout in out integer
)
as
begin
psv_inout := psv_in1 + psv_in2 + psv_inout;
end;
/
//DBtest.java
//以下用例以gsjdbc4.jar為例。
//演示基于JDBC開發的主要步驟，會涉及創建數據庫、創建表、插入數據等。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;
import java.sql.Statement;
import java.sql.CallableStatement;
import java.sql.Types;
public class DBTest {
//創建數據庫連接，以下IP地址和database替換為對應的數據庫連接地址和數據庫名稱。
public static Connection GetConnection(String username, String passwd) {
String driver = "org.postgresql.Driver";
String sourceURL = "jdbc:postgresql://10.10.0.13:8000/database";
Connection conn = null;
try {
//加載數據庫驅動。
Class.forName(driver).newInstance();
} catch (Exception e) {
e.printStackTrace();
return null;
}
try {
//創建數據庫連接。
conn = DriverManager.getConnection(sourceURL, username, passwd);
System.out.println("Connection succeed!");
} catch (Exception e) {
e.printStackTrace();
return null;
}
return conn;
};
//執行普通SQL語句，創建customer_t1表。
public static void CreateTable(Connection conn) {
Statement stmt = null;
try {
stmt = conn.createStatement();
//執行普通SQL語句。
int rc = stmt
.executeUpdate("CREATE TABLE customer_t1(c_customer_sk INTEGER, c_customer_name VARCHAR(32));");
stmt.close();
} catch (SQLException e) {
if (stmt != null) {
try {
stmt.close();
} catch (SQLException e1) {
e1.printStackTrace();
}
}
e.printStackTrace();
}
}
//執行預處理語句，批量插入數據。
public static void BatchInsertData(Connection conn) {
PreparedStatement pst = null;
try {
//生成預處理語句。
pst = conn.prepareStatement("INSERT INTO customer_t1 VALUES (?,?)");
for (int i = 0; i < 3; i++) {
//添加參數。
pst.setInt(1, i);
pst.setString(2, "data " + i);
pst.addBatch();
}
//執行批處理。
pst.executeBatch();
pst.close();
} catch (SQLException e) {
if (pst != null) {
try {
pst.close();
} catch (SQLException e1) {
e1.printStackTrace();
}
}
e.printStackTrace();
}
}
//執行預編譯語句，更新數據。
public static void ExecPreparedSQL(Connection conn) {
PreparedStatement pstmt = null;
try {
pstmt = conn
.prepareStatement("UPDATE customer_t1 SET c_customer_name = ? WHERE c_customer_sk = 1");
pstmt.setString(1, "new Data");
int rowcount = pstmt.executeUpdate();
pstmt.close();
} catch (SQLException e) {
if (pstmt != null) {
try {
pstmt.close();
} catch (SQLException e1) {
e1.printStackTrace();
}
}
e.printStackTrace();
}
}
//執行存儲過程。
public static void ExecCallableSQL(Connection conn) {
CallableStatement cstmt = null;
try {
cstmt=conn.prepareCall("{? = CALL TESTPROC(?,?,?)}");
cstmt.setInt(2, 50);
cstmt.setInt(1, 20);
cstmt.setInt(3, 90);
cstmt.registerOutParameter(4, Types.INTEGER); //注冊out類型的參數，類型為整型。
cstmt.execute();
int out = cstmt.getInt(4); //獲取out參數
System.out.println("The CallableStatment TESTPROC returns:"+out);
cstmt.close();
} catch (SQLException e) {
if (cstmt != null) {
try {
cstmt.close();
} catch (SQLException e1) {
e1.printStackTrace();
}
}
e.printStackTrace();
}
}
/**
* 主程序，逐步調用各靜態方法。
* @param args
*/
public static void main(String[] args) {
//創建數據庫連接，以下User、Password替換為實際連接的數據庫用戶和密碼。
Connection conn = GetConnection("User", "Password");
//創建表。
CreateTable(conn);
//批插數據。
BatchInsertData(conn);
//執行預編譯語句，更新數據。
ExecPreparedSQL(conn);
//執行存儲過程。
ExecCallableSQL(conn);
//關閉數據庫連接。
try {
conn.close();
} catch (SQLException e) {
e.printStackTrace();
}
}
}
配置JDBC連接（使用負載均衡方式）
背景信息
很多用戶在使用JDBC連接集群時只連接集群的一個CN，這就導致單個CN壓力較大并且別的CN資源浪費，并且這種方式還有單點故障導致連接不可用的風險。
用戶可使用JDBC連接多個CN避免以上問題。主要有以下兩種方式：
- 使用ELB連接集群：彈性負載均衡（ELB）是將訪問流量根據轉發策略分發到后端多臺彈性云服務器的流量分發控制服務，可以通過流量分發擴展應用系統對外的服務能力，提高應用程序的容錯能力。
- 使用multi-host方式連接集群：使用JDBC配置多個節點的方式，也能實現類似ELB的效果。
方式一：使用ELB連接集群（推薦）
- 獲取彈性負載均衡地址。在控制臺打開指定集群詳情頁面，獲取彈性負載均衡IP。
- 配置驅動。
- 獲取數據庫連接。
private static final String USER_NAME = "dbadmin";
private static final String PASSWORD = "password";
// jdbc:postgresql://ELB_IP:PORT/dbName"
private static final String URL = "jdbc:postgresql://100.95.153.169:8000/gaussdb";
private static Properties properties = new Properties();
static {
properties.setProperty("user", USER_NAME);
properties.setProperty("password", PASSWORD);
}
/**
* 獲取數據庫連接
*/
public static Connection getConnection() {
Connection connection = null;
try {
connection = DriverManager.getConnection(URL, properties);
} catch (SQLException e) {
e.printStackTrace();
}
return connection;
}
方式二：使用multi-host方式連接集群
- 獲取公網IP。打開控制臺指定集群詳情頁面，獲取彈性公網IP。
- 配置驅動。
- 獲取數據庫連接。
private static final String USER_NAME = "dbadmin";
private static final String PASSWORD = "password";
// jdbc:postgresql://host1:port1,host2:port2/dbName"
private static final String URL = "jdbc:postgresql://100.95.146.194:8000,100.95.148.220:8000,100.93.0.221:8000/gaussdb?loadBalanceHosts=true";
private static Properties properties = new Properties();
static {
properties.setProperty("user", USER_NAME);
properties.setProperty("password", PASSWORD);
}
/**
* 獲取數據庫連接
*/
public static Connection getConnection() {
Connection connection = null;
try {
connection = DriverManager.getConnection(URL, properties);
} catch (SQLException e) {
e.printStackTrace();
}
return connection;
}
配置JDBC連接集群（使用IAM認證方式）
概述
DWS 提供了使用IAM認證方式訪問數據庫的功能。當使用JDBC應用程序連接集群時，您可以在JDBC連接中配置IAM用戶名及其用戶憑證等信息，在連接數據庫時系統就會自動生成臨時數據庫憑證，從而成功連接到數據庫。
說明當前僅支持1.3.1及以上版本的集群及其配套的JDBC驅動程序使用IAM認證方式訪問數據庫。請先參考上方“下載JDBC或ODBC驅動”章節，下載JDBC驅動程序。
IAM用戶憑證有密碼和訪問密鑰（Access Key ID和Secret Access Key，簡稱AK和SK）兩種類型，您要為JDBC連接提供 IAM 訪問密鑰。
如需使用IAM用戶憑證訪問數據庫，必須先給您的IAM用戶授予DWS Database Access權限，同時擁有DWS Administrator和DWS Database Access權限的用戶，才能基于IAM用戶生成臨時數據庫用戶憑證以連接DWS 數據庫。
需要注意的是，DWS Database Access是用戶組級別的權限，您可以通過為用戶組授權并將用戶加入到用戶組的方式，使用戶具有用戶組中的權限。
在IAM中，只有admin用戶組的用戶可以管理用戶。如需給IAM用戶授權，您的IAM帳號必須屬于IAM的admin用戶組，否則，請聯系IAM賬號管理員幫您授權。
使用IAM用戶憑證訪問數據庫的流程如下：
- 授予IAM用戶DWS Database Access權限。
- 創建IAM用戶憑證。
- 配置JDBC連接使用IAM認證方式連接集群。
授予IAM用戶DWS Database Access權限
- 登錄云管理控制臺，單擊“服務列表 > 管理與監管 > 統一身份認證服務”，打開IAM管理控制臺。
- 修改您的IAM用戶所屬的用戶組，給用戶組設置策略，授予用戶組DWS Database Access權限，并將您的IAM用戶添加到該IAM用戶組中。
只有IAM的admin用戶組的用戶才能執行此步驟。在IAM中，只有admin用戶組的用戶可以管理用戶，包括創建用戶組及用戶、設置用戶組權限等。
具體操作請參見《統一身份認證服務用戶指南》中的“用戶指南 > 管理用戶和用戶組 > 查看或修改用戶組”。
您也可以新創建一個IAM用戶組，并給用戶組設置策略，授予用戶組DWS Administrator和DWS Database Access權限，然后將您的IAM用戶添加到該IAM用戶組中。具體操作請參見《統一身份認證服務用戶指南》中的“用戶指南。
管理用戶和用戶組 > 創建用戶組”。
創建IAM用戶憑證
用戶可以登錄管理控制臺創建訪問密鑰，如果您已經創建過了，也可以使用已有的訪問密鑰。
- 登錄管理控制臺。
- 將鼠標移到右上角的用戶名，單擊“我的憑證”。
- 再單擊“管理訪問密鑰”頁簽，可以查看已有的訪問密鑰，也可以單擊“新增訪問密鑰”進行創建。
訪問密鑰是IAM身份認證的重要憑證，只有在新增訪問密鑰時，用戶才可以下載到含有Access Key ID（AK）和Secret Access Key（SK）的密鑰文件，在管理控制臺只能查看到Access Key ID，如果您未曾下載過該密鑰文件，請聯系您的管理員進行獲取，或者重新創建。
說明每個用戶最多可創建2個訪問密鑰，有效期為永久。為了帳號安全性，建議您定期更換并妥善保存訪問密鑰。
配置JDBC連接使用IAM認證方式連接集群
配置JDBC連接參數
數據庫連接參數
| 參數 | 描述 |
|---|---|
| url | gsjdbc4.jar/gsjdbc200.jar數據庫連接描述符。JDBC接口不提供重試連接的能力，您需要在業務代碼中實現重試連接的處理。url示例如下： jdbc:dws:iam://dws-IAM-demo:cn-north-4/gaussdb?AccessKeyID=XXXXXXXXXXXXXXXXXXXX&SecretAccessKey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&DbUser=user_test&AutoCreate=true JDBC URL參數說明： jdbc:dws:iam是URL格式的前綴。 dws-IAM-demo為數據庫集群名稱。 cn-north-4是集群所在的區域。 有關DWS的區域信息，請向數據庫系統管理員獲取。 gaussdb是要連接的數據庫名。 AccessKeyID/SecretAccessKey為參數DbUser指定的IAM用戶所對應的訪問密鑰ID和秘密訪問密鑰。 DbUser請設置為IAM用戶名，注意，當前版本暫不支持IAM用戶名中含有中劃線的情況。 ? 如果數據庫中已存在DbUser指定的用戶，則臨時用戶憑證具有與現有用戶相同的權限。 ? 如果數據庫中不存在DbUser指定的用戶，且AutoCreate參數值為true，則自動創建一個以DbUser參數值作為用戶名的新用戶，默認創建的用戶為數據庫普通用戶。 AutoCreate可以不設置，默認為false。該參數表示是否在數據庫中自動創建一個以DbUser參數值作為用戶名的數據庫用戶。 ? true表示自動創建。如果用戶已存在則不會再創建。 ? false表示不會自動創建。如果數據庫中不存在DbUser指定的用戶名將返回失敗。 |
| info | 數據庫連接屬性。常用的屬性如下： ssl：Boolean類型。表示是否使用SSL連接。 loglevel：Integer類型。為LogStream或LogWriter設置記錄進DriverManager當前值的日志信息量。 目前支持org.postgresql.Driver.DEBUG和org.postgresql.Driver.INFO。值為1時，表示只打印org.postgresql.Driver.INFO，將記錄非常少的信息。值大于等于2時，表示打印org.postgresql.Driver.DEBUG和org.postgresql.Driver.INFO，將產生詳細的日志信息。默認值為0，表示不打印日志。 charSet：String類型。表示在向數據庫發送數據或從數據庫接收數據時使用到的字符集。 prepareThreshold：Integer類型。用于確定在轉換為服務器端的預備語句之前，要求執行方法PreparedStatement的次數。缺省值是5。 |
示例
//以下用例以gsjdbc4.jar為例。
//以下代碼將獲取數據庫連接操作封裝為一個接口，可通過給定集群所在的區域、集群名稱、AccessKeyID、SecretAccessKey及對應的IAM用戶名來連接數據庫。
public static Connection GetConnection(String clustername, String regionname, String AK, String SK, String username)
{
//驅動類。
String driver = "org.postgresql.Driver";
//數據庫連接描述符。
String sourceURL = "jdbc:dws:iam://" + clustername + ":" + regionname + "/postgresgaussdb?" + "AccessKeyID=" + AK + "&SecretAccessKey=" + SK + "&DbUser=" + username + "&autoCreate=true";
Connection conn = null;
try
{
//加載驅動。
Class.forName(driver);
}
catch( Exception e )
{
return null;
}
try
{
//創建連接。
conn = DriverManager.getConnection(sourceURL);
System.out.println("Connection succeed!");
}
catch(Exception e)
{
return null;
}
return conn;
};
使用ODBC連接數據庫
DWS 支持使用ODBC應用程序連接數據庫。應用程序可以在云平臺環境的彈性云主機中，或者互聯網環境連接數據庫。
ODBC接口的使用方法，請自行查閱官方文檔。
前提條件
- 已下載Linux版本的ODBC驅動包“dws_odbc_driver_for_linux.zip”和Windows版本的ODBC驅動包“dws_odbc_driver_for_windows.zip”，請參見上方“下載JDBC或ODBC驅動”章節。DWS 也支持開源的ODBC驅動程序：PostgreSQL ODBC 09.01.0200或更高版本。
- 已下載開源unixODBC代碼文件，支持版本為2.3.0。
- 已下載SSL證書文件，請參見使用SSL進行安全的TCP/IP連接章節“在 gsql 客戶端配置 SSL 認證相關的數字證書參數”部分內容，下載SSL證書。
在Linux環境使用ODBC連接
- 將ODBC驅動包和代碼文件上傳到Linux環境，并解壓到指定目錄。
- 以root用戶登錄Linux環境。
- 準備unixODBC。
a.解壓unixODBC代碼文件。
tar-xvf unixODBC-2.3.0.tar.gz
b.修改配置。
cd unixODBC-2.3.0
vi configure
將“LIB_VERSION”修改為如下內容，并保存退出。
LIB_VERSION="1:0:0"
c.編譯并安裝。
./configure--enable-gui=no
make
make install
- 替換驅動文件。
a.解壓“dws_odbc_driver_for_linux.zip”。
unzip dws_odbc_driver_for_linux.zip
b.將“dws_odbc_driver_for_linux.zip”解壓后“lib”目錄下所有文件，替換到“/usr/local/lib”。
c.將“dws_odbc_driver_for_linux.zip”解壓后“odbc/lib”目錄下的“psqlodbcw.la”和“psqlodbcw.so”，保存到“/usr/local/lib”。
- 執行以下命令，修改驅動文件配置。
vi /usr/local/etc/odbcinst.ini
將以下內容保存到配置中
[DWS]
Driver64=/usr/local/lib/psqlodbcw.so
參數說明如下：
- “[DWS]”：表示驅動器名稱，支持自定義。
- “Driver64”或“Driver”：表示驅動動態庫的路徑。64位系統優先查找“Driver64”配置項，如果未配置則會繼續查找“Driver”。
- 執行以下命令，修改數據源文件。
vi /usr/local/etc/odbc.ini
將以下內容保存到配置文件中，并退出修改。
[DWSODBC]
Driver=DWS
Servername=10.10.0.13
Database=gaussdb
Username=dbadmin
Password=password
Port=8000
Sslmode=allow
| 參數名 | 說明 | 參數值樣例 |
|---|---|---|
| [DSN] | 數據源的名稱。 | [DWSODBC] |
| Driver | 驅動名稱，對應“odbcinst.ini”中的DriverName。 | Driver=DWS |
| Servername | 服務器的IP地址。 | Servername=10.10.0.13 |
| Database | 要連接的數據庫的名稱。 | Database=gaussdb |
| Username | 數據庫用戶名稱。 | Username=dbadmin |
| Password | 數據庫用戶密碼。 | Password=password |
| Port | 服務器的端口號。 | Port=8000 |
| Sslmode | SSL認證工作模式。集群默認開啟。 取值及含義： disable：只嘗試非SSL連接。 allow：首先嘗試非SSL連接，如果連接失敗，再嘗試SSL連接。 prefer：首先嘗試SSL連接，如果連接失敗，將嘗試非SSL連接。 require：只嘗試SSL連接。如果存在CA文件，則按設置成verify-ca的方式驗證。 verify-ca：只嘗試SSL連接，并且驗證服務器是否具有由可信任的證書機構簽發的證書。 verify-full：DWS不支持此模式。 說明 SSL模式安全性高于普通模式，集群默認開啟SSL功能允許來自客戶端的SSL連接或非SSL連接，建議在使用ODBC連接DWS集群時采用SSL模式。 |
Sslmode=allow |
說明其中，參數“Servername”和“Port”的值，可以在DWS 的管理控制臺查看。請登錄DWS 管理控制臺，單擊“連接管理”， 在“數據倉庫連接字符串”區域，選擇指定的集群，獲取該集群的“內網訪問地址”或“公網訪問地址”。具體步驟請參見[獲取集群連接地址](//www.daliqc.cn/document/10014061/10047782)。
- 配置環境變量。
vi ~/.bashrc
在配置文件中追加以下內容。
export LD_LIBRARY_PATH=/usr/local/lib/:$LD_LIBRARY_PATH
export ODBCSYSINI=/usr/local/etc
export ODBCINI=/usr/local/etc/odbc.ini
- 導入環境變量。
source ~/.bashrc
- 執行以下命令，開始連接。
/usr/local/bin/isql -v DWSODBC
界面顯示以下信息表示連接成功：
+---------------------------------------+
| Connected! |
| |
| sql-statement |
| help [tablename] |
| quit |
| |
+---------------------------------------+
SQL>
在Windows環境使用ODBC連接
- 解壓Windows版本的ODBC驅動包“dws_odbc_driver_for_windows.zip”，并安裝“psqlodbc.msi”。
- 解壓SSL證書壓縮包，并準備證書文件。
用戶可以根據實際情況選擇自動或手動部署方法。
自動部署：
雙擊"sslcert_env.bat"文件，即可完成證書的默認位置的部署。
說明該sslcert_env.bat為了保證證書環境的純凈，在%APPDATA%\postgresql目錄存在時，會提示是否需要移除相關目錄。如果有需要，請備份該目錄中的文件。
手動部署：
a.在“%APPDATA%\”目錄創建一個新文件夾，并命名為“postgresql”。
b.將證書文件包中的“client.crt”、“client.key”、“client.key.cipher”、“client.key.rand”文件保存至“%APPDATA%\postgresql”目錄，并且將文件名中的client改為 postgres ，例如“client.key”修改為“postgres.key”。
c.將“cacert.pem”文件保存至“%APPDATA%\postgresql”目錄，并更名為“root.crt”。
- 打開驅動管理器
因為目前DWS 只提供了32位的ODBC驅動程序，所以只支持32位的應用程序開發 ；在配置數據源時，也請使用32位的驅動管理器（假設操作系統安裝盤符為C:盤，如果是其他盤符，請對路徑做相應修改）：
- 64位操作系統請使用：C:\Windows\SysWOW64\odbcad32.exe
請勿直接使用“控制面板->系統和安全->管理工具->數據源(ODBC)”。
說明WoW64的全稱是"Windows32-bit on Windows 64-bit"，C:\Windows\SysWOW64\存放的是64位系統上的32位運行環境。而C:\Windows\System32\存放的是與操作系統一致的運行環境，具體的技術信息請查閱Windows的相關技術文檔。
- 32位操作系統請使用：C:\Windows\System32\odbcad32.exe
或者單擊“開始菜單->控制面板->系統和安全->管理工具->數據源(ODBC)”打開驅動管理器。
- 配置連接數據源。
a.在打開的驅動管理器上，選擇“用戶DSN>添加>PostgreSQL Unicode”，然后進行配置。
詳見下圖：配置連接數據源
其中，配置項“Server”和“Port”的值，可以在DWS 的管理控制臺查看。請登錄DWS 管理控制臺，單擊“連接管理”， 在“數據倉庫連接字符串”區域，選擇指定的集群，獲取該集群的“內網訪問地址”或“公網訪問地址”。具體步驟請參見獲取集群連接地址。
b.單擊“Test”驗證連接正確，界面提示“Connection successful”。
- 編寫ODBC樣例程序連接數據源。
ODBC接口不提供重試連接數據庫的能力，您需要在業務代碼中實現重試連接的處理。
樣例代碼如下：
// 此示例演示如何通過ODBC方式獲取DWS 中的數據。
// DBtest.c (compile with: libodbc.so)
#include <stdlib.h>
#include <stdio.h>
#include <sqlext.h>
#ifdef WIN32
#include <windows.h>
#endif
SQLHENV V_OD_Env; // Handle ODBC environment
SQLHSTMT V_OD_hstmt; // Handle statement
SQLHDBC V_OD_hdbc; // Handle connection
char typename[100];
SQLINTEGER value = 100;
SQLINTEGER V_OD_erg,V_OD_buffer,V_OD_err,V_OD_id;
int main(int argc,char *argv[])
{
// 1. 申請環境句柄
V_OD_erg = SQLAllocHandle(SQL_HANDLE_ENV,SQL_NULL_HANDLE,&V_OD_Env);
if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO))
{
printf("Error AllocHandle\n");
exit(0);
}
// 2. 設置環境屬性（版本信息）
SQLSetEnvAttr(V_OD_Env, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, 0);
// 3. 申請連接句柄
V_OD_erg = SQLAllocHandle(SQL_HANDLE_DBC, V_OD_Env, &V_OD_hdbc);
if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO))
{
SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env);
exit(0);
}
// 4. 設置連接屬性
SQLSetConnectAttr(V_OD_hdbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_ON, 0);
// 5. 連接數據源，其中的用戶名和用戶密碼等信息之所以能省略，是因為在odbc.ini文件中進行了配置，若沒配置需要在SQLConnect函數參數中具體寫明要連接數據庫的用戶名和用戶密碼等信息。
V_OD_erg = SQLConnect(V_OD_hdbc, (SQLCHAR*) "gaussdb", SQL_NTS,
(SQLCHAR*) "", SQL_NTS, (SQLCHAR*) "", SQL_NTS);
if ((V_OD_erg != SQL_SUCCESS) && (V_OD_erg != SQL_SUCCESS_WITH_INFO))
{
printf("Error SQLConnect %d\n",V_OD_erg);
SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env);
exit(0);
}
printf("Connected !\n");
// 6. 設置語句屬性
SQLSetStmtAttr(V_OD_hstmt,SQL_ATTR_QUERY_TIMEOUT,(SQLPOINTER *)3,0);
// 7. 申請語句句柄
SQLAllocHandle(SQL_HANDLE_STMT, V_OD_hdbc, &V_OD_hstmt);
// 8. 直接執行SQL語句。
SQLExecDirect(V_OD_hstmt,"drop table IF EXISTS testtable",SQL_NTS);
SQLExecDirect(V_OD_hstmt,"create table testtable(id int)",SQL_NTS);
SQLExecDirect(V_OD_hstmt,"insert into testtable values(25)",SQL_NTS);
// 9. 準備執行
SQLPrepare(V_OD_hstmt,"insert into testtable values(?)",SQL_NTS);
// 10. 綁定參數
SQLBindParameter(V_OD_hstmt,1,SQL_PARAM_INPUT,SQL_C_SLONG,SQL_INTEGER,0,0,
&value,0,NULL);
// 11. 執行準備好的語句
SQLExecute(V_OD_hstmt);
SQLExecDirect(V_OD_hstmt,"select id from testtable",SQL_NTS);
// 12. 獲取結果集某一列的屬性
SQLColAttribute(V_OD_hstmt,1,SQL_DESC_TYPE,typename,100,NULL,NULL);
printf("SQLColAtrribute %s\n",typename);
// 13. 綁定結果集
SQLBindCol(V_OD_hstmt,1,SQL_C_SLONG, (SQLPOINTER)&V_OD_buffer,150,
(SQLLEN *)&V_OD_err);
// 14. 通過SQLFetch取結果集中數據
V_OD_erg=SQLFetch(V_OD_hstmt);
// 15. 通過SQLGetData獲取并返回數據。
while(V_OD_erg != SQL_NO_DATA)
{
SQLGetData(V_OD_hstmt,1,SQL_C_SLONG,(SQLPOINTER)&V_OD_id,0,NULL);
printf("SQLGetData ----ID = %d\n",V_OD_id);
V_OD_erg=SQLFetch(V_OD_hstmt);
};
printf("Done !\n");
// 16. 斷開數據源連接并釋放句柄資源
SQLFreeHandle(SQL_HANDLE_STMT,V_OD_hstmt);
SQLDisconnect(V_OD_hdbc);
SQLFreeHandle(SQL_HANDLE_DBC,V_OD_hdbc);
SQLFreeHandle(SQL_HANDLE_ENV, V_OD_Env);
return(0);
}
