LXXX. Funzioni PostgreSQL

Postgres, sviluppato originariamente nel Dipartimento di Informatica dell'Unniversità 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, integrità transazionale ed estensibilità dei tipi. PostgreSQL è un discendente open source dell'originario codice di Berkeley.

Il database PostgreSQL è un prodotto Open Source ed è disponibile gratuitamente. Per utilizzare il supporto a PostgreSQL, occorre PosgreSQL 6.5 o versioni più recenti. PostgreSQL 7.0 o successivi permettono di abilitare tutte le possibilità 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/.

Per abilitare il supporto PostgreSQL, --with-pgsql[=DIR] è richiesto quando si compila il PHP. Se è disponibile il modulo di libreria dinamico, questo può essere caricato usando la direttiva extension in php.ini o la funzione dl(). Le direttive ini previste sono descritte in php.ini-dist che è disribuito con il pacchetto dei sorgenti.

Attenzione

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.

Attenzione

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 1. Nomi di funzione cambiati

Vecchio nomeNuovo 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 2. Postmaster e PHP

PostmasterPHPStatus
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=LaMiaPort 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 (lbpq - 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
PGPASSWD=segreta
PGDATESTYLE=ISO
PGTZ=JST
PGCLIENTENCODING=EUC-JP

export PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD PGDATESTYLE PGTZ PGCLIENTENCODING

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.

Sommario
pg_affected_rows -- Restituisce il numero delle tuple coinvolte dall'ultimo comando
pg_cancel_query --  Annulla una query asincrona
pg_client_encoding --  Restituisce la codifica caratteri del client
pg_close -- Chiude una connessione PostgreSQL
pg_connect -- Stabilisce una connessione PostgreSQL
pg_connection_busy --  Riferisce se una connessione è occupata o meno
pg_connection_reset --  Rpristina la connessione (riconnette)
pg_connection_status --  Restituisce lo stato di una connessione
pg_convert --  Converte i valori di un array associativo in una forma compatibile con i comandi SQL.
pg_copy_from --  Inserisce le tuple in una tabella prendendole da un array
pg_copy_to --  Copia una tabella in un array
pg_dbname -- Restituisce il nome del database
pg_delete --  Cancella le tuple.
pg_end_copy -- Esegue una sincronizzazione con il backend PostgreSQL
pg_escape_bytea --  Aggiunge le sequenze di escape ai dati binari nel tipo bytea
pg_escape_string --  Escape string for text/char type
pg_fetch_array -- Carica una tupla in un array
pg_fetch_object -- Carica una tupla in un oggetto
pg_fetch_result -- Returns values from a result resource
pg_fetch_row -- Carica una tupla in un array
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_result --  Get asynchronous query result
pg_host --  Returns the host name associated with the connection
pg_insert --  Insert array into table.
pg_last_error -- Get the last error message string of a connection
pg_last_notice --  Restituisce l'ultimo messaggio di notifica dal server PostgreSQL
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 --  Read a 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 --  Restituisce la posizione attuale in un large object
pg_lo_unlink -- Delete a large object
pg_lo_write -- Write a large object
pg_metadata --  Get metadata for table.
pg_num_fields -- Returns the number of fields
pg_num_rows -- Returns the number of rows
pg_options -- Get the options associated with the connection
pg_pconnect -- Open a persistent PostgreSQL connection
pg_port --  Return the port number associated with the connection
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_status --  Get status of query result
pg_select --  Select records.
pg_send_query --  Send asynchronous query
pg_set_client_encoding --  Set the client encoding
pg_trace -- Enable tracing a PostgreSQL connection
pg_tty --  Return the tty name associated with the connection
pg_untrace -- Disable tracing of a PostgreSQL connection
pg_update --  Update table.