LXXXVII. Funciones PostgreSQL

Introducción

La base de datos PostrgeSQL es un producto Open Source y disponible sin costo. Postgres, desarrollado originalmente en el Deportamento de Ciencias de Computación de UC Berkeley, fue pionero en muchos de los conceptos de objetos y relacionales que ahora están apareciendo en algunas bases de datos comerciales. Provee soporte para lenguajes SQL92/SQL99, transacciones, integridad referencial, procedimientos almacenados y extensibilidad de tipos. PostgreSQL es un descendiente de código abierto de su código original de Berkeley.

Requirimientos

Para hacer uso del soporte PostgreSQL, necesita PostgreSQL 6.5 o posterior, PostgreSQL 7.0 o posterior para habilitar todas las características del módulo. PostgreSQL soporta varias codificaciones de caracteres, incluyendo codificación de caracteres multibyte. Su versión actual, asi como más información sobre PostgreSQL se encuentra disponible en http://www.postgresql.org/ y http://techdocs.postgresql.org/.

Instalación

In order to enable PostgreSQL support, --with-pgsql[=DIR] is required when you compile PHP. DIR is the PostgreSQL base install directory, defaults to /usr/local/pgsql. If shared object module is available, PostgreSQL module may be loaded using extension directive in php.ini or dl() function.

Configuración en tiempo de ejecución

El comportamiento de estas funciones está afectado por los valores definidos en php.ini.

Tabla 1. PostgreSQL configuration options

NameDefaultChangeable
pgsql.allow_persistent"1"PHP_INI_SYSTEM
pgsql.max_persistent"-1"PHP_INI_SYSTEM
pgsql.max_links"-1"PHP_INI_SYSTEM
pgsql.auto_reset_persistent"0"PHP_INI_SYSTEM
pgsql.ignore_notice"0"PHP_INI_ALL
pgsql.log_notice"0"PHP_INI_ALL
For further details and definition of the PHP_INI_* constants see ini_set().

A continuación se presenta una corta explicación de las directivas de configuración.

pgsql.allow_persistent boolean

Whether to allow persistent Postgres connections.

pgsql.max_persistent integer

The maximum number of persistent Postgres connections per process.

pgsql.max_links integer

The maximum number of Postgres connections per process, including persistent connections.

pgsql.auto_reset_persistent integer

Detect broken persistent links with pg_pconnect(). Needs a little overhead.

pgsql.ignore_notice integer

Whether or not to ignore PostgreSQL backend notices.

pgsql.log_notice integer

Whether or not to log PostgreSQL backends notice messages. The PHP directive pgsql.ignore_notice must be off in order to log notice messages.

Modo de uso y consejos

Aviso

El uso del módulo PostgreSQL con PHP 4.0.6 no se recomienda debido a un fallo en el código de gestión de mensajes tipo noticia. Use la versión 4.1.0 o posterior.

Aviso

Los nombres de funciones PostgreSQL serán modificados en el lanzamiento 4.2.0 para adoptar los estándares de código actuales. La mayoría de nombres nuevos tendrán signos de subrayado adicionales, p.ej. pg_lo_open(). Algunas funciones son renombradas a nuevos nombres por razones de consistencia, p.ej. pg_exec() a pg_query(). Los nombres antiguos pueden ser usados en 4.2.0 y algunas versiones subsiguientes, pero pueden ser eliminados en el futuro.

Tabla 2. Nombres de función modificados

Nombre antiguoNombre nuevo
pg_cmdtuples()pg_affected_rows()
pg_errormessage()pg_last_error()
pg_exec()pg_query()
pg_fieldname()pg_field_name()
pg_fieldsize()pg_field_size()
pg_fieldnum()pg_field_num()
pg_fieldprtlen()pg_field_prtlen()
pg_fieldisnull()pg_field_is_null()
pg_freeresult()pg_free_result()
pg_getlastoid()pg_last_oid()
pg_loreadall()pg_lo_read_all()
pg_locreate()pg_lo_create()
pg_lounlink()pg_lo_unlink()
pg_loopen()pg_lo_open()
pg_loclose()pg_lo_close()
pg_loread()pg_lo_read()
pg_lowrite()pg_lo_write()
pg_loimport()pg_lo_import()
pg_loexport()pg_lo_export()
pg_numrows()pg_num_rows()
pg_numfields()pg_num_fields()
pg_result()pg_fetch_result()

La vieja sintaxis pg_connect()/pg_pconnect() será marcada como obsoleta para dar soporte a conexiones asincrónicas en el futuro. Por favor use una cadena de conexión para pg_connect() y pg_pconnect().

No todas las funciones son soportadas en todas las instalaciones. Depende de su versión de libpq (la interfaz C de Cliente PostrgeSQL) y de cómo fue compilado libpq. Si hace falta alguna función, libpq no soporta la característica requerida para la función.

También es importante que no use una versión de libpq más antigua que la del Servidor PostgreSQL al que se conectará. Si usa una versión de libpq más antigua que la que el Servidor PostgreSQL espera, puede tener problemas.

A partir de la versión 6.3 (03/02/1998) PostgreSQL usa sockets de dominio unix por defecto. El puerto TCP NO será abierto por defecto. A continuación se presenta una tabla que describe estas posibilidades de conexión nuevas. Este socket se encontrará en /tmp/.s.PGSQL.5432. Esta opción puede habilitarse con la bandera '-i' a postmaster y su significado es: "escuche en sockets TCP/IP asi como en sockets de dominio Unix".

Tabla 3. Postmaster y PHP

PostmasterPHPStatus
postmaster &pg_connect("dbname=NombreDeMiBD");OK
postmaster -i &pg_connect("dbname=NombreDeMiBD");OK
postmaster &pg_connect("host=localhost dbname=NombreDeMiBD"); No fue posible conectarse con el servidor PostgreSQL: connectDB() falló: ¿Está corriendo postmaster y acepta conexiones TCP/IP (con -i) en 'localhost' en el puerto '5432'? en /ruta/hacia/archivo.php en la línea 20.
postmaster -i &pg_connect("host=localhost dbname=NombreDeMiBD");OK

Puede establecerse una conexión con el servidor PostgreSQL con el siguiente juego de pares de valores en la cadena de comando: $con = pg_connect("host=miHost port=miPuerto tty=miTTY options=misOpciones dbname=miBD user=miUsuario password=miContrasenya ");

La sintaxis previa de: $conn = pg_connect ("host", "port", "options", "tty", "dbname") ha sido marcada como obsoleta.

Las variables de entorno afectan el comportamiente de servidor/cliente de PostgreSQL. Por ejemplo, el módulo PostgreSQL buscará la variable de entorno PGHOSN cuando el nombre de host sea omitido en la cadena de conexión. Las variables de entorno soportadas son diferentes entre versión y versión. Refiérase el Manual de Programador de PostgreSQL (libpq - Variables de Entorno) para más detalles.

Asegúrese de establecer las variables de entorno para el usuario apropiado. Use $_ENV o getenv() para chequear cuáles variables de entorno están disponibles en el proceso actual.

Ejemplo 1. Definición de parámetros predeterminados

PGHOST=pgsql.example.com
PGPORT=7890
PGDATABASE=sistema-web
PGUSER=usuario-web
PGPASSWORD=secreto
PGDATESTYLE=ISO
PGTZ=JST
PGCLIENTENCODING=EUC-JP

export PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD PGDATESTYLE PGTZ PGCLIENTENCODING

Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles solamente cuando la extensión ha sido o bien compilada dentro de PHP o grabada dinámicamente en tiempo de ejecución.

PGSQL_ASSOC (integer)

PGSQL_NUM (integer)

PGSQL_BOTH (integer)

PGSQL_CONNECTION_BAD (integer)

PGSQL_CONNECTION_OK (integer)

PGSQL_SEEK_SET (integer)

PGSQL_SEEK_CUR (integer)

PGSQL_SEEK_END (integer)

PGSQL_ESCAPE_STRING (integer)

PGSQL_ESCAPE_BYTEA (integer)

PGSQL_EMPTY_QUERY (integer)

PGSQL_COMMAND_OK (integer)

PGSQL_TUPLES_OK (integer)

PGSQL_COPY_OUT (integer)

PGSQL_COPY_IN (integer)

PGSQL_BAD_RESPONSE (integer)

PGSQL_NONFATAL_ERROR (integer)

PGSQL_FATAL_ERROR (integer)

Ejemplos

A partir de PostgreSQL 7.1.0, puede almacenar hasta 1GB en un campo de tipo texto. En versiones anteriores, éste se encontraba limitado al tamaño de bloque (por defecto 8KB, el máximo era 32KB, definido en tiempo de compilación)

Para usar la interfaz de objetos grandes (lo), es necesario ubicar las funciones de objetos grandes en el interior de un bloque de transacción. Un bloque de transacción comienza con una sentencia SQL BEGIN y, si la transacción fue válida, termina con COMMIT o END. Si la transacción falla, ésta debe ser cerrada con ROLLBACK o ABORT.

Ejemplo 2. Uso de Objetos Grandes

<?php
    $base_de_datos
= pg_connect("dbname=jacarta");
    
pg_query($base_de_datos, "begin");
    
$oid = pg_lo_create($base_de_datos);
    echo
"$oid\n";
    
$gestor = pg_lo_open($base_de_datos, $oid, "w");
    echo
"$gestor\n";
    
pg_lo_write($gestor, "datos de objeto grande");
    
pg_lo_close($gestor);
    
pg_query($base_de_datos, "commit");
?>
Usted no debe cerrar la conexión con el servidor PostgreSQL antes de cerrar el objeto grande.

Tabla de contenidos
pg_affected_rows -- Returns number of affected records (tuples)
pg_cancel_query --  Cancel asynchronous query
pg_client_encoding --  Gets the client encoding
pg_Close -- Cierra una conexión PostgreSQL
pg_Connect -- Abre una conexión
pg_connection_busy --  Get connection is busy or not
pg_connection_reset --  Reset connection (reconnect)
pg_connection_status --  Get connection status
pg_convert --  Convert associative array value into suitable for SQL statement.
pg_copy_from --  Insert records into a table from an array
pg_copy_to --  Copy a table to an array
pg_DBname -- Nombre de la base de datos
pg_delete --  Deletes records.
pg_end_copy -- Sync with PostgreSQL backend
pg_escape_bytea --  Escape binary for bytea type
pg_escape_string --  Escape string for text/char type
pg_fetch_all -- Fetches all rows from a result as an array
pg_Fetch_Array -- obtiene una fila en la forma de un array
pg_fetch_assoc -- Fetch a row as an associative array
pg_Fetch_Object -- obtener una fila en forma de objeto
pg_fetch_result -- Returns values from a result resource
pg_Fetch_Row -- obtiene la fila como un array enumerado
pg_field_is_null -- Test if a field is NULL
pg_field_name -- Returns the name of a field
pg_field_num -- Returns the field number of the named field
pg_field_prtlen -- Returns the printed length
pg_field_size --  Returns the internal storage size of the named field
pg_field_type --  Returns the type name for the corresponding field number
pg_free_result -- Free result memory
pg_get_notify -- Ping database connection
pg_get_pid -- Ping database connection
pg_get_result --  Get asynchronous query result
pg_Host -- Devuelve el nombre del host
pg_insert --  Insert array into table.
pg_last_error -- Get the last error message string of a connection
pg_last_notice --  Returns the last notice message from PostgreSQL server
pg_last_oid -- Returns the last object's oid
pg_lo_close -- Close a large object
pg_lo_create -- Create a large object
pg_lo_export -- Export a large object to file
pg_lo_import -- Import a large object from file
pg_lo_open -- Open a large object
pg_lo_read_all --  Reads an entire large object and send straight to browser
pg_lo_read -- Read a large object
pg_lo_seek --  Seeks position of large object
pg_lo_tell --  Returns current position of large object
pg_lo_unlink -- Delete a large object
pg_lo_write -- Write a large object
pg_meta_data --  Get meta data for table.
pg_num_fields -- Returns the number of fields
pg_num_rows -- Returns the number of rows
pg_Options -- Devuelve opciones
pg_parameter_status --  Returns the value of a server parameter
pg_pConnect --  Crea una conexión persistente con una base de datos
pg_ping -- Ping database connection
pg_Port -- Devuelve el número de puerto
pg_put_line -- Send a NULL-terminated string to PostgreSQL backend
pg_query -- Execute a query
pg_result_error --  Get error message associated with result
pg_result_seek -- Set internal row offset in result resource
pg_result_status --  Get status of query result
pg_select --  Select records.
pg_send_query --  Sends asynchronous query
pg_set_client_encoding --  Set the client encoding
pg_trace -- Enable tracing a PostgreSQL connection
pg_tty -- Devuelve el nombre del tty
pg_unescape_bytea --  Unescape binary for bytea type
pg_untrace -- Disable tracing of a PostgreSQL connection
pg_update --  Update table.
pg_version --  Returns an array with client, protocol and server version (when available)