建立與資料庫伺服器的新連線。

PGconn *PQconnectdbParams(const char * const *keywords,
                          const char * const *values,
                          int expand_dbname);

此函數使用從兩個以 NULL 結尾的陣列中取得的參數開啟新的資料庫連線。 第一個陣列 keywords 定義為字串陣列，每個字串都是一個關鍵字。 第二個陣列 values 提供每個關鍵字的值。 與下面的 PQsetdbLogin 不同，可以擴展參數集而無需變更函數簽名，因此對於新的應用程式編程，建議使用此函數（或其非阻塞類比 PQconnectStartParams 和 PQconnectPoll）。

目前可識別的參數關鍵字列於第 32.1.2 節。

傳遞的陣列可以是空的，以使用所有預設參數，也可以包含一個或多個參數設定。它們的長度必須匹配。處理將在 keywords 陣列中的第一個 NULL 條目處停止。此外，如果與非 NULL 的 keywords 條目關聯的 values 條目是 NULL 或空字串，則該條目將被忽略，並且處理將繼續使用下一對陣列條目。

當 expand_dbname 非零時，將檢查第一個 dbname 關鍵字的值，以查看它是否是連線字串。 如果是，它將被「展開」為從字串中提取的個別連線參數。 如果該值包含等號 (=) 或以 URI 方案指示符開頭，則該值被視為連線字串，而不僅僅是資料庫名稱。（有關連線字串格式的更多詳細資訊，請參閱第 32.1.1 節。）僅以這種方式處理 dbname 的第一次出現； 任何後續的 dbname 參數都將被視為普通的資料庫名稱。

通常，參數陣列會從頭到尾依序處理。如果任何關鍵字重複出現，則使用最後一個值 (不是 NULL 或空字串)。此規則特別適用於連線字串中找到的關鍵字與 keywords 陣列中出現的關鍵字衝突時。因此，程式設計師可以決定陣列條目是否可以覆蓋或被來自連線字串的值覆蓋。出現在展開的 dbname 條目之前的陣列條目可以被連線字串的欄位覆蓋，而連線字串的欄位又可以被出現在 dbname 之後的陣列條目覆蓋（但同樣地，僅當這些條目提供非空值時）。

在處理完所有陣列條目和任何展開的連線字串後，任何未設定的連線參數都會填入預設值。如果未設定參數的相應環境變數（請參閱第 32.15 節），則使用其值。如果環境變數也未設定，則使用參數的內建預設值。

建立與資料庫伺服器的新連線。

PGconn *PQconnectdb(const char *conninfo);

此函數使用從字串 conninfo 取得的參數開啟新的資料庫連線。

傳遞的字串可以是空的，以使用所有預設參數，或者它可以包含一個或多個以空白分隔的參數設定，或者它可以包含一個URI。有關詳細資訊，請參閱第 32.1.1 節。

建立與資料庫伺服器的新連線。

PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);

這是 PQconnectdb 的前身，具有固定的參數集。它具有相同的功能，只是遺失的參數將始終採用預設值。對於任何要預設的固定參數，請寫入 NULL 或空字串。

如果 dbName 包含一個 = 符號或具有有效的連線URI前綴，它將被視為一個 conninfo 字串，其處理方式與傳遞給 PQconnectdb 完全相同，然後將剩餘的參數按照 PQconnectdbParams 的指定方式應用。

pgtty 不再使用，並且任何傳遞的值都將被忽略。

建立與資料庫伺服器的新連線。

PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);

這是一個巨集，使用 null 指標作為 login 和 pwd 參數來呼叫 PQsetdbLogin。提供它是為了與非常舊的程式保持向後相容性。

以非阻塞方式連線到資料庫伺服器。

PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *values,
                             int expand_dbname);

PGconn *PQconnectStart(const char *conninfo);

PostgresPollingStatusType PQconnectPoll(PGconn *conn);

這三個函數用於開啟到資料庫伺服器的連線，這樣您的應用程式執行緒在執行時不會被遠端 I/O 阻塞。這種方法的重點是，等待 I/O 完成可以在應用程式的主迴圈中發生，而不是在 PQconnectdbParams 或 PQconnectdb 內部發生，因此應用程式可以與其他活動平行管理此操作。

使用 PQconnectStartParams，資料庫連線是使用從 keywords 和 values 陣列中取得的參數建立的，並由 expand_dbname 控制，如上面對 PQconnectdbParams 的描述。

使用 PQconnectStart，資料庫連線是使用從字串 conninfo 取得的參數建立的，如上面對 PQconnectdb 的描述。

只要滿足一些限制，PQconnectStartParams、PQconnectStart 和 PQconnectPoll 都不會阻塞

若要開始非阻塞連線請求，請呼叫 PQconnectStart 或 PQconnectStartParams。如果結果為 null，則 libpq 無法配置新的 PGconn 結構。否則，會傳回有效的 PGconn 指標（但尚未表示到資料庫的有效連線）。接下來呼叫 PQstatus(conn)。如果結果為 CONNECTION_BAD，則連線嘗試已失敗，通常是因為無效的連線參數。

如果 PQconnectStart 或 PQconnectStartParams 成功，則下一個階段是輪詢 libpq，以便它可以繼續進行連線序列。使用 PQsocket(conn) 取得資料庫連線底層的套接字描述符。(注意：不要假設套接字在 PQconnectPoll 呼叫中保持不變。) 迴圈如下：如果 PQconnectPoll(conn) 最後傳回 PGRES_POLLING_READING，則等到套接字準備好讀取（如 select()、poll() 或類似的系統函數所示）。請注意，如果您的系統上可用，PQsocketPoll 可以透過抽象化 select(2) 或 poll(2) 的設定來幫助減少樣板程式碼。然後再次呼叫 PQconnectPoll(conn)。相反地，如果 PQconnectPoll(conn) 最後傳回 PGRES_POLLING_WRITING，則等到套接字準備好寫入，然後再次呼叫 PQconnectPoll(conn)。在第一次迭代中，即如果您尚未呼叫 PQconnectPoll，則表現得好像它最後傳回 PGRES_POLLING_WRITING。繼續此迴圈，直到 PQconnectPoll(conn) 傳回 PGRES_POLLING_FAILED，表示連線程序已失敗，或者 PGRES_POLLING_OK，表示連線已成功建立。

在連線期間的任何時間，都可以透過呼叫 PQstatus 來檢查連線狀態。如果此呼叫傳回 CONNECTION_BAD，則連線程序已失敗；如果呼叫傳回 CONNECTION_OK，則連線已準備就緒。從上述 PQconnectPoll 的傳回值同樣可以偵測到這兩種狀態。在非同步連線程序期間（且僅在該期間），也可能發生其他狀態。這些狀態指示連線程序的目前階段，並且可能有用於向使用者提供回饋。這些狀態是

請注意，雖然這些常數會保留（為了維持相容性），但應用程式絕不應該依賴這些常數以特定的順序發生，或完全發生，或依賴於狀態始終是這些文件中記錄的值之一。應用程式可能會執行類似以下的操作

switch(PQstatus(conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
}

當使用 PQconnectPoll 時，connect_timeout 連線參數會被忽略；由應用程式自行決定是否經過了過多的時間。 否則，PQconnectStart 後面跟著 PQconnectPoll 迴圈，等同於 PQconnectdb。

請注意，當 PQconnectStart 或 PQconnectStartParams 傳回一個非 null 指標時，您必須在完成使用後呼叫 PQfinish，以便處置該結構和任何相關的記憶體區塊。即使連線嘗試失敗或被放棄，也必須執行此操作。

輪詢使用 PQsocket 擷取的連線底層 socket 描述符。此函數的主要用途是迭代 PQconnectStartParams 文件中描述的連線序列。

typedef pg_int64 pg_usec_time_t;

int PQsocketPoll(int sock, int forRead, int forWrite,
                 pg_usec_time_t end_time);

此函數執行檔案描述符的輪詢，並可選擇設定逾時時間。如果 forRead 非零，則當 socket 準備好進行讀取時，該函數將終止。如果 forWrite 非零，則當 socket 準備好進行寫入時，該函數將終止。

逾時時間由 end_time 指定，它是停止等待的時間，以自 Unix Epoch 以來的微秒數表示（即，time_t 乘以 100 萬）。如果 end_time 是 -1，則逾時時間是無限的。如果 end_time 是 0 （或者，實際上，任何早於現在的時間），則逾時時間是立即的（不阻塞）。逾時值可以透過將所需的微秒數加到 PQgetCurrentTimeUSec 的結果中來方便地計算。請注意，底層系統呼叫可能具有小於微秒的精度，因此實際的延遲可能不精確。

如果滿足指定條件，該函數將傳回一個大於 0 的值；如果發生逾時，則傳回 0；如果發生錯誤，則傳回 -1。可以透過檢查 errno(3) 值來檢索錯誤。如果 forRead 和 forWrite 均為零，則該函數會立即傳回逾時指示。

PQsocketPoll 是使用 poll(2) 或 select(2) 實作的，具體取決於平台。有關更多資訊，請參閱 poll(2) 中的 POLLIN 和 POLLOUT，或 select(2) 中的 readfds 和 writefds。

傳回預設的連線選項。

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* The keyword of the option */
    char   *envvar;    /* Fallback environment variable name */
    char   *compiled;  /* Fallback compiled in default value */
    char   *val;       /* Option's current value, or NULL */
    char   *label;     /* Label for field in connect dialog */
    char   *dispchar;  /* Indicates how to display this field
                          in a connect dialog. Values are:
                          ""        Display entered value as is
                          "*"       Password field - hide value
                          "D"       Debug option - don't show by default */
    int     dispsize;  /* Field size in characters for dialog */
} PQconninfoOption;

傳回連線選項陣列。這可用於確定所有可能的 PQconnectdb 選項及其目前的預設值。傳回值指向一個 PQconninfoOption 結構的陣列，該陣列以一個具有空 keyword 指標的條目結尾。如果無法分配記憶體，則傳回空指標。請注意，目前的預設值（val 欄位）將取決於環境變數和其他上下文。遺失或無效的服務檔案將被靜默忽略。呼叫者必須將連線選項資料視為唯讀。

處理選項陣列後，透過將其傳遞給 PQconninfoFree 來釋放它。如果沒有這樣做，則每次呼叫 PQconndefaults 都會洩漏少量記憶體。

傳回即時連線使用的連線選項。

PQconninfoOption *PQconninfo(PGconn *conn);

傳回連線選項陣列。這可用於確定所有可能的 PQconnectdb 選項以及用於連線到伺服器的值。傳回值指向一個 PQconninfoOption 結構的陣列，該陣列以一個具有空 keyword 指標的條目結尾。PQconndefaults 的所有上述說明也適用於 PQconninfo 的結果。

從提供的連線字串傳回已剖析的連線選項。

PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);

剖析連線字串並將結果選項作為陣列傳回；如果連線字串有問題，則傳回 NULL。此函數可用於提取提供的連線字串中的 PQconnectdb 選項。傳回值指向一個 PQconninfoOption 結構的陣列，該陣列以一個具有空 keyword 指標的條目結尾。

所有合法的選項都會出現在結果陣列中，但是連線字串中不存在的任何選項的 PQconninfoOption 都會將 val 設定為 NULL；不會插入預設值。

如果 errmsg 不是 NULL，成功時 *errmsg 會被設定為 NULL；否則，會被設定為一個用 malloc 分配的錯誤字串，來說明問題。(也有可能 *errmsg 被設定為 NULL，且函式返回 NULL；這表示記憶體不足的情況。)

處理選項陣列後，將其傳遞給 PQconninfoFree 來釋放它。 如果不這樣做，每次呼叫 PQconninfoParse 都會洩漏一些記憶體。 相反地，如果發生錯誤且 errmsg 不是 NULL，請務必使用 PQfreemem 釋放錯誤字串。

關閉與伺服器的連線。 同時釋放 PGconn 物件使用的記憶體。

void PQfinish(PGconn *conn);

請注意，即使伺服器連線嘗試失敗（如 PQstatus 所示），應用程式也應呼叫 PQfinish 以釋放 PGconn 物件使用的記憶體。 在呼叫 PQfinish 後，不得再次使用 PGconn 指標。

重設與伺服器的通訊通道。

void PQreset(PGconn *conn);

此函式將關閉與伺服器的連線，並嘗試建立新的連線，使用之前使用的所有相同參數。 如果工作連線遺失，這可能對錯誤恢復很有用。

以非阻塞的方式重設與伺服器的通訊通道。

int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);

這些函式將關閉與伺服器的連線，並嘗試建立新的連線，使用之前使用的所有相同參數。 如果工作連線遺失，這可能對錯誤恢復很有用。 它們與 PQreset（如上所述）的不同之處在於，它們以非阻塞的方式運作。 這些函式具有與 PQconnectStartParams、PQconnectStart 和 PQconnectPoll 相同的限制。

要啟動連線重設，請呼叫 PQresetStart。 如果它返回 0，則重設失敗。 如果它返回 1，請使用 PQresetPoll 以與使用 PQconnectPoll 建立連線完全相同的方式輪詢重設。

PQpingParams 報告伺服器的狀態。 它接受與上面描述的 PQconnectdbParams 相同的連線參數。 沒有必要提供正確的使用者名稱、密碼或資料庫名稱值來取得伺服器狀態； 但是，如果提供了不正確的值，伺服器將記錄失敗的連線嘗試。

PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);

該函式返回以下值之一

PQping 報告伺服器的狀態。 它接受與上面描述的 PQconnectdb 相同的連線參數。 沒有必要提供正確的使用者名稱、密碼或資料庫名稱值來取得伺服器狀態； 但是，如果提供了不正確的值，伺服器將記錄失敗的連線嘗試。

PGPing PQping(const char *conninfo);

返回值與 PQpingParams 的返回值相同。

PQsetSSLKeyPassHook_OpenSSL 允許應用程式使用 sslpassword 或互動式提示，來覆蓋 libpq 的 加密用戶端憑證金鑰檔案的預設處理方式。

void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);

應用程式傳遞一個指向簽名回呼函式的指標

int callback_fn(char *buf, int size, PGconn *conn);

然後 libpq 將呼叫該函式 而不是 其預設的 PQdefaultSSLKeyPassHook_OpenSSL 處理常式。 回呼應確定金鑰的密碼，並將其複製到大小為 size 的結果緩衝區 buf 中。buf 中的字串必須以 null 結尾。 回呼必須返回儲存在 buf 中密碼的長度，不包括 null 終止符。 失敗時，回呼應設定 buf[0] = '\0' 並返回 0。 有關範例，請參閱 libpq 原始碼中的 PQdefaultSSLKeyPassHook_OpenSSL。

如果使用者指定了顯式金鑰位置，則在呼叫回呼時，其路徑將位於 conn->sslkey 中。 如果使用預設金鑰路徑，則此值將為空。 對於作為引擎說明符的金鑰，是否使用 OpenSSL 密碼回呼或定義自己的處理方式取決於引擎的實作。

應用程式回呼可以選擇將未處理的情況委託給 PQdefaultSSLKeyPassHook_OpenSSL，或者先呼叫它，如果它返回 0，則嘗試其他操作，或者完全覆蓋它。

回呼 不得 使用異常、longjmp(...) 等跳脫正常的流程控制。 它必須正常返回。

PQgetSSLKeyPassHook_OpenSSL 會傳回目前用戶端憑證金鑰密碼勾點 (hook)，如果沒有設定，則傳回 NULL。

PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);