Chapter 27. libpq - C ��

Table of Contents
27.1. ���ݿ����Ӻ���
27.2. ����״̬����
27.3. ����ִ�к���
27.3.1. ������
27.3.2. ������ѯ�����Ϣ
27.3.3. ������������Ľ����Ϣ
27.3.4. ���ݰ����� SQL �����е��ִ�
27.3.5. ���ݰ����� SQL �����еĶ������ִ�
27.4. �첽�����
27.5. ȡ�����ڴ���IJ�ѯ
27.6. �ݾ��ӿ�
27.7. �첽֪ͨ
27.8. ��COPY������صĺ���
27.8.1. ���ڷ��� COPY ���ݵĺ���
27.8.2. ���ڽ��� COPY ���ݵĺ���
27.8.3. ���� COPY �ķ����ĺ���
27.9. ���ƺ���
27.10. ע����Ϣ����
27.11. ��������
27.12. �����ļ�
27.13. SSL ֧��
27.14. �ڶ��̳߳��������Ϊ
27.15. ���� libpq ����
27.16. ���ӳ���

libpq ��PostgreSQL�� C Ӧ�ó���ӿڡ� libpq ��һ������ͻ������� PostgreSQL ������������̷��Ͳ�ѯ���һ�ò�ѯ���صĿ⺯����

libpq ͬʱҲ���������� PostgreSQL Ӧ�ýӿ���������棬 ���� C++��Perl��Python��Tcl �� ECPG�� ���������ʹ����Щ�������libpqijЩ��������Ի����dz���Ҫ�� �ر��� Section 27.11�� Section 27.12 �� Section 27.13 �������κ�ʹ�� libpq ��Ӧ�õ��û��ɼ�����Ϊ��

����ĩβ������С������ʾ������� libpq ��д���� ��Section 27.16����Դ���뷢���� src/test/examples Ŀ¼�����м��������� libpq Ӧ�õ����ӡ�

ʹ�� libpq ��ǰ�˳���������ͷ�ļ� libpq-fe.h ���ұ����� libpq �����ӡ�

27.1. ���ݿ����Ӻ���

����ĺ��������� PostgreSQL ���������������ӵ����顣 һ��Ӧ�ó���һ�ο��������������������ӡ�����ô����ԭ��֮һ�Ƿ��ʶ���һ�����ݿ⡣�� ÿ�����Ӷ�����һ���Ӻ���PQconnectdb()�� PQsetdbLogin() ��õ� PGconn �����ʾ�� ע�⣬��Щ�������Ƿ���һ���ǿյĶ���ָ�룬���Ǵ洢���ٵ�����PGconn���󶼷��䲻������ �ڰѲ�ѯ���͸����Ӷ���֮ǰ�����Ե���PQstatus���������һ�������Ƿ�ɹ���

PQconnectdb

����������ݿ����������һ���µ����ӡ�

PGconn *PQconnectdb(const char *conninfo);

��������ô�һ���ַ��� conninfo���IJ��������ݿ��һ���µ����ӡ� �������PQsetdbLogin()��ͬ���ǣ� ���ǿ��Բ��ظ�������ǩ�������֣��Ϳ�����չ�������� �������ǽ���Ӧ�ó�����ʹ������������������������Ƶķ������ı��� PQconnectStart �� PQconnectPoll����

����IJ�������Ϊ�գ�����ʹ������ȱʡ�IJ����� ���߿��԰���һ���������ÿհ׼���IJ������á� ÿ�������� �ؼ��� = ��ֵ����ʽ���á� �Ⱥ���Χ�Ŀհ��ǿ�ѡ�ġ� Ҫдһ����ֵ����һ�������հ׵�ֵ���������һ�Ե����Ű�Χ���ǣ����磬 keyword = 'a value' ����ֵ�ڲ��ĵ����źͷ�б�ܱ�����һ����б�����ݣ� ���磬 \'��\\��

Ŀǰ��ʶ��IJ��������ǣ�

host

Ҫ���ӵ��������� �����������б�ܿ�ͷ����������ʹ�� Unix ���׽���ͨѶ������ TCP/IP ͨѶ�� ��ֵ�����׽����ļ����洢��Ŀ¼�� ���û������ host����ôȱʡʱ����λ�� /tmp Ŀ¼���������� PostgreSQL ��ʱ���������׽���Ŀ¼�� ����� Unix-���׽������ӡ� ��û�� Unix ���׽��ֵĻ����ϣ�ȱʡ���� localhost ���ӡ�

hostaddr

��֮���ӵ������� IP ��ַ�����Ӧ���DZ�׼��IPv4 ��ַ��ʽ�� ���磬172.28.40.9�������Ļ���֧�� IPv6�� ��ô��Ҳ����ʹ�� IPv6 �ĵ�ַ�����������һ���ǿյ��ַ�������ôʹ�� TCP/IP ͨѶ���ơ�

ʹ��hostaddrȡ��host������Ӧ�ñ���һ�����������ң� ��һ�������Щ��ʱ��Լ����Ӧ����˵�����Ƿdz���Ҫ�ġ� ������Kerberos ��֤ϵͳҪ��������host��������ˣ�Ӧ������Ĺ��� ��������˲���hostaddr��host��ô��ǿ�ƽ������������ҡ� ���������û��host��hostaddr ��ֵ����Զ�˵ĵ�ַ�� ���ʹ���� Kerberos��������һ�η������ֲ�ѯ�����ͬʱ������ host ��hostaddr�� ����ʹ���� Kerberos������ʹ��hostaddr��ֵ��ΪԶ�˵�ַ�� host ��ֵ�������ԣ����ʹ���� Kerberos��host ��ֵ���� Kerberos ��֤�� ��Ҫע��������ݸ�libpq����������host�� ���ǵ�ַhostaddr���Ļ���������ô��֤���п���ʧ�ܡ��� ͬ������ ~/.pgpass������ Section 27.12�� ����ʹ�� host ������ hostaddr ����ʶ���ӡ�

�����������host����������ַ��û�У� ��ôlibpq��ʹ��һ�����ص� Unix ���׽��ֽ���ͨѶ�� ��������û�� Unix ���׽��ֵĻ����ϣ����������� localhost ���ӡ�

port

�����������Ķ˿ںţ������� Unix ���׽�������ʱ���׽�����չ�ļ�����

dbname

���ݿ�����ȱʡ���û�����ͬ��

user

Ҫ���ӵ� PostgreSQL �û����� ȱʡ�������и�Ӧ�õ��û�����ϵͳ��ͬ�����û���

password

���������Ҫ�������֤�����õĿ��

connect_timeout

���ӵ����ȴ�ʱ�䣬����ƣ���ʮ���������ִ���д���� ����߲�������ʾ������Dz���������ӳ�ʱ��ֵ���õ�С�� 2 �롣

options

���͸���������������ѡ�

tty

���ԣ���ǰ�����ѡ��������������־��������򣩡�

sslmode

���ѡ������Ƿ���Ҫ�ͷ�����Э��һ�� SSL ���ӣ� �Լ���ʲô�������ȼ������������ SSL ���ӡ� ������ģʽ�ɹ�ѡ��disable ��ֻ����һ��û�м��ܵķ� SSL ���ӣ� allow ���ͷ���������Э�̣����ȳ���һ���� SSL ���ӣ� ���ʧ�ܣ�����һ�� SSL ���ӣ�prefer ��ȱʡ�� ������Э�̣� ���ȳ��� SSL ���ӣ����ʧ�ܣ�����һ�������ķ� SSL ���ӣ� require ��ֻ���� SSL ���ӡ�

��� PostgreSQL ����ʱû�д� SSL ֧�֣���ôʹ�� require ������һ������ �� libpq ������ allow �� prefer��������ʵ���ϲ�����ͼ���� SSL ���ӡ�

requiressl

���ѡ����Ϊ���� sslmode ����֮���Ѿ������ˡ�

�����Ϊ 1 ����Ҫ�������������SSL���ӣ���Ч�� sslmode require���� �����������֧��SSL����ôlibpq�����Ͼܾ����ӡ� ����Ϊ 0 ��ȱʡ�������������Э���������ͣ���Ч�� sslmode prefer���� ���ѡ��ֻ���ڱ��� PostgreSQL ʱ���� SSL ֧�ֲ���Ч��

service

���ڶ�������ķ�����������pg_service.conf��������һ���������� ��������ļ������������Ӳ���������������Ӧ��Ӧ��ֻ����һ���������� �����Ӳ����Ϳ�����һ���ط�ά���ˡ����İ�װĿ¼�е� share/pg_service.conf.sample ��ȡ�����������ļ�����Ϣ��

������κ�û�������IJ�������ô������Ӧ�Ļ�������������Section 27.11 С�ڣ��� �����������Ҳû�����ã���ôʹ�ñ���ʱ��ָ��������ȱʡ��

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 ǰ�� ���й̶������IJ�����������ͬ�Ĺ��ܣ�ֻ���ڵ�������Щ��ȱ�ٵIJ���������ȱʡֵ�� ���ô������Ĺ̶���������ȱʡֵ����ôдһ�� NULL ����һ�����ִ������ǡ�

PQsetdb

����������ݿ����������һ���µ����ӡ�

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

����һ������ PQsetdbLogin() �ĺֻ꣬��login��pwd�����ÿգ�null �����档 �ṩ���������Ϊ����dz��ϰ汾�ij�����ݡ�

PQconnectStart
PQconnectPoll

�����ݿ����������һ�η����������ӡ�

PGconn *PQconnectStart(const char *conninfo);

PostgreSQLPollingStatusType PQconnectPoll(PGconn *conn);

�������������ڴ�һ�������ݿ������֮��ķ����������ӣ� ���Ӧ�õ�ִ��������ִ������ʱ�򲻻���Զ�˵� I/O �������� ���������Ҫ���ǵȴ� I/O �������Է�����Ӧ�õ���ѭ��� �������� PQconnectdb �����Ӧ�ÿ��԰������������������������һ��ִ�С�

���ݿ��������ô� conninfo �ַ�����ȡ�õIJ������ݸ� PQconnectStart ���еġ� ����ַ����ĸ�ʽ������PQconnectdb��������һ����

PQconnectStart ��PQconnectPoll ���������������̣���������һЩ������

  • ������ȷ�ṩhostaddr��host ������ȷ�����ᷢ��������߷�������ֲ��ҡ� ��������PQconnectdb�����Щ�������ĵ���ȡϸ�ڡ�

  • ����������PQtrace�� ȷ������ٽ���������󲻻�������

  • ������ڵ���PQconnectPoll֮ǰȷ�� socket ������ȷ��״̬��������������������

Ҫ��ʼһ�η������������󣬵��� 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

���ӳɹ����ȴ����͡�

CONNECTION_AWAITING_RESPONSE

�ȴ����Է���������Ӧ��

CONNECTION_AUTH_OK

���յ���֤���ȴ����������������С�

CONNECTION_SSL_STARTUP

Э�� SSL ���ܡ�

CONNECTION_SETENV

Э�̻��������IJ������á�

ע�⣬������Щ������������ȥ��Ϊ��ά�ּ����ԣ��� Ӧ�þ���Ӧ����������Щ������ij���ض�˳����֣� �����Ǹ�����Ӧ��������Щ������ �����Dz�Ӧ����������Щ״̬����ij���ĵ�������ֵ�� һ��Ӧ�ÿ�����������������

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

    case CONNECTION_MADE:
	feedback = "������������ѽ���...";
	break;
.
.
.
    default:
	feedback = "��������...";
}

��ʹ�� PQconnectPoll ��ʱ�����Ӳ��� connect_timeout �������ԣ��ж��Ƿ�ʱ��Ӧ�õ����Ρ����򣬺������һ�� PQconnectPoll ѭ���� PQconnectStart ��Ч�� PQconnectdb��

Ҫע�����PQconnectStart����һ���ǿյ�ָ�룬 �������ʹ��������ָ�룩֮�����PQfinish�� �Դ�����Щ�ṹ��������صĴ洢�顣 ��������PQconnectStart���� PQconnectPollʧ��ʱҲҪ��������

PQconndefaults

����ȱʡ������ѡ�

PQconninfoOption *PQconndefaults(void);

typedef struct PQconninfoOption
{
    char   *keyword;   /* ѡ��ļ��� */
    char   *envvar;    /* ���صĻ��������� */
    char   *compiled;  /* ���صı���ʱȱʡֵ */
    char   *val;       /* ѡ��ĵ�ǰֵ������ NULL */
    char   *label;     /* ���ӶԻ����ֶεı�ʶ */
    char   *dispchar;  /* �����ӶԻ���Ϊ���ֶ���ʾ���ַ���
			  ��ֵ�У�
			  ""	ԭ����ʵ�������ֵ
			  "*"   �����ֶ� �� ������ֵ
			  "D"   ����ѡ�� �� ȱʡ��ʱ����ʾ */
    int     dispsize;  /* �Ի����ֶε����ַ��ƵĴ�С */
}PQconninfoOption;

����һ������ѡ�����顣 �������ڻ�ȡ���п��ܵ�PQconnectdbѡ������ǵĵ�ǰȱʡֵ�� ����ֵָ��һ��PQconninfoOption �ṹ�����飬 ��������һ���� NULL keyword ָ�����Ŀ������ע��ȱʡֵ��val �򣩽������ڻ������������������� �����߱��������ѡ���ֻ���Դ���

�ڴ�����ѡ������󣬰����齻��PQconninfoFree()�ͷš� ���û����ô����ÿ�ε���PQconndefaults()������һС�����ڴ�й©��

PQfinish

�ر�������������ӡ�ͬʱ�ͷű�PGconn ����ʹ�õĴ洢����

void PQfinish(PGconn *conn);

ע�⣬��ʹ������������ӳ���ʧ�ܣ�����PQstatus�жϣ��� Ӧ��ҲҪ����PQfinish�ͷű�PGconn����ʹ�õĴ洢���� ��Ӧ���ڵ���PQfinish����ʹ��PGconn ָ�롣

PQreset

�������������ͨѶ�˿ڡ�

void PQreset(PGconn *conn);

�˺������ر�������������Ӳ�����ͼ��ͬһ���������ؽ��µ����ӣ� ʹ������ǰ��ʹ�ù��IJ���������ʧȥ�������Ӻ���й��ϻָ�ʱ�����á�

PQresetStart
PQresetPoll

�Է�����ģʽ�������������ͨѶ�˿ڡ�

int PQresetStart(PGconn *conn);

PostgreSQLPollingStatusType PQresetPoll(PGconn *conn);

�˺������ر�������������Ӳ�����ͼ��ͬһ���������ؽ��µ����ӣ� ʹ������ǰ��ʹ�ù��IJ���������ʧȥ�������Ӻ���й��ϻָ�ʱ�����á� ���Ǻ������PQreset�����������ǹ����ڷ�����ģʽ�� ��Щ������ʹ����������PQconnectStart�� PQconnectPollһ�������ơ�

Ҫ����һ���������ã�����PQresetStart����������� 0����ô����ʧ�ܡ� ������� 1������ʹ��PQconnectPoll �������ӵ�ͬ���ķ���ʹ��PQresetPoll�������ӡ�