Manuale PHP
Indietro |  | Avanti

# CXIV. Funzioni PostgreSQL

# Introduzione

Il database PostgreSQL è un prodotto OpenSource ed è disponibile gratuitamente. Postgres, sviluppato originariamente nel Dipartimento di Informatica dell'Università di Berkeley, ha anticipato molti dei concetti su oggetti e relazioni che ora stanno diventando disponibili in alcuni database commerciali. Postgres fornisce supporto per il linguaggio SQL/92/SQL99, transazioni, integrità referenziale, stored procedures ed estensibilità dei tipi. PostgreSQL è un discendente open source dell'originario codice di Berkeley.

# Requisiti

Per utilizzare il supporto a PostgreSQL, occorre PostgreSQL 6.5 o versioni più recenti. PostgreSQL 7.0 o successivi permettono di abilitare tutte le funzionalità di questo modulo. PostgreSQL ammette molte codifiche di carattere, tra cui la codifica multibyte. La versione corrente e maggiori informazioni su PostgreSQL sono disponibili su http://www.postgresql.org/ e http://techdocs.postgresql.org/.

# Installazione

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.

# Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di `php.ini`.

Tabella 1. PostgreSQL configuration options

Name | Default | Changeable | Changelog
--- | --- | --- | ---
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 | Available since PHP 4.2.0.
pgsql.ignore_notice | "0" | PHP_INI_ALL | Available since PHP 4.3.0.
pgsql.log_notice | "0" | PHP_INI_ALL | Available since PHP 4.3.0.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

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.

# Utilizzo e suggerimenti

Avvertimento
L'utilizzo del modulo PostgreSQL con PHP 4.0.6 non è raccomandato a causa di un bug nella gestione dei messaggi. Si usi PHP 4.1.0 o successivi.

Avvertimento

I nomi delle funzioni relative a PostgreSQL verranno cambiate a partire dalla versione 4.2.0 per conformarsi agli standard di sviluppo attuali. La maggior parte dei nuovi nomi avrà underscore aggiuntivi, per esempio pg_lo_open(). Alcune funzioni verranno rinominate per dare consistenza. Per esempio pg_exec() diventerà pg_query(). I vecchi nomi potranno essere usati nella versione 4.2.0 e in alcune versioni successive alla 4.2.0, ma potranno essere cancellati in futuro.

Tabella 2. Nomi di funzione cambiati

Vecchio nome | Nuovo nome
--- | ---
pg_exec() | pg_query()
pg_getlastoid() | pg_last_oid()
pg_cmdtuples() | pg_affected_rows()
pg_numrows() | pg_num_rows()
pg_numfields() | pg_num_fields()
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_result() | pg_fetch_result()
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()

La vecchia sintassi di pg_connect()/pg_pconnect() sarà deprecata per supportare, in futuro, connessioni asincrone. Si usi una stringa di connessione con pg_connect() e pg_pconnect().

Non tutte le funzioni sono supportate su tutte le architetture. Dipende dalla versione di libpq (L'interfaccia Client C per PostgreSQL) e da come libpq è compilato. Se c'è una funzione mancante, libpq non supporta la feature richiesta per quella funzione.

È importante usare versioni di libpq più recenti rispetto al Server PostgreSQL al quale ci si vuole collegare. Se si usa una versione di libpq più vecchia rispetto al Server PostgreSQL al quale ci si vuole collegare, si andrà probabilmente incontro a problemi.

Fin dalla versione 6.3 (03/02/1998) PostgreSQL usa gli unix domain socket di default. La porta TCP, di default, NON verrà aperta. La tabella sottostante descrive queste nuove possibilità di connessione. Questo socket può essere trovato in `/tmp/.s.PGSQL.5432`. Questa opzione può venire abilitata con la flag '-i' da postmaster e il suo significato è: "ascolta i socket TCP/IP così come gli Unix domain socket".

Tabella 3. Postmaster e PHP

Postmaster | PHP | Status
--- | --- | ---
postmaster & | pg_connect("dbname=NomeMioDatabase"); | OK
postmaster -i & | pg_connect("dbname=NomeMioDatabase"); | OK
postmaster & | pg_connect("host=localhost dbname=NomeMioDatabase"); | Unable to connect to PostgreSQL server: connectDB() failed: Is the postmaster running and accepting TCP/IP (with -i) connection at 'localhost' on port '5432'? in /path/to/file.php on line 20.
postmaster -i & | pg_connect("host=localhost dbname=NomeMioDatabase"); | OK

Si può stabilire una connessione al server PostgreSQL usando le seguenti coppie di valori impostate nella stringa di comando: $conn = pg_connect("host=IlMioHost port=LaMiaPorta tty=myTTY options=LeMieOpzioni dbname=IlMioDB user=IlMioUtente password=LaMiaPassword ");

L'uso della sintassi in uso precedentemente: $conn = pg_connect ("host", "port", "options", "tty", "dbname") è deprecato.

Le variabili d'ambiente modificano il comportamento server/client di PostgreSQL. Per esempio, il modulo PostgreSQL si baserà sulla variabile PGHOST quando il nome dell'host è omesso nella stringa di connessione. Le variabili d'ambiente riconosciute sono diverse da versione a versione. Consultare il Manuale del Programmatore PostgreSQL (libpq - Variabili d'Ambiente) per ulteriori dettagli.

Assicurarsi di aver impostato le variabili d'ambiente per l'utente appropriato. Usare $_ENV o getenv() per controllare quali variabili d'ambiente sono disponibili al processo corrente.

Esempio 1. Impostazione dei parametri di default

    PGHOST=pgsql.example.com
    PGPORT=7890
    PGDATABASE=web-system
    PGUSER=web-user
    PGPASSWORD=segreta
    PGDATESTYLE=ISO
    PGTZ=JST
    PGCLIENTENCODING=EUC-JP

    export PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD PGDATESTYLE PGTZ PGCLIENTENCODING

# Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

`PGSQL_ASSOC` (integer)

  Passed to pg_fetch_array(). Return an associative array of field names and values.

`PGSQL_NUM` (integer)

  Passed to pg_fetch_array(). Return a numerically indexed array of field numbers and values.

`PGSQL_BOTH` (integer)

  Passed to pg_fetch_array(). Return an array of field values that is both numerically indexed (by field number) and associated (by field name).

`PGSQL_CONNECT_FORCE_NEW` (integer)

  Passed to pg_connect() to force the creation of a new connection, rather then re-using an existing identical connection.

`PGSQL_CONNECTION_BAD` (integer)

  Returned by pg_connection_status() indicating that the database connection is in an invalid state.

`PGSQL_CONNECTION_OK` (integer)

  Returned by pg_connection_status() indicating that the database connection is in a valid state.

`PGSQL_SEEK_SET` (integer)

  Passed to pg_lo_seek(). Seek operation is to begin from the start of the object.

`PGSQL_SEEK_CUR` (integer)

  Passed to pg_lo_seek(). Seek operation is to begin from the current position.

`PGSQL_SEEK_END` (integer)

  Passed to pg_lo_seek(). Seek operation is to begin from the end of the object.

`PGSQL_EMPTY_QUERY` (integer)

  Returned by pg_result_status(). The string sent to the server was empty.

`PGSQL_COMMAND_OK` (integer)

  Returned by pg_result_status(). Successful completion of a command returning no data.

`PGSQL_TUPLES_OK` (integer)

  Returned by pg_result_status(). Successful completion of a command returning data (such as a SELECT or SHOW).

`PGSQL_COPY_OUT` (integer)

  Returned by pg_result_status(). Copy Out (from server) data transfer started.

`PGSQL_COPY_IN` (integer)

  Returned by pg_result_status(). Copy In (to server) data transfer started.

`PGSQL_BAD_RESPONSE` (integer)

  Returned by pg_result_status(). The server's response was not understood.

`PGSQL_NONFATAL_ERROR` (integer)

  Returned by pg_result_status(). A nonfatal error (a notice or warning) occurred.

`PGSQL_FATAL_ERROR` (integer)

  Returned by pg_result_status(). A fatal error occurred.

`PGSQL_TRANSACTION_IDLE` (integer)

  Returned by pg_transaction_status(). Connection is currently idle, not in a transaction.

`PGSQL_TRANSACTION_ACTIVE` (integer)

  Returned by pg_transaction_status(). A command is in progress on the connection. A query has been sent via the connection and not yet completed.

`PGSQL_TRANSACTION_INTRANS` (integer)

  Returned by pg_transaction_status(). The connection is idle, in a transaction block.

`PGSQL_TRANSACTION_INERROR` (integer)

  Returned by pg_transaction_status(). The connection is idle, in a failed transaction block.

`PGSQL_TRANSACTION_UNKNOWN` (integer)

  Returned by pg_transaction_status(). The connection is bad.

`PGSQL_DIAG_SEVERITY` (integer)

  Passed to pg_result_error_field(). The severity; the field contents are ERROR, FATAL, or PANIC (in an error message), or WARNING, NOTICE, DEBUG, INFO, or LOG (in a notice message), or a localized translation of one of these. Always present.

`PGSQL_DIAG_SQLSTATE` (integer)

  Passed to pg_result_error_field(). The SQLSTATE code for the error. The SQLSTATE code identifies the type of error that has occurred; it can be used by front-end applications to perform specific operations (such as error handling) in response to a particular database error. This field is not localizable, and is always present.

`PGSQL_DIAG_MESSAGE_PRIMARY` (integer)

  Passed to pg_result_error_field(). The primary human-readable error message (typically one line). Always present.

`PGSQL_DIAG_MESSAGE_DETAIL` (integer)

  Passed to pg_result_error_field(). Detail: an optional secondary error message carrying more detail about the problem. May run to multiple lines.

`PGSQL_DIAG_MESSAGE_HINT` (integer)

  Passed to pg_result_error_field(). Hint: an optional suggestion what to do about the problem. This is intended to differ from detail in that it offers advice (potentially inappropriate) rather than hard facts. May run to multiple lines.

`PGSQL_DIAG_STATEMENT_POSITION` (integer)

  Passed to pg_result_error_field(). A string containing a decimal integer indicating an error cursor position as an index into the original statement string. The first character has index 1, and positions are measured in characters not bytes.

`PGSQL_DIAG_INTERNAL_POSITION` (integer)

  Passed to pg_result_error_field(). This is defined the same as the `PG_DIAG_STATEMENT_POSITION` field, but it is used when the cursor position refers to an internally generated command rather than the one submitted by the client. The `PG_DIAG_INTERNAL_QUERY` field will always appear when this field appears.

`PGSQL_DIAG_INTERNAL_QUERY` (integer)

  Passed to pg_result_error_field(). The text of a failed internally-generated command. This could be, for example, a SQL query issued by a PL/pgSQL function.

`PGSQL_DIAG_CONTEXT` (integer)

  Passed to pg_result_error_field(). An indication of the context in which the error occurred. Presently this includes a call stack traceback of active procedural language functions and internally-generated queries. The trace is one entry per line, most recent first.

`PGSQL_DIAG_SOURCE_FILE` (integer)

  Passed to pg_result_error_field(). The file name of the PostgreSQL source-code location where the error was reported.

`PGSQL_DIAG_SOURCE_LINE` (integer)

  Passed to pg_result_error_field(). The line number of the PostgreSQL source-code location where the error was reported.

`PGSQL_DIAG_SOURCE_FUNCTION` (integer)

  Passed to pg_result_error_field(). The name of the PostgreSQL source-code function reporting the error.

`PGSQL_ERRORS_TERSE` (integer)

  Passed to pg_set_error_verbosity(). Specified that returned messages include severity, primary text, and position only; this will normally fit on a single line.

`PGSQL_ERRORS_DEFAULT` (integer)

  Passed to pg_set_error_verbosity(). The default mode produces messages that include the above plus any detail, hint, or context fields (these may span multiple lines).

`PGSQL_ERRORS_VERBOSE` (integer)

  Passed to pg_set_error_verbosity(). The verbose mode includes all available fields.

`PGSQL_STATUS_LONG` (integer)

  Passed to pg_result_status(). Indicates that numerical result code is desired.

`PGSQL_STATUS_STRING` (integer)

  Passed to pg_result_status(). Indicates that textual result command tag is desired.

`PGSQL_CONV_IGNORE_DEFAULT` (integer)

  Passed to pg_convert(). Ignore default values in the table during conversion.

`PGSQL_CONV_FORCE_NULL` (integer)

  Passed to pg_convert(). Use SQL NULL in place of an empty string.

`PGSQL_CONV_IGNORE_DEFAULT` (integer)

  Passed to pg_convert(). Ignore conversion of `NULL` into SQL NOT NULL columns.

# Esempi

A partire da PostgreSQL 7.1.0, il tipo di dato text ha 1GB come dimensione massima. Nelle versioni più vecchie di PostgreSQL il tipo di dato text è limitato dalla dimensione del block. (Default 8KB. Massimo 32KB, specificato al momento della compilazione)

Per usare l'interfaccia large object (lo), è necessario includerla entro un blocco di una transazione. Un blocco di transazione inizia con un comando SQL BEGIN e se la transazione è stata valida, termina con COMMIT o END. Se la transazione fallisce, essa deve venire chiusa con ROLLBACK o ABORT.

Esempio 2. Utilizzare Large Objects

`<?php $database = pg_connect ("dbname=jacarta"); pg_query ($database, "begin"); $oid = pg_lo_create ($database); echo "$oid\n"; $handle = pg_lo_open ($database, $oid, "w"); echo "$handle\n"; pg_lo_write ($handle, "dati large object"); pg_lo_close ($handle); pg_query ($database, "commit"); ?>`

Non chiudere la risorsa di connessione prima di aver chiuso la risorsa large object.

Indietro | Partenza | Avanti
sql_regcase | Risali | pg_affected_rows