PQconnectdbParams
-
开启一个到数据库服务器的新连接。
PGconn *PQconnectdbParams(const char * const *keywords,
const char * const *values,
int expand_dbname);
这个函数使用从两个以NULL
结尾的数组中取得的参数打开一个新的数据库连接。第一个数组keywords
被定义为一个字符串数组,每一个元素是一个关键词。第二个数组values
给出了每个关键词的值。和下面的PQsetdbLogin
不同,可以在不改变函数签名的情况下扩展参数集合,因此使用这个函数(或者与之相似的非阻塞的PQconnectStartParams
和PQconnectPoll
)对于新应用编程要更好。
当前能被识别的参数关键词被列举在第 33.1.2 节中。
其可能的格式详见第 33.1.1 节。 当expand_dbname
为非零时,dbname
关键词的值被允许识别为一个连接字符串。只有dbname
的第一次出现会按这种方式扩展,任何后续dbname
值会被当 做一个普通数据库名处理。有关可能的连接字符串格式的详情可见 第 33.1.1 节。
被传递的数组可以为空,这样就会使用所有默认参数。也可以只包含一个或几个参数设置。两个参数数组应该在长度上匹配。对于参数数组的处理将会停止于keywords
数组中第一个非-NULL
元素。
如果任何一个参数是NULL
或者一个空字符串, 那么将会检查相应的环境变量(见第 33.14 节)。 如果该环境变量也没有被设置,那么将使用指示的内建默认值。
通常,关键词的处理是从这些数组的头部开始并且以索引顺序进行。这样做的效果就是,当关键词有重复时,只会保留最后一个被处理的值。因此,通过小心地放置关键词dbname
,可以决定什么会被一个conninfo
字符串所重载,以及什么不会被重载。
PQconnectdb
-
开启一个到数据库服务器的新连接。
PGconn *PQconnectdb(const char *conninfo);
这个函数使用从字符串conninfo
中得到的参数开启一个新的数据库连接。
被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见第 33.1.1 节。
PQsetdbLogin
-
开启一个到数据库服务器的新连接。
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
。
PQsetdb
-
开启一个到数据库服务器的新连接。
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName);
这是一个调用PQsetdbLogin
的宏,其中为login
和pwd
参数使用空指针。提供它是为了向后兼容非常老的程序。
-
PQconnectStartParams
PQconnectStart
PQconnectPoll
-
以非阻塞的方式建立一个到数据库服务器的连接。
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
都不会阻塞:
-
hostaddr
和host
参数被合适地使用,以确保不会做名字或逆向名字查询。详见第 33.1.2 节中这些参数的文档。
-
如果你调用PQtrace
,确保你追踪的该流对象不会阻塞。
-
如后文所述,你要确保在调用PQconnectPoll
之前,套接字处于合适的状态。
注意:PQconnectStartParams
的使用和下文所示的PQconnectStart
类似。
要开始一个非阻塞的连接请求,可调用conn = PQconnectStart("connection_info_string
")
。如果conn
为空,那么libpq无法分配一个新的PGconn
结构。否则,一个合法的PGconn
指针将被返回(尽管并不表示代表一个到数据库的合法连接)。在从PQconnectStart
返回时,调用status = PQstatus(conn)
。如果status
等于CONNECTION_BAD
,就说明PQconnectStart
已经失败。
如果PQconnectStart
成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)
来获得该数据库连接底层的套接字描述符。这样循环:如果PQconnectPoll(conn)
上一次返回PGRES_POLLING_READING
,等到该套接字准备好读取(按照select()
、poll()
或类似的系统函数所指示的)。则再次调用PQconnectPoll(conn)
。反之,如果PQconnectPoll(conn)
上一次返回PGRES_POLLING_WRITING
,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)
。如果你还没有调用PQconnectPoll
,即刚好在对PQconnectStart
的调用之后,行为就像是它上次返回了PGRES_POLLING_WRITING
。持续这个循环直到PQconnectPoll(conn)
返回PGRES_POLLING_FAILED
指示连接过程已经失败,或者返回PGRES_POLLING_OK
指示连接已经被成功地建立。
在连接期间的任意时刻,该连接的状态可以通过调用PQstatus
来检查。如果这个调用返回CONNECTION_BAD
,那么连接过程已经失败。如果该调用返回CONNECTION_OK
,则该连接已经准备好。如前所述,这些状态同样都可以从PQconnectPoll
的返回值检测。在一个异步连接过程中(也只有在这个过程中)也可能出现其他状态。这些状态指示该连接过程的当前阶段,并且可能有助于为用户提供反馈。这些状态是:
CONNECTION_STARTED
-
等待连接被建立。
CONNECTION_MADE
-
连接 OK,等待发送。
CONNECTION_AWAITING_RESPONSE
-
等待来自服务器的一个回应。
CONNECTION_AUTH_OK
-
收到认证,等待后端启动结束。
CONNECTION_SSL_STARTUP
-
协商 SSL 加密。
CONNECTION_SETENV
-
协商环境驱动的参数设置。
CONNECTION_CHECK_WRITABLE
-
检查连接是否能够处理写入事务。
CONNECTION_CONSUME
-
在连接上消费任何剩余的响应消息。
注意,尽管这些常数将被保留(为了维护兼容性),一个应用永远不应该依赖这些状态按照特定顺序出现,或者根本就不依赖它们,或者不依赖状态总是这些文档中所说的值。一个应用可能做些这样的事情:
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
返回一个非空的指针,你必须在用完它之后调用PQfinish
来处理那些结构和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。
PQconndefaults
-
返回默认连接选项。
PQconninfoOption *PQconndefaults(void);
typedef struct
{
char *keyword; /* 该选项的关键词 */
char *envvar; /* 依赖的环境变量名 */
char *compiled; /* 依赖的内建默认值 */
char *val; /* 选项的当前值,或者 NULL */
char *label; /* 连接对话框中域的标签 */
char *dispchar; /* 指示如何在一个连接对话框中显示这个域。值是:
"" 显示输入的值
"*" 口令域 - 隐藏值
"D" 调试选项 - 默认不显示 */
int dispsize; /* 用于对话框的以字符计的域尺寸 */
} PQconninfoOption;
返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的PQconnectdb
选项和它们的当前缺省值。返回值指向一个PQconninfoOption
结构的数组,该数组以一个包含空keyword
指针的条目结束。如果无法分配内存,则返回该空指针。注意当前缺省值(val
域)将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。
在处理完选项数组后,把它交给PQconninfoFree
释放。如果没有这么做, 每次调用PQconndefaults
都会导致一小部分内存泄漏。
PQconninfo
-
返回被一个活动连接使用的连接选项。
PQconninfoOption *PQconninfo(PGconn *conn);
返回一个连接选项数组。这可以用来确定用于连接服务器的所有可能的PQconnectdb
选项和它们的当前缺省值。返回值指向一个PQconninfoOption
结构的数组,该数组以一个包含空keyword
指针的条目结束。上述所有对于PQconndefaults
的注解也适用于PQconninfo
的结果。
PQconninfoParse
-
返回从提供的连接字符串中解析到的连接选项。
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
释放错误字符串。
PQfinish
-
关闭与服务器的连接。同时释放PGconn
对象使用的内存。
void PQfinish(PGconn *conn);
注意,即使与服务器的连接尝试失败(由PQstatus
指示),应用也应当调用PQfinish
来释放PGconn
对象使用的内存。不能在调用PQfinish
之后再使用PGconn
指针。
PQreset
-
重置与服务器的通讯通道。
void PQreset(PGconn *conn);
此函数将关闭与服务器的连接,并且使用所有之前使用过的参数尝试重新建立与同一个服务器的连接。这可能有助于在工作连接丢失后的错误恢复。
-
PQresetStart
PQresetPoll
-
以非阻塞方式重置与服务器的通讯通道。
int PQresetStart(PGconn *conn);
PostgresPollingStatusType PQresetPoll(PGconn *conn);
这些函数将关闭与服务器的连接,并且使用所有之前使用过的参数尝试重新建立与同一个服务器的连接。这可能有助于在工作连接丢失后的错误恢复。它们和上面的PQreset
的不同在于它们工作在非阻塞方式。这些函数受到PQconnectStartParams
、PQconnectStart
和PQconnectPoll
相同的限制。
要发起一次连接重置,调用PQresetStart
。如果它返回 0,那么重置失败。如果返回 1,用与使用PQresetPoll
建立连接的相同方法使用PQconnectPoll
重置连接。
PQpingParams
-
PQpingParams
报告服务器的状态。它接受与PQconnectdbParams
相同的连接参数。获得服务器状态不需要提供正确的用户名、口令或数据库名。不过,如果提供了不正确的值,服务器将记录一次失败的连接尝试。
PGPing PQpingParams(const char * const *keywords,
const char * const *values,
int expand_dbname);
该函数返回下列值之一:
PQPING_OK
-
服务器正在运行,并且看起来可以接受连接。
PQPING_REJECT
-
服务器正在运行,但是处于一种不允许连接的状态(启动、关闭或崩溃恢复)。
PQPING_NO_RESPONSE
-
无法联系到服务器。这可能表示服务器没有运行,或者给定的连接参数中有些错误(例如,错误的端口号),或者有一个网络连接问题(例如,一个防火墙阻断了连接请求)。
PQPING_NO_ATTEMPT
-
没有尝试联系服务器,因为提供的参数显然不正确,或者有一些客户端问题(例如,内存用完)。
PQping
-
PQping
报告服务器的状态。它接受与PQconnectdb
相同的连接参数。获得服务器状态不需要提供正确的用户名、口令或数据库名。不过,如果提供了不正确的值,服务器将记录一次失败的连接尝试。
PGPing PQping(const char *conninfo);
返回值和PQpingParams
相同。