Documentazione di PostgreSQL 9.0 > Il linguaggio SQL > Funzioni e Operatori > Funzioni di amministrazione di sistema
PrecedenteFunzioni per informazioni di sistemaFunzioni triggerSuccessivo

9.24. Funzioni di amministrazione di sistema

Tabella 9.54, «Funzioni per impostazioni di configurazione» mostra le funzioni disponibili per interrogare e modificare parametri di configurazione durante l'esecuzione.

Tabella 9.54. Funzioni per impostazioni di configurazione

NomeTipo di ritornoDescrizione
current_setting(setting_name) textottiene il valore corrente dell'impostazione
set_config(setting_name, , new_value, , is_local) textimposta il parametro e ritorna il nuovo valore

La funzione current_setting fornisce il valore corrente dell'impostazione setting_name. Essa corrisponde al comando SQL SHOW. Un esempio:

SELECT current_setting('datestyle');

 current_setting
-----------------
 ISO, MDY
(1 row)

set_config imposta il parametro setting_name a new_value. Se is_local è true, il nuovo valore sarà applicato solo alla transazione corrente. Se si vuole il nuovo valore da applicare per la sessione corrente, usare invece false. La funzione corrisponde al comando SQL SET. Un esempio:

SELECT set_config('log_statement_stats', 'off', false);

 set_config
------------
 off
(1 row)

La funzione mostrata in Tabella 9.55, «Funzioni di segnalazione al server» manda segnali di controllo agli altri processi del server. L'uso di queste funzioni è limitato ai speruser.

Tabella 9.55. Funzioni di segnalazione al server

NomeTipo di ritornoDescrizione
pg_cancel_backend(pid, int) booleanCancella la query di backend corrente
pg_terminate_backend(pid, int) booleanTermina un backend
pg_reload_conf() booleanFa si che i processi del server ricarichino i loro file di configurazione
pg_rotate_logfile() booleanRuota il file di log del server

Ognuna di queste funzioni ritorna true se ha successo e false altrimenti.

pg_cancel_backend e pg_terminate_backend mandano segnali (SIginT o SIGTERM rispettivamente) sui processi di backend identificati dall'ID di processo. L'ID di processo di un backend attivo può essere trovato con la colonna procpid della vista pg_stat_activity, o elencando i processi postgres sul server (usando ps su Unix o il Task Manager su Windows™).

pg_reload_conf invia un segnale SIGHUP al server, facendo si che i file di configurazione siano ricaricati da tutti i processi del server.

pg_rotate_logfile segnala al gestore del file di log di cambiare file di output immediatamente. Questo funziona solo quando il log collector incorporato sta viaggiando, dato che altrimenti non c'è nessun sottoprocesso di gestione del file di log.

Le funzioni mostrate in Tabella 9.56, «Funzioni di controllo del backup» aiutano a fare backup on-line. Queste funzioni non possono essere eseguite durante un recovery. L'uso di queste tre funzioni è limitato ai superuser.

Tabella 9.56. Funzioni di controllo del backup

NomeTipo di ritornoDescrizione
pg_start_backup(label, text [, fast boolean ]) text Predispone per il backup on-line
pg_stop_backup() text Termina il backup on-line
pg_switch_xlog() textForza il passaggio a un file di log di transazione nuovo
pg_current_xlog_location() text Restituisce la posizione delle scritture del log della transazione corrente
pg_current_xlog_insert_location() text Rende la locazione di inserimento del log di transazione corrente
pg_xlogfile_name_offset(location, text) text, integer Converte la stringa di locazione del log di transazione in un nome di file e lo scostamento decimale di byte all'interno del file
pg_xlogfile_name(location, text) text Converte la stringa di locazione del log in un nome di file

pg_start_backup accetta un'etichetta arbitraria definita dall'utente per il backup. (Tipicamente questa sarebbe il nome sotto il quale il file dump di backup sarà immagazzinato). La funzione scrive un file etichetta di backup (backup_label) nella directory dati del cluster di database, esegue un checkpoint, e poi restituisce la locazione del log dell'inizio della transazione di backup come testo. L'utente può ignorare questo valore, ma viene fornito nel caso fosse utile.

postgres=# select pg_start_backup('label_goes_here');
 pg_start_backup
-----------------
 0/D4445B8
(1 row)

C'è un secondo parametro opzionale di tipo boolean. Se true, esso specifica di eseguire pg_start_backup il più velocemente possibile. Questo forza un checkpoint immediato che causerà un blocco delle operazioni di I/O, rallentando qualsiasi query eseguita concorrentemente.

pg_stop_backup rimuove il file etichetta creato da pg_start_backup, e crea un file storico per il backup nell'area archivio del log di transazione. Il file storico include l'etichetta fornita a pg_start_backup, le locazioni di inizio e fine del log di transazione per il backup e gli orari di inizio e di fine del backup. Il valore di ritorno è la locazione del log di fine transazione di backup (che di nuovo, può essere ignorato). Dopo aver registrato la locazione finale, il punto di inserimento del log di transazione corrente viene automaticamente avanzato al prossimo file di log di transazione, così che il file di log di fine transazione possa essere archiviato immediatamente per completare il backup.

pg_switch_xlog si muove al prossimo file di log di transazione, permettendo che il file corrente sia archiviato (assumendi che si stia usando archiviazione continua). Il valore di ritorno è la locazione del log di fine transazione +1 all'interno del file di log di transazione appena completato. Se non c'è stat attività di log di transazione dall'ultimo cambio di log di transazione, pg_switch_xlog non fa niente e restituisce la locazione di inizio del file di log di transazione attualmente in uso.

pg_current_xlog_location mostra la locazione attuale del log di transazione ma nello stesso formato usato della funzioni viste sopra. Similarmente, pg_current_xlog_insert_location mostra il punto di inserimento nel log della transazione corrente. Il punto di inserimento è la fine «logica» del log di transazione in qualsiasi istante, mentre la locazione di scritture è la fine di quello che attualmente è stato trascritto dai buffer interni del server. La locazione di scrittura è la fine di quello che può essere esaminato dall'esterno del server, solitamente è quello che vuoi se sei interessato nell'archiviazione di file di log di transazione parzialmente completi. Il punto di inserimento è reso disponibile principalmente per scopi di debug del seerver. Queste due sono operazioni di sola lettura e non richiedono i permessi di superuser.

È possibile usare pg_xlogfile_name_offset per estrarre il nome del file di log di transazione corrispondente e lo scostamento di byte dal risultato di una delle funzioni viste sopra. Per esempio:

postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
        file_name         | file_offset 
--------------------------+-------------
 00000001000000000000000D |     4039624
(1 row)

Similarmente, pg_xlogfile_name estrae solo il nome del file di log. Quando la locazione del log di transazione fornito è esattamente al confine di un file di log di transazione, tutte e due le funzioni ritornano il nome del file di log di transazione precedente. Questo di solito è il comportamento desiderato per gestire l'archiviazione dei log di transazione, dato che il file precedente è l'ultimo che attualmente ha bisogno di essere archiviato.

Per dettagli circa il giusto uso di queste funzioni, vedere Sezione 24.3, «Archiviazione continua e Ripristino Point-In-Time (PITR)».

Le funzioni mostrate in Tabella 9.57, «Recovery Information Functions» forniscono informazioni sullo stato corrente dello standby. Queste funzioni possono essere eseguite sia durante il recovery che durante la normale esecuzione.

Tabella 9.57. Recovery Information Functions

NameReturn TypeDescription
pg_is_in_recovery() boolTrue if recovery is still in progress.
pg_last_xlog_receive_location() textGet last transaction log location received and synced to disk by streaming replication. While streaming replication is in progress this will increase monotonically. But when streaming replication is restarted this will back off to the replication starting position, typically the beginning of the WAL file containing the current replay location. If recovery has completed this will remain static at the value of the last WAL record received and synced to disk during recovery. If streaming replication is disabled, or if it has not yet started, the function returns NULL.
pg_last_xlog_replay_location() textGet last transaction log location replayed during recovery. If recovery is still in progress this will increase monotonically. If recovery has completed then this value will remain static at the value of the last WAL record applied during that recovery. When the server has been started normally without recovery the function returns NULL.

Le funzioni mostrate in Tabella 9.58, «Funzioni sulla dimensione degli oggetti di database» calcolano l'uso dello sapzio del disco da parte degli oggetti del database.

Tabella 9.58. Funzioni sulla dimensione degli oggetti di database

NomeTipo di ritornoDescrizione
pg_column_size(any)int Numero di byte usati per immagazzinare un valore particolare (possibilmente compresso)
pg_total_relation_size(regclass) bigint Spazio su disco totale usato dalla tabella con OID o nome specificato, inclusi tutti gli indici e dati TOAST
pg_table_size(regclass) bigint Spazio su disco totale usato dalla tabella con OID o nome specificato, esclusi gli indici (ma inclusi TOAST, mappa dello spazio libero e mappa di visibilità)
pg_indexes_size(regclass) bigint Spazio su disco totale usato dagli indici connessi alla tabella con OID o nome specificato
pg_database_size(oid) bigint Spazio su disco usato dal database con l'OID specificato
pg_database_size(name) bigint Spazio su disco usato dal databse con il nome specificato
pg_tablespace_size(oid) bigint Spazio su disco usato dal tablespace con l'OID specificato
pg_tablespace_size(name) bigint Spazio su disco usato dal tablespace con il nome specificato
pg_relation_size(relation, regclass, fork, text) bigint Spazio su disco usato del fork specificato ('main', 'fsm' or 'vm') della tabella o dell'indice con l'OID o il nome fornito
pg_relation_size(relation, regclass) bigint Shorthand for pg_relation_size(..., 'main') Scorciatoia per pg_relation_size(..., 'main')
pg_size_pretty(bigint) text Converte una dimensione in byte in un formato leggibile con unità di dimensione

pg_column_size mostra lo sapzio usato per immagazzinare ogni singolo valore di dato.

pg_total_relation_size acceta l'OID o il nome di una tabella o di una tabella toast, e restituisce lo spazio su disco totale usato per quella tabella, includendo tutti gli indici associati. Questa funzione è equivalente a pg_table_size + pg_indexes_size.

pg_table_size accetta l'OID o il nome di una tabella e restituisce lo spazio su disco necessario per quella tabella, escluso gli indici. (incluso spazio TOAST, mappa dello spazio libero e mappa di visibilità).

pg_indexes_size accetta l'OID o il nome di una tabella e restituisce lo spazio su disco totale usato da tutti gli indici connessi a quella tabella.

pg_database_size e pg_tablespace_size accettano l'OID o il nome di un database o un tablespace, e restituiscono lo spazio su disco usato ivi contenuto.

[Nota]

Nota

Nota per il revisore: data fork ?

pg_relation_size accetta l'OID o il nome di una tabella, indice o tabella toast, e restituisce lo spazio su disco in byte. Specificare 'main' o lasciare vuoto il secondo argomento restituisce la dimensione del fork principale dei dati della relazione. Specificare 'fsm' restituisce la dimensione della Mappa dello spazio libero (vedere Sezione 54.3, «Free Space Map») associata alla relazione. Specificare 'vm' restituisce la dimensione della Mappa di visibilità (vedere Sezione 54.4, «Visibility Map») associata con la relazione. Notare che questa funzione mostra la dimensione di solo un fork; per la mamaggior parte degli scopi è più conveniente usare le funzioni a più alto livello pg_total_relation_size o pg_table_size.

pg_size_pretty puà essere usata per formattare il risultato di una delle altre funzioni in maniera leggibile dall'uomo, usando kB, MB, GB o TB come appropriato.

Le funzioni mostrate in Tabella 9.59, «Funzioni di locazione di oggetti di database» aiutano nell'identificare i file disco specifici associati con gli oggetti del database.

Tabella 9.59. Funzioni di locazione di oggetti di database

NomeTipo di ritornoDescrizione
pg_relation_filenode(relation, regclass) oid numero filenode della relazione con l'OID o il nome specificato
pg_relation_filepath(relation, regclass) text Percorso del file della relazione con il nome o l'OID specificato

pg_relation_filenode accetta l'OID o il nome di una tabella, indice, sequenza o tabella toast, e restituisce il numero di «filenode» attualmente assegnato ad esso. Il filenode è il componente base del nome del/i file usato/i per la relazzione (vedere Sezione 54.1, «Database File Layout» per maggiori informazioni). Per la maggior parte delle tabelle il risultato è lo stesso di pg_class.relfilenode, ma per certi cataloghi di sistema relfilenode è zero e questa funzione deve essere usato per ottenete il valore corretto. La funzione restituisce NULL se viene passata una relazione che non ha immagazzinamento, tipo una vista.

pg_relation_filepath è simile a pg_relation_filenode, ma restituisce l'intero percorso del file (relativo alla directory dati PGDATA del cluster di database) della relazione.

La funzione mostrata in Tabella 9.60, «Funzioni di accesso ai file» fornisce accesso nativo a file sulla macchina che esegue l'hosting del server. Solo i file all'interno della directory cluster di database e la log_directory possono essere accesse. Usare un percorso relativo per i file nella directory cluster, e un percorso che corrisponde all'impostazione di configurazione log_directory per i file di log. L'uso di queste funzioni è limitato al superuser.

Tabella 9.60. Funzioni di accesso ai file

NomeTipo di ritornoDescrizione
pg_ls_dir(dirname, text) setof textLista i contenuti di una directory
pg_read_file(filename, text, offset, bigint, length, bigint) textRestituisce i contenuti di un file di testo
pg_stat_file(filename, text) recordRestituisce informazioni su un file

pg_ls_dir restituisce tutti i nomi nella specifica directory, ad eccezione delle voci speciali «.» e «..» .

pg_read_file restituisce parte di un file di testo, cominciando all'offset fornito, e ritorna al massimo length byte (meno se la fine del file viene raggiunta prima). Se offset è negativo, partirà dalla fine del file.

pg_stat_file ritorna un record contenente la dimensione del file, il timestamp dell'ultimo accesso, il timestamp dell'ultima modifica, il timestamp dell'ultimo cambiamento di stato del file (solo su piattaforme Unix), il timestamp della creazione del file (solo Windows), e un boolean indicante se è una directory. Utilizzi tipici includono:

SELECT * FROM pg_stat_file('filename');
SELECT (pg_stat_file('filename')).modification;

Le funzioni mostrate in Tabella 9.61, «Funzioni di lock consultivi» gestiscono i lock consultivi. Per dettagli circa l'uso corretto di queste funzioni, vedere Sezione 13.3.4, «Lock consultivi».

Tabella 9.61. Funzioni di lock consultivi

NomeTipo di ritornoDescrizione
pg_advisory_lock(key, bigint) voidOttiene un lock consultivo esclusivo
pg_advisory_lock(key1, int, key2, int) voidOttiene un lock consultivo esclusivo
pg_advisory_lock_shared(key, bigint) voidOttiene un lock consultivo condiviso
pg_advisory_lock_shared(key1, int, key2, int) voidOttiene un lock consultivo condiviso
pg_try_advisory_lock(key, bigint) booleanOttiene un lock consultivo esclusivo se disponibile
pg_try_advisory_lock(key1, int, key2, int) booleanOttiene un lock consultivo esclusivo se disponibile
pg_try_advisory_lock_shared(key, bigint) booleanOttiene un lock consultivo condiviso se disponibile
pg_try_advisory_lock_shared(key1, int, key2, int) booleanOttiene un lock consultivo condiviso se disponibile
pg_advisory_unlock(key, bigint) booleanRilascia un advisory lock condiviso
pg_advisory_unlock(key1, int, key2, int) booleanRilascia un advisory lock esclusivo
pg_advisory_unlock_shared(key, bigint) booleanRilascia un advisory lock condiviso
pg_advisory_unlock_shared(key1, int, key2, int) booleanRelease a shared advisory lock
pg_advisory_unlock_all() voidRilascia tutti i lock consultivi della sessione corrente

La funzione pg_advisory_lock blocca una risorsa definita in una applicazione, che può essere identificata o tramite un singolo valore chiave a 64-bit oppure tramite due valori chiave a 32-bit (notare che questi due spazi chiave non si sovrappongono). Se un altra sessione è già titolare di un blocco sulla stessa risorsa, la funzione dovrà attendere finchè la risorsa diventa disponibile. Il blocco è esclusivo. Le richieste multiple di blocco vengono messe in stack, per cui se la stessa risorsa è stata bloccata tre volte essa dovrà essere sbloccata tre volte prima di essere rilasciata per l'utilizzo in altre sessioni.

La funzione pg_advisory_lock_shared lavora come pg_advisory_lock, eccetto che il blocco può essere condiviso con altre sessioni che richiedono un blocco condiviso. Solo chi aspira ad un blocco esclusivo verrà escluso.

La funzione pg_try_advisory_lock è simile alla pg_advisory_lock, eccetto che essa non dovrà aspettare che il blocco diventi disponibile. Essa potrà ottenere il blocco immediatamente e restituire true, oppure restituire false se il blocco non può essere immediatamente acquisito.

La funzione pg_try_advisory_lock_shared lavora nello stesso modo della pg_try_advisory_lock, eccetto che essa tenta di acquisire blocchi condivisi anziche blocchi esclusivi.

La funzione pg_advisory_unlock rilascia un advisory lock esclusivo acquisito in precedenza. Essa restituirà true se il blocco è stato rilasciato con successo. Se il blocco non è di fatto tenuto, verrà restituito false, e in aggiunta, il server rileverà un warning SQL.

La funzione pg_advisory_unlock_shared lavora nello stesso modo della pg_advisory_unlock, solo che rilascia un advisory lock condiviso.

La funzione pg_advisory_unlock_all rilascia tutti gli advisory lock mantenuti nella sessione corrente. (Questa funzione viene implicitamente chiamata alla fine della sessione, anche se il client si disconnette in modo non corretto).

Documentazione di PostgreSQL 9.0 > Il linguaggio SQL > Funzioni e Operatori > Funzioni di amministrazione di sistema
PrecedenteFunzioni per informazioni di sistemaFunzioni triggerSuccessivo