libpq es la interfaz para los programadores de aplicaciones en C para PostgreSQL. libpq es un conjunto de rutinas de biblioteca que permiten a los programas cliente trasladar consultas al servidor de Postgres y recibir el resultado de esas consultas. libpq es tambi�n el mecanismo subyacente para muchas otras interfaces de aplicaciones de PostgreSQL, incluyendo libpq++ (C++), libpgtcl (Tcl), Perl, y ecpg. Algunos aspectos del comportamiento de libpq le resultar�n de importancia si quiere utilizar uno de estos paquetes.
Se incluyen tres programas cortos al final de esta secci�n para mostrarle como escribir programas que utilicen libpq. Hay varios ejemplos completos de aplicaciones con libpq en los siguientes directorios:
../src/test/regress ../src/test/examples ../src/bin/psql |
Los programas cliente que utilicen libpq deber�n incluir el fichero de cabeceras libpq-fe.h, y deber�n enlazarse con la biblioteca libpq.
Las siguientes rutinas le permitir�n realzar una conexi�n al servidor de Postgres. El programa de aplicaci�n puede tener abiertas varias conexiones a servidores al mismo tiempo. (Una raz�n para hacer esto es acceder a m�s de una base de datos). Cada conexi�n se representa por un objeto PGconn que se obtiene de PQconnectdb () o PQsetdbLogin (). N�tese que estas funciones siempre devolver�n un puntero a un objeto no nulo, a menos que se tenga demasiada poca memoria incluso para crear el objeto PGconn. Se deber�a llamar a la funci�n PQstatus para comprobar si la conexi�n se ha realizado con �xito antes de enviar consultas a traves del objeto de conexi�n.
PQconnectdb Realiza una nueva conexi�n al servidor de base de datos.
PGconn *PQconnectdb(const char *conninfo) |
Cada fijaci�n de un par�metro tiene la forma keyword = value. (Para escribir un valor nulo o un valor que contiene espaci�n, se emplear�n comillas simples, por ejemplo keyword = 'a value'. Las comillas simples dentro de un valor se escribir�n como \'. Los espacios alrededor del signo igual son opcionales). Los par�metros reconocidos actualmente son:
Nombre del ordenador al que conectarse. Si se da una cadena de longitud distinta de cero, se utiliza comunicaci�n TCP/IP. El uso de este par�metro supone una b�squeda del nombre del ordenador. Ver hostaddr.
Direcci�n IP del ordenador al que se debe conectar. Deber�a estar en el formato estandar de n�meros y puntos, como se usan en las funciones de BSD inet_aton y otras. Si se especifica una cadena de longitud distinta de cero, se emplea una comunicaci�n TCP/IP.
El uso de hostaddr en lugar de host permite a la aplicaci�n evitar la b�squeda del nombre de ordenador, lo que puede ser importante en aplicaciones que tienen una limitaci�n de tiempo. Sin embargo la autenticaci�n Kerberos necesita el nombre del ordenador. En este caso de aplica la siguiente secuencia. Si se especifica host sin hostaddr, se fuerza la b�squeda del nombre del ordenador. Si se especifica hostaddr sin host, el valor de hostaddr dar� la direcci�n remota; si se emplea Kerberos, se buscar� de modo inverso el nombre del ordenador. Si se dan tanto host como hostaddr, el valor de hostaddr dar� la direcci�n remota; el valor de host se ignorar�, a menos que se emplee Kerberos, en cuyo caso ese valor se utilizar� para la autenticaci�n Kerberos. N�tese que libpq fallar� si se pasa un nombre de ordenador que no sea el nombre de la m�quina en hostaddr.
Cuando no se empleen ni uno ni otro, libpq conectar� utilizando un socket de dominio local.
N�mero del puerto para la conexi�n en el ordenador servidor, o extensi�n del nombre de fichero del socket para conexi�n de dominio Unix.
Nombre de la base de datos.
Nombre del usuario que se debe conectar.
Password que se deber� utilizar si el servidor solicita una autenticaci�n con password.
Se pueden enviar las opciones Trace/debug al servidor.
Un fichero o tty para la salida de la depuraci�n opcional desde el servidor.
Esta funci�n no salva hebra.
PQsetdbLogin Realiza una nueva conexi�n al servidor de base de datos.
PGconn *PQsetdbLogin(const char *pghost, const char *pgport, const char *pgoptions, const char *pgtty, const char *dbName, const char *login, const char *pwd) |
Esta funci�n no salva hebra.
PQsetdb Realiza una nueva conexi�n al servidor de base de datos.
PGconn *PQsetdb(char *pghost, char *pgport, char *pgoptions, char *pgtty, char *dbName) |
PQconnectStart PQconnectPoll Realizan una conexi�n al servidor de base de datos de forma no bloqueante.
PGconn *PQconnectStart(const char *conninfo) |
PostgresPollingStatusType *PQconnectPoll(PQconn *conn) |
La conexi�n a la base de datos se realiza utilizando lo par�metros dados en la cadena conninfo, que se pasa a PQconnectStart. Esta cadena est� en el mismo formato que se describi� antes para PQconnectdb.
Ni PQconnectStart ni PQconnectPoll bloquear�n, aunque se exigen un cierto n�mero de restricci�nes:
Los par�metros hostaddr y host se utilizan apropiadamente para asegurar que no se realizan consultas de nombre ni de nombre inverso. Vea la documentaci�n de estos par�metros bajo PQconnectdb antes para obtener m�s detalles.
Si llama a PQtrace, asegurese de que el objeto de la secuencia en la cual realiza usted un rastreo no bloquea.
Asegurese usted mismo de que el socket se encuentra en el estado apropiado antes de llamar a PQconnetPoll, como se describe m�s abajo.
Para empezar, llame conn=PQconnectStart("<connection_info_string>"). Si conn es NULL, libpq habr� sido incapaz de crear una nueva estructura PGconn. De otro modo, se devolver� un puntero PGconn valido (aunque todav�a no represente una conexi�n v�lida a la base de datos). Al regreso de PQconnectStart, llame a status=PQstatus(conn). Si status es igual a CONNECTION_BAD, PQconnectStart habr� fallado.
Si PQconnectStart funciona con �xito, el siguiente paso es comprobar libpq de forma que pueda proceder con la secuencia de conexi�n. Realice un bucle como sigue: Considere que por defecto una conexi�n se encuentra 'inactiva'. Si el �ltimo PQconnectPoll devolvi� PGRES_POLLING_ACTIVE, considere ahora que la conexi�n est� 'activa'. Si el �ltimo PQconnectPoll(conn) devolvi� PGRES_POLLING_READING, realice una select para leer en PQsocket(conn). Si devolvi� PGRES_POLLING_WRITING, realice una select para escribir en PQsocket(conn). Si todav�a tiene que llamar a PQconnectPoll, es decir, tras llamar a PQconnectStart, comportese como si hubiera devuelto PGRES_POLLING_WRITING. Si la select muestra que el socket est� preparado (ready), considerelo 'activo'. Si ya ha decido que el esta conexi�n est� 'activa', llame de nuevo a PQconnectPoll(conn). Si esta llamada devuelve PGRES_POLLING_OK, la conexi�n se habr� establecido con �xito.
N�tese que el uso de select() para asegurar que el socket se encuentra listo es realmente un ejemplo; aquellos que dispongan de otras facilidades disponibles, como una llamada poll(), por supuesto pueden utilizarla en su lugar.
En cualquier momento durante la conexi�n, se puede comprobar la situaci�n de esta conexi�n, llamando a PQstatus. Si el resultado es CONNECTION_BAD, el procedimiento de conexi�n habr� fallado; si es CONNECTION_OK, la conexi�n est� funcionando correctamente. Cualquiera de estas situaciones se puede detectar del mismo modo a partir del valor de retorno de PQconnectPoll, como �ntes. Otras situaciones se pueden mostrar durante (y s�lo durante) un procedimiento de conexi�n as�ncrona. Estos indican la situaci�n actual del procedimiento de conexi�n, y se pueden utilizar para proporcionar informaci�n de retorno al usuario, por ejemplo. Estas situaciones pueden incluir:
CONNECTION_STARTED: Esperando que se realice una conexi�n.
CONNECTION_MADE: Conexi�n OK; esperando para enviar.
CONNECTION_AWAITING_RESPONSE: Esperando una respuesta del postmaster.
CONNECTION_AUTH_OK: Recibida autenticaci�n, espera que arranque del servidor.
CONNECTION_SETENV: Negociando el entorno.
switch(PQstatus(conn)) { case CONNECTION_STARTED: feedback = "Connecting..."; break; case CONNECTION_MADE: feedback = "Connected to server..."; break; . . . default: feedback = "Connecting..."; } |
N�tese que si PQconnectStart devuelve un puntero no nulo, deber� usted llamar a PQfinish cuando haya terminado con �l, para disponer de la estructura y de cualquier bloque de memoria asociado. Se debe hacer esto incluso si ha fallado una llamada a PQconnectStart o a PQconnectPoll.
PQconnectPoll actualmente bloquear� si libpq se compila con USE_SSL definido. Esta restricci�n se eliminar� en el futuro.
PQconnectPoll actualmente bloquear� bajo Windows, a menos que libpq se compile con WIN32_NON_BLOCKING_CONNECTIONS definida. Este c�digo no se ha probado a�n bajo Windows, de forma que actualmente se encuentra desactivado por defecto. Esto podr�a cambiar en el futuro.
Estas funciones dejar�n el socket en un estado de no-bloqueo como si se hubiese llamado a PQsetnonblocking.
Estas funciones no aseguran la hebra.
PQconndefaults Devuelve la opciones de conexi�n de defecto.
PQconninfoOption *PQconndefaults(void) struct PQconninfoOption { char *keyword; /* Palabra clave de la opci�n */ char *envvar; /* Nombre de la variable de entorno que recoge su valor si no se da expresamente */ char *compiled; /* Valor de defecto en el c�digo fuente si tampoco se asigna variable de entorno */ char *val; /* Valor de la opci�n */ char *label; /* Etiqueta para el campo en el di�logo de conexi�n */ char *dispchar; /* Car�cter a mostrar para este campo en un di�logo de conexi�n. Los valores son: "" Muestra el valor entrado tal cual es "*" Campo de Password - ocultar el valor "D" Opciones de depuraci�n - No crea un campo por defecto */ int dispsize; /* Tama�o del campo en car�cteres para dialogo */ } |
Esta funci�n no salva hebra.
PQfinish Cierra la conexi�n con el servidor. Tambi�n libera la memoria utilizada por el objeto PGconn.
void PQfinish(PGconn *conn) |
PQreset Inicializa el puerto de comunicaci�n con el servidor.
void PQreset(PGconn *conn) |
PQresetStart PQresetPoll Limpian el puerto de comunicaci�n con el servidor de forma no bloqueante.
int PQresetStart(PGconn *conn); |
PostgresPollingStatusType PQresetPoll(PGconn *conn); |
Ejecute PQresetStart. Si devuelve 0, la limpieza ha fallado. Si devuelve 1, pruebe la limpieza utilizando PQresetPoll exactamente en la misma forma en que habr�a creado la conexi�n utilizando PQconnectPoll.
Los programadores de aplicaciones con libpq deber�an ser cuidadosos de mantener la abstracci�n de PGconn. Utilice las funciones siguientes para tomar el contenido de PGconn. Prohiba las referencias directas a los campos de la estructura PGconn, ya que est�n sujetas a cambios en el futuro. (A partir de PostgreSQL 6.4, la definici�n de la estructura PGconn incluso ya no se proporciona en libpq-fe.h. Si tiene usted viejas aplicaciones que acceden a campos de PGconn directamente, puede usted conservarlas utilizando para incluirla libpq-int.h tambi�n, pero le recomendamos encarecidamente que fije pronto el c�digo).
PQdb Devuelve el nombre de la base de datos de la conexi�n.
char *PQdb(const PGconn *conn) |
PQuser Devuelve el nombre de usuario de la conexi�n.
char *PQuser(const PGconn *conn) |
PQpass Devuelve la palabra de paso de la conexi�n.
char *PQpass(const PGconn *conn) |
PQhost Devuelve el nombre del ordenador de servidor de la conexi�n.
char *PQhost(const PGconn *conn) |
PQport Devuelve el puerto de la conexi�n.
char *PQport(const PGconn *conn) |
PQtty Devuelve el terminal tty de depuraci�n de la conexi�n.
char *PQtty(const PGconn *conn) |
PQoptions Devuelve las opciones de servidor utilizadas en la conexi�n.
char *PQoptions(const PGconn *conn) |
PQstatus Devuelve la situaci�n (status) de la conexi�n.
ConnStatusType PQstatus(const PGconn *conn) |
La situaci�n puede tomar varios valores diferentes. Sin embargo, s�lo dos de ellos tienen significado fuera de un procedimiento de conexi�n as�ncrona: CONNECTION_OK o CONNECTION_BAD. Una buena conexi�n a la base de datos tiene es status CONNECTION_OK. Una conexi�n fallida se se�ala con la situaci�n CONNECTION_BAD. Normalmente, una situaci�n de OK se mantendr� hasta PQfinish, pero un fallo de las comunicaciones puede probocar un cambio prematuro de la situaci�n a CONNECTION_BAD. En ese caso, la aplicaci�n podr�a intentar recuperar la comunicaci�n llamando a PQreset.
Para averiguar otras posibles situaci�nes que podr�an comprobarse, revise las entradas de PQconnectStart y PQconnectPoll.
PQerrorMessage Devuelve el mensaje de error m�s reciente que haya generado alguna operaci�n en la conexi�n.
char *PQerrorMessage(const PGconn* conn); |
Casi todas las funciones de libpq fijar�n el valor de PQerrorMessage si fallan. Tenga en cuenta que por convenci�n de libpq, un PQerrorMessage no vac�o incluir� un car�cter "nueva l�nea" final.
PQbackendPID Devuelve el identificador (ID) del proceso del servidor que est� controland esta conexi�n.
int PQbackendPID(const PGconn *conn); |
PQsetenvStart PQsetenvPoll PQsetenvAbort Realizan una negocaci�n del ambiente.
PGsetenvHandle *PQsetenvStart(PGconn *conn) |
PostgresPollingStatusType *PQsetenvPoll(PGsetenvHandle handle) |
void PQsetenvAbort(PGsetenvHandle handle) |
Estas funciones no bloquean, sujeto a las restricciones aplicadas a PQconnectStart y PQconnectPoll.
Para empezar, llame a handle=PQsetenvStart(conn), donde conn es una conexi�n abierta con el servidor de la base de datos. Si handle es NULL, libpq habr� sido incapaz de situar una nueva estructura PGsetenvHandle. En otro vaso, se devuelve una estructura handle valida. (N. del T: Dejo la palabra handle como identificador de una estructura de datos la aplicaci�n, aunque evidentemente el usuario podr� utilizar el nombre que desee. Conociendo los programas que yo programo, normalmente usar�a un nombre como con_servidor, por ejemplo). Este handle se piensa que sea opaco: s�lo debe utilizarlo para llamar a otras funciones de libpq (PQsetenvPoll, por ejemplo).
Elija el procecimiento utilizando PQsetenvPoll, exactamente del mismo modo en que hubiese creado la conexi�n utilizando PQconnectPoll.
El procedimiento se puede abortar en cualquier momento llamando a PQsetevnAbort (handle).
Estas funciones no aseguran la hebra.
PQsetenv Realiza una negociaci�n del entorno.
int PQsetenv(PGconn *conn) |