45.2. 数据库连接函数
下面的例程用于从 C 程序建立与后端的连接。
PQsetdbLogin与后端建立一个新连接。PGconn *PQsetdbLogin(const char *pghost, const char *pgport, const char *pgoptions, const char *pgtty, const char *dbName, const char *login, const char *pwd);如果任何参数为 NULL,则检查相应的环境变量。如果环境变量也未设置,则使用硬编码的默认值。PQsetdbLogin 总是返回有效的 PGconn 指针。在通过连接发送查询之前,应当调用 PQstatus(见下文)确认连接已正确建立。
libpq程序员应注意维护 PGconn 的抽象。请使用下面的访问函数获取 PGconn 的内容。避免直接引用 PGconn 结构的字段,因为它们将来可能改变。PQsetdb与后端建立一个新连接。PGconn *PQsetdb(char *pghost, char *pgport, char *pgoptions, char *pgtty, char *dbName);这是一个宏,以空指针作为 login 和 pwd 参数调用 PQsetdbLogin()。
PQconndefaults返回连接选项。PQconninfoOption *PQconndefaults(void) struct PQconninfoOption { char *keyword; /* The keyword of the option */ char *environ; /* Fallback environment variable name */ char *compiled; /* Fallback compiled in default value */ char *val; /* Options value */ char *label; /* Label for field in connect dialog */ char *dispchar; /* Character to display for this field in a connect dialog. Values are: "" Display entered value as is "*" Password field - hide value "D" Debug options - don't create a field by default */ int dispsize; /* Field size in characters for dialog */ };返回连接选项结构的地址。它可用来确定所有可用选项及其当前值。
PQdb返回连接的数据库名。char *PQdb(PGconn *conn)
PQhost返回连接的主机名。char *PQhost(PGconn *conn)
PQoptions返回连接中使用的 pgoptions。char *PQoptions(PGconn *conn)
PQport返回连接的 pgport。char *PQport(PGconn *conn)
PQtty返回连接的 pgtty。char *PQtty(PGconn *conn)
PQstatus返回连接的状态。状态可以是 CONNECTION_OK 或 CONNECTION_BAD。ConnStatusType *PQstatus(PGconn *conn)
PQerrorMessage返回与连接相关联的错误消息char *PQerrorMessage(PGconn* conn);
PQfinish关闭与后端的连接,同时释放 PGconn 结构使用的内存。调用过 PQfinish 之后,不应再使用该 PGconn 指针。void PQfinish(PGconn *conn)
PQreset重置与后端的通信端口。此函数将关闭到后端的 IPC 套接字连接,并尝试与同一个后端重新建立新连接。void PQreset(PGconn *conn)
PQtrace打开前端与后端之间所传消息的跟踪。这些消息会被回显到 debug_port 文件流。void PQtrace(PGconn *conn, FILE* debug_port);PQuntrace关闭前端与后端之间所传消息的跟踪。void PQuntrace(PGconn *conn);