../src/test/regress
../src/test/examples
../src/bin/psql
   

Funciones de Conexión a la Base de Datos

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)

  Esta rutina abre una conexión a una base de datos utilizando los parámetros que se dan en la cadena conninfo. Contra lo que ocurre más abajo con PQsetdbLogin(), los parámetros fijados se pueden extender sin cambiar la firma de la función, de modo que el uso de bien esta rutina o bien las análogas sin bloqueo PQconnetStart / PQconnectPoll resulta preferible para la programación de las aplicaciones. La cadena pasada puede estar varía para utilizar así los parámetros de defecto, o puede contener uno o más parámetros separados por espacios.

  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:

  host

  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.

  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.

  port

  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.

  dbname

  Nombre de la base de datos.

  user

  Nombre del usuario que se debe conectar.

  password

  Password que se deberá utilizar si el servidor solicita una autenticación con password.

  options

  Se pueden enviar las opciones Trace/debug al servidor.

  tty

  Un fichero o tty para la salida de la depuración opcional desde el servidor.

  Si no se especifica ningún parámetro, se comprobarán las correspondiente variables de entorno. Si no se encuentran fijadas, se emplean los valores de defecto codificadas en el programa. El valor devuelto es un puntero a una estructura abstracta que representa la conexión al 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 es la predecesora de PQconnectdb, con un número fijado de parámetros, pero con la misma funcionalidad.

  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)

  Esta es una función que llama a PQsetdbLogin() con punteros nulos para los parámetros login y pwd. Se proporciona inicialmente para mantener compatibilidad con programas antigüos.

• 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)

  Estas dos rutinas se utilizan para abrir una conexión al servidor de base de datos tal que la hebra de ejecución de la aplicación no queda bloqueada en el I/O remoto mientras lo hace.

  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.

  Téngase en cuenta que, aunque estas constantes se conservarán (para mantener la compatibilidad), una aplicación nunca debería basarse en la aparición de las mismas en un orden particual, o en todos, o en que las situaciones siempre tengan un valor de estos documentados. Una aplicación podría hacer algo así:

  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 */ }

  Devuelve la dirección de la estructura de opciones de conexión. Esta se puede utilizar para determinar todas las opciones posibles de PQconnectdb y sus valores de defecto actuales. El valor de retorno apunta a una matriz de estructuras PQconninfoOption, que termina con una entrada que tiene un puntero a NULL. Note que los valores de defecto (los campos "val") dependerán de las variables de entorno y del resto del contexto. Cuando se le llame, se deben tratar los datos de las opciones de conexión como de sólo lectura.

  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)

  Téngase en cuenta que incluso si falló el intento de conexión con el servidor (como se indicaba en PQstatus), la aplicación deberá llamar a PQfinish para liberar la memoria utilizada por el objeto PGconn. No se debería utilizar el puntero PGconn una vez que se ha llamado a PQfinish.

• PQreset Inicializa el puerto de comunicación con el servidor.

  void PQreset(PGconn *conn)

  Esta función cerrará la conexión con el servidor e intentará establecer una nueva conexión al mismo postmaster, utilizando todos los mismos parámetros anteriores. Se puede utilizar para recuperar un error si una conexión que estaba trabajando se pierde.

• PQresetStart PQresetPoll Limpian el puerto de comunicación con el servidor de forma no bloqueante.

  int PQresetStart(PGconn *conn);

  PostgresPollingStatusType PQresetPoll(PGconn *conn);

  Estas funciones cerrarán la conexión al servidor e intentarán reestablecer una nueva conexión con el mismo postmaster, utilizando los mismos parámetros previamente utilizados. Esto puede ser utilizable para recuperaciones de errores si se pierde una conexión que estaba trabajando. Difieren de del anterior PQreset en que lo hacen de una forma no bloqueante. Estas funciones sufren las mismas restricciones que PQconnectStart y PQconnectPoll.

  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)

  PQdb y las siguientes funciones devuelven los valores establecidos en la conexión. Estos valores se fijan para toda la vida de PGconn. object.

• 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);

  El PID del servidor es utilizable si se quiere hacer depuración de errores y para comparar los mensajes de NOTIFY (que incluyen el PID del servidor que está realizando la notificación). Tenga en cuenta que el PID corresponde a un proceso que se está ejecutando en el ordenador servidor de la base de datos, ¡no en el ordenador local!

• PQsetenvStart PQsetenvPoll PQsetenvAbort Realizan una negocación del ambiente.

  PGsetenvHandle *PQsetenvStart(PGconn *conn)

  PostgresPollingStatusType *PQsetenvPoll(PGsetenvHandle handle)

  void PQsetenvAbort(PGsetenvHandle handle)

  Estas dos rutinas se pueden utilizar para re-ejecutar la negociación del entorno que ocurre durante la apertura de una conexión al servidor de la base de datos. No tengo idea de para qué se puede aprovechar esto (¿la tiene alguien?), pero quizá resulte interesante para los usuarios poder reconfigurar su codificación de carácteres en caliente, por ejemplo.

  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)

  Esta función realiza las mismas tareas que PQsetenvStart y PQsetenvPoll, pero bloquea para hacerlo. Devuelve 1 en caso de éxito, y 0 en caso de fracaso.