数据库编程接口Libpq

Libpq是PostgreSQL提供的C语言数据库编程接口，用户可以使用Libpq的API来访问数据库，开发应用程序。 1.1 数据库连接控制函数 应用程序在连接数据库时必须使用本节介绍的数据库连接控制函数。应用程序可以同时建立多个数据库连接，一个连接只能访问一个数据库中的数据。每个数据库连接用一个PGconn对象表示，函数PQconnectdb 或PQsetdbLogin会返回一个PGconn对象。函数PQconnectdb 和PQsetdbLogin总是返回一个非空的对象指针，除非整个内存都被耗尽，无法为PGconn对象分配存储空间。在向数据库发送SQL命令以前，可以用函数PQstatus检查是否成功地建立数据库连接。 PQconnectdb 建立一个新的数据库连接。         PGconn *PQconnectdb(const char *conninfo); 这个函数使用参数conninfo中的信息建立一个新的数据库连接。conninfo中含有一个或多个参数的值, 每个参数的值用keyword = value的形式表示，keyword表示参数的名字，value表示参数的值，也可以省略keyword 和value之间的等号，不同的值用空格隔开。如果参数的值中含有空格或者值为空，则应该用双引号引起来，例如，keyword = 'a value' 。如果参数的值中含有单引号或反斜杠，则前面必须再加上一个反斜杠，例如，/' 和//分别表示单引号和反斜杠。如果conninfo是一个空串，函数将会使用默认的参数连接数据库。 当前，conninfo支持下列参数： host 运行数据库的主机的名字。如果它以反斜杠开始，则表示客户端想通过Unix-domain socket与数据库通信，它表示存放Unix-domain socket文件的目录。 hostaddr 运行数据库的主机的IP地址。可以是IPv4和Ipv6。如果同时指定了参数host和hostaddr，参数host将被忽略。 port 数据库的端口。 dbname 数据库的名字。默认与用户名相同。 user 数据库用户的名字。默认与运行应用程序的操作系统用户相同。 password 数据库用户的密码。 connect_timeout 连接操作的最大的等待时间。如果超过了这个时间，连接仍然没有建立成功，则主动终止建立连接的操作。单位是秒，用十进制整数表示。0或不指定这个参数的值表示一值等待下去，直到连接建立成功。这个值应该不小于2秒钟。 sslmode 表示SSL的工作模式。一共有四种，分别是disable、allow、prefer和require，默认值是require。disable表示使用未加密的 SSL连接。allow先尝试使用非SSL连接，如果失败，再尝试使用SSL连接。prefer表示先尝试建立SSL连接，如果失败，再尝试建立非SSL连接。require只尝试建立SSL连接。sslmode对于使用Unix domain socket建立的连接没有没有任何作用，会被自动忽略。 PQfinish 关闭数据库连接，同时释放PGconn对象占有的内存。         void PQfinish(PGconn *conn); 即使建立数据库连接的操作执行失败，应用程序也应该调用PQfinish来释放PGconn对象使用的内存。PQfinish执行结束以后，不应该再使用指针PGconn。 PQreset 重置数据库连接。         void PQreset(PGconn *conn); 这个函数会关闭数据库连接，然后使用上次建立数据库连接的参数尝试重新建立数据库连接。在数据库连接丢失以后，可以用这个函数来重新建立数据库连接。       1.2 连接状态函数 本节的函数用来查询数据库连接的状态。 PQdb 返回连接的数据库的名字。 char *PQdb(const PGconn *conn); PQuser 返回建立连接的数据库用户名。 char *PQuser(const PGconn *conn); PQpass 返回建立连接的数据库用户的密码。 char *PQpass(const PGconn *conn); PQhost 返回数据库运行的主机名。 char *PQhost(const PGconn *conn); PQport 返回数据库监听的端口。 char *PQport(const PGconn *conn); PQstatus 返回连接的状态。 ConnStatusType PQstatus(const PGconn *conn); 它有两个取值，分别是CONNECTION_OK和CONNECTION_BAD。CONNECTION_OK表示连接正常。CONNECTION_BAD表示连接已中断，在这种情况下，可以调用PQreset重新建立连接。 PQtransactionStatus 返回指定的连接上正在执行的事务的状态。 PGTransactionStatusType PQtransactionStatus(const PGconn *conn); PQTRANS_IDLE 表示连接处于空闲状态，没有执行任何事务。PQTRANS_ACTIVE 表示连接处于一个事务中，而且该事务正在执行命令。 PQTRANS_INTRANS 表示处于一个事务中，但事务处于空闲状态。PQTRANS_INERROR 表示处于一个事务中，但这个事务遇到错误，处于空闲状态，等待用户发一个COMMIT或ROLLBACK命令来结束它。 PQTRANS_UNKNOWN表示数据库连接已被终止。只有在用户发送了一个查询给数据库，而且这个查询仍然还在执行的情况下，才会返回PQTRANS_ACTIVE。 PQparameterStatus 查询指定的连接上数据库参数的值。 const char *PQparameterStatus(const PGconn *conn, const char *paramName); 如果指定的参数不存在，返回NULL。 PQserverVersion 返回数据库的版本号。 int PQserverVersion(const PGconn *conn); 数据库版本号由三部分表示，分别是major、minor和revision编号，每个部分用两个十进制位表示。例如，对于8.1.5的数据库调用这个函数将返回80105，对于8.2的数据库调用这个函数将返回80200。如果连接以被终止，函数将返回0。 PQerrorMessage 返回指定的连接最近一次收到的数据库错误信息。 char *PQerrorMessage(const PGconn *conn); 不要释放该函数返回的字符串占有的内存空间，在相关的PGconn对象被释放时，错误消息占的存储空间会被自动释放。另外，系统会自动在错误消息的末尾加上一个换行符。 PQsocket 得到用来建立连接的socket的文件描述符（file descriptor）。合法的文件描述符必须大于或等于0。如果数据库连接没有被打开，函数将返回-1。 int PQsocket(const PGconn *conn); PQbackendPID 返回执行这个连接发出的所有SQL命令的数据库 backend进程的进程ID。 int PQbackendPID(const PGconn *conn); PQconnectionNeedsPassword 返回1表示需要提供数据库用户的密码才能建立数据库连接，但是没有提供密码。其它情况下，返回0. int PQconnectionNeedsPassword(const PGconn *conn); 在建立连接的操作失败以后，应该调用这个函数决定是否需要提供数据库用户的密码。 PQconnectionUsedPassword 该函数检测连接数据库时，提供的数据库用户密码是否被使用。返回1表示密码被使用。返回0表示密码没有被使用。 int PQconnectionUsedPassword(const PGconn *conn); PQgetssl 返回SSL类型的连接的SSL信息。如果不是SSL类型的连接，返回null。 SSL *PQgetssl(const PGconn *conn); SSL信息包括加密级别、服务器证书等。详细信息参考OpenSSL文档。     1.3 执行命令的函数    数据库连接成功地建立以后，可以用本节介绍的函数发送SQL命令给数据库执行。   1.3.1 主要的函数 PQexec 发送一个命令给数据库执行，然后等待命令执行结束。          PGresult *PQexec(PGconn *conn, const char *command);         如果返回值是一个空指针，表示遇到了错误，调用PQerrorMessage可以得到详细的错误信息。       可以在同一个命令字符串中包含多条SQL命令，不同的SQL命令用分号隔开。如果PQexec中的命令字符串含有多条命令，而且这些命令中没有BEGIN和COMMIT，这些命令将在同一个事务里面被执行,如果其中含有BEGIN和COMMIT，则这些命令将在多个事务中被执行。只要有一条命令执行失败，剩下的命令就会被停止执行，返回的PGresult中包含相应的错误信息。     PQexecParams 发送一个命令给数据库执行，然后等待命令执行结束。这个函数可以执行带参数的SQL命令。   PGresult *PQexecParams(PGconn *conn,                        const char *command,                        int nParams,                        const Oid *paramTypes,                        const char * const *paramValues,                        const int *paramLengths,                        const int *paramFormats,                        int resultFormat);   PQexecParams与PQexec类似，但它还具备其它的功能，包括SQL命令可以带有参数，指定查询结果用二进制或文本的格式表示。   该函数的参数如下: conn 数据库连接对象。   command 被执行的SQL命令。如果里面含有参数，用$1, $2,…，$n表示。   nParams 被执行的SQL命令中含有的参数的个数。它也是数组paramTypes[]、paramValues[]、paramLengths[]和paramFormats[]的长度，如果nParams的值是0，这些指针的值应该是NULL。   paramTypes[] 指定SQL命令中对应的参数的数据类型，用OID表示。如果paramTypes是一个空指针或者数组paramTypes的某个元素的值是0，数据库会自动推断对应的参数的数据类型。