psql — terminal interactif PostgreSQL
psql [option...] [nombase
[nomutilisateur]]
psql est une interface en mode texte pour PostgreSQL. Il vous permet de saisir des requêtes de façon interactive, de les exécuter sur PostgreSQL et de voir les résultats de ces requêtes. Alternativement, les entrées peuvent être lues à partir d'un fichier ou à partir des arguments de la ligne de commande. De plus, il fournit un certain nombre de métacommandes et plusieurs fonctionnalités style shell pour faciliter l'écriture des scripts et automatiser une grande variété de tâches.
-a--echo-all
Affiche toutes les lignes non vides en entrée sur la sortie standard
lorsqu'elles sont lues. (Ceci ne s'applique pas aux lignes lues de
façon interactive.) C'est équivalent à initialiser la variable
ECHO à all.
-A--no-align
Bascule dans le mode d'affichage non aligné. (Le mode d'affichage par
défaut est aligné.) Ceci est équivalent à \pset format
unaligned.
-b--echo-errors
Affiche les commandes SQL qui ont échoué sur la sortie standard des erreurs.
C'est équivalent à configurer la variable ECHO à
errors.
-c commande--command=commande
Indique que psql doit exécuter la commande
indiquée dans le paramètre commande. Cette option peut être
répétée et combinée avec l'option -f dans n'importe
quel ordre. Quand soit -c soit -f est
utilisée, psql ne lit pas les commandes à
partir de l'entrée standard ; à la place, il quitte après avoir
traité toutes les options -c et -f
dans la séquence indiquée.
commande doit être soit
une chaîne de commande complètement analysable par le serveur
(autrement dit, elle ne contient pas de fonctionnalités spécifiques à
psql), soit une simple métacommande. De ce
fait, vous ne pouvez pas mixer les commandes SQL et les
métacommandes psql dans une option
-c. Pour ce faire, vous pouvez utiliser plusieurs
options -c ou envoyer la chaîne par un tube
(pipe) dans
psql, par exemple :
psql -c '\x' -c 'SELECT * FROM foo;'
or
echo '\x \\ SELECT * FROM foo;' | psql
(\\ est le séparateur de métacommandes.)
Chaque chaîne de commande SQL passée à
-c est envoyée au serveur comme une requête unique. De
ce fait, le serveur l'exécute comme une seule transaction, même si la
chaîne contient plusieurs commandes SQL, sauf si des
commandes BEGIN/COMMIT explicites
sont incluses dans la chaîne pour la diviser en plusieurs transactions.
De plus, psql n'affiche que le résultat
de la dernière commande SQL dans la chaîne. Ce
comportement est différent de celui où la même chaîne est lue à partir
d'un fichier ou envoyée à psql via l'entrée
standard, parce qu'alors psql envoie chaque
commande SQL séparément.
À cause de ce comportement, placer plus d'une commande dans une option
-c a souvent des résultats inattendus. Il est
préférable d'utiliser plusieurs options -c ou
d'envoyer les différentes commandes à psql
via l'entrée standard, soit en utilisant
echo comme dans l'exemple ci-dessus, soit en
utilisant une redirection de type « here-document », comme
ci-dessous :
psql <<EOF
\x
SELECT * FROM foo;
EOF
-d nombase--dbname=nombase
Indique le nom de la base de données où se connecter. Ceci est
équivalent à spécifier nombase comme premier argument de la
ligne de commande qui n'est pas une option. Le nom de la base,
dbname, peut être remplacé par une chaîne de connexion. Dans ce cas, les
paramètres de la chaîne de connexion surchargeront toutes les options en
ligne de commande conflictuelles.
-e--echo-queries
Copie toutes les commandes SQL envoyées au serveur aussi sur la sortie
standard. Ceci est équivalent à initialiser la variable
ECHO à queries.
-E--echo-hidden
Affiche les requêtes réelles générées par \d et autres
commandes antislash. Vous pouvez utiliser ceci pour étudier les
opérations internes de psql. Ceci est
équivalent à initialiser la variable ECHO_HIDDEN
à on.
-f nomfichier--file=nomfichier
Lit les commandes à partir du fichier nomfichier, plutôt que l'entrée
standard. Cette option peut être répétée et combinée dans tout ordre
avec l'option -c. Quand ni -c ni
-f n'est indiquée, psql ne
lit pas les commandes à partir de l'entrée standard ; à la place,
il termine après avoir traité toutes les options -c et
-f dans la séquence indiquée. En dehors de ça, cette
option est fortement équivalente à la métacommande
\i.
Si nomfichier est un -
(tiret), alors l'entrée standard est lue jusqu'à la détection d'une fin
de fichier ou de la métacommande \q. Ceci peut être
utilisé pour intercaler une saisie interactive entre des entrées depuis
des fichiers. Néanmoins,
notez que Readline n'est pas utilisé dans ce cas (un peu comme si
-n a été précisé).
Utiliser cette option est légèrement différent d'écrire psql
< . En
général, les deux feront ce que vous souhaitez, mais utiliser
nomfichier-f active certaines fonctionnalités intéressantes
comme les messages d'erreur avec les numéros de ligne. Il y a aussi une
petite chance qu'utiliser cette option réduira la charge au démarrage.
D'un autre côté, la variante utilisant la redirection de l'entrée du shell
doit (en théorie) pour ramener exactement le même affichage que
celui que vous auriez eu en saisissant tout manuellement.
-F séparateur--field-separator=séparateur
Utilisez séparateur comme
champ séparateur pour un affichage non aligné. Ceci est équivalent à
\pset fieldsep ou \f.
-h nomhôte--host=nomhôteIndique le nom d'hôte de la machine sur lequel le serveur est en cours d'exécution. Si la valeur commence avec un slash, elle est utilisée comme répertoire du socket de domaine Unix.
-H--html
Active l'affichage en tableau HTML. Ceci est
équivalent à \pset format html ou à la commande
\H.
-l--list
Liste toutes les bases de données disponibles puis quitte. Les autres
options non relatives à la connexion sont ignorées. Ceci est similaire
à la métacommande \list.
Quand cette option est utilisée, psql se
connectera à la base de données postgres, sauf si une
base de données différente est nommée sur la ligne de commande (via
l'option -d, via le dernier argument de la ligne de
commande, via l'enregistrement du service, mais pas via une variable
d'environnement).
-L nomfichier--log-file=nomfichier
Écrit tous les résultats des requêtes dans le fichier nomfichier en plus de la destination
habituelle.
-n--no-readlineN'utilise pas Readline pour l'édition de ligne et n'utilise pas l'historique des commandes. Ceci est utile quand on veut désactiver la gestion de la tabulation quand on copie/colle.
-o nomfichier--output=nomfichier
Dirige tous les affichages de requêtes dans le fichier nomfichier. Ceci est équivalent à la
commande \o.
-p port--port=port
Indique le port TCP ou l'extension du fichier socket de domaine local
Unix sur lequel le serveur attend les connexions. Par défaut, il s'agit de
la valeur de la variable d'environnement PGPORT ou, si elle
n'est pas initialisée, le port spécifié au moment de la compilation,
habituellement 5432.
-P affectation--pset=affectation
Vous permet de spécifier les options d'affichage dans le style de
\pset sur la ligne de commande. Notez que, ici, vous
devez séparer nom et valeur avec un signe égal au lieu d'un espace. Du
coup, pour initialiser le format d'affichage en
LaTeX, vous devez écrire
-P format=latex.
-q--quiet
Indique que psql doit travailler
silencieusement. Par défaut, il affiche des messages de bienvenue et
diverses informations. Si cette option est utilisée, rien de ceci
n'est affiché. C'est utile avec l'option -c. Ceci est
équivalent à configurer la variable QUIET à
on.
-R séparateur--record-separator=séparateur
Utilisez séparateur comme
séparateur d'enregistrement pour un affichage non aligné. Ceci est
équivalent à \pset recordsep.
-s--single-stepS'exécute en mode étape par étape. Ceci signifie qu'une intervention de l'utilisateur est nécessaire avant l'envoi de chaque commande au serveur, avec une option pour annuler l'exécution. Utilisez cette option pour déboguer des scripts.
-S--single-lineS'exécute en mode simple ligne, où un retour à la ligne termine une commande SQL, de la même façon qu'un point-virgule.
Ce mode est fourni pour ceux qui insistent pour l'avoir, mais vous n'êtes pas nécessairement encouragé à l'utiliser. En particulier, si vous mixez SQL et métacommandes sur une ligne, l'ordre d'exécution peut ne pas être toujours clair pour un utilisateur inexpérimenté.
-t--tuples-only
Désactive l'affichage des noms de colonnes, le pied de page
contenant le nombre de résultats, etc. Ceci est équivalent à la
métacommande \t ou à
\pset tuples_only.
-T options_table--table-attr=options_table
Indique les options à placer à l'intérieur d'une balise
table en HTML. Voir
\pset tableattr pour plus de détails.
-U nomutilisateur--username=nomutilisateur
Se connecte à la base de données en tant que l'utilisateur nomutilisateur au lieu de celui par
défaut. (Vous devez aussi avoir le droit de le faire, bien sûr.)
-v affectation--set=affectation--variable=affectation
Réalise une affectation de variable, comme la métacommande
\set. Notez que vous devez séparer le nom et la valeur,
s'il y en a une, par
un signe égal sur la ligne de commande. Pour désinitialiser une variable,
enlevez le signe d'égalité. Pour initialiser une variable avec une valeur
vide, utilisez le signe égal sans passer de valeur. Ces affectations
sont réalisées lors du traitement de la ligne de commande, du coup les
variables reflétant l'état de la connexion seront écrasées plus
tard.
-V--versionAffiche la version de psql et quitte.
-w--no-password
Ne demande jamais un mot de passe. Si le serveur en réclame un pour
l'authentification et qu'un mot de passe n'est pas disponible d'une autre
façon (par exemple avec le fichier .pgpass), la
tentative de connexion échouera. Cette option peut être utile pour les
scripts où aucun utilisateur n'est présent pour saisir un mot de passe.
Notez que cette option restera positionnée pour l'ensemble de la session,
et qu'elle affecte aussi l'utilisation de la métacommande
\connect en plus de la tentative de connexion
initiale.
-W--passwordForce psql à demander un mot de passe avant de se connecter à une base de données, même si le mot de passe ne sera pas utilisé.
Si le serveur requiert une authentification par mot de passe et qu'un
mot de passe n'est pas disponible par d'autres sources que le fichier
.pgpass, psql demandera
un mot de passe. Néanmoins, psql perdra une
tentative de connexion pour trouver que le serveur veut un mot de passe.
Dans certains cas, il est préférable d'ajouter l'option
-W pour éviter la tentative de connexion.
Notez que cette option sera conservée pour la session entière,
et que du coup elle affecte l'utilisation de la métacommande
\connect ainsi que la tentative de connexion
initiale.
-x--expanded
Active le mode de formatage de table étendu. Ceci est équivalent à
\x ou \pset expanded.
-X,--no-psqlrc
Ne lit pas le fichier de démarrage (ni le fichier système
psqlrc ni le ~/.psqlrc
de l'utilisateur).
-z--field-separator-zero
Configure le séparateur de champs pour une sortie non alignée avec un
octet zéro. Ceci est équivalent à \pset fieldsep_zero.
-0--record-separator-zero
Configure le séparateur d'enregistrement pour une sortie non alignée avec
un octet zéro. C'est intéressant pour l'interfacer avec
xargs -0. Ceci est équivalent à \pset
recordsep_zero.
-1--single-transaction
Cette option peut seulement être utilisée en combinaison avec une ou
plusieurs options -c et/ou -f. Cela
force psql à exécuter une commande
BEGIN avant la première option de ce type et une
commande COMMIT après la dernière, englobant la
totalité des commandes dans une seule transaction. Ceci garantit que soit
toutes les commandes réussissent, soit aucun changement n'est appliqué.
Si les commandes elles-mêmes contiennent BEGIN,
COMMIT ou ROLLBACK, cette option
n'aura pas les effets désirés. De plus, si une commande en particulier ne
peut pas être exécutée à l'intérieur d'un bloc de transaction, indiquer
cette option causera l'échec de toute la transaction.
-?--help[=thème]
Affiche de l'aide sur psql puis quitte. Le
paramètre optionnel thème
(par défaut à options) sélectionne les parties de
psql à expliquer :
commands décrit les métacommandes de
psql ; options décrit
les options en ligne de commande de
psql ; et variables
affiche de l'aide sur les variables de configuration de
psql.
psql renvoie 0 au shell s'il s'est terminé
normalement, 1 s'il y a eu une erreur fatale de son fait (par exemple :
pas assez de mémoire, fichier introuvable), 2 si la connexion au serveur
s'est interrompue et que la session n'était pas interactive,
3 si une erreur est survenue dans un script et si la variable
ON_ERROR_STOP était positionnée.
psql est une application client
PostgreSQL standard. Pour se connecter à une
base de données, vous devez connaître le nom de votre base de
données cible, le nom de l'hôte et le numéro de port du serveur ainsi que le
nom de l'utilisateur sous lequel vous voulez vous connecter.
On peut indiquer ces paramètres à psql à partir
d'options en ligne de commande, respectivement
-d, -h, -p et
-U. Si un argument est rencontré qui ne correspond à
aucune option, il sera interprété comme le nom de la base de données
(ou le nom de l'utilisateur si le nom de la base de données est déjà donné).
Toutes ces options ne sont pas requises, il y a des valeurs par défaut
convenables. Si vous omettez le nom de l'hôte,
psql se connectera via un
socket de domaine Unix à un serveur sur l'hôte local, ou par TCP/IP sur
localhost pour les machines qui n'ont pas de sockets
de domaine Unix. Le numéro de port par
défaut est déterminé au moment de la compilation. Comme le serveur de bases
de données utilise la même valeur par défaut, vous n'aurez pas besoin de
spécifier le port dans la plupart des cas. Le nom de l'utilisateur par
défaut est votre nom d'utilisateur pour le système d'exploitation,
de même pour le nom de la base de
données par défaut. Notez que vous ne pouvez pas simplement vous connecter à
n'importe quelle base de données avec n'importe quel nom d'utilisateur. Votre
administrateur de bases de données doit vous avoir informé de vos droits
d'accès.
Quand les valeurs par défaut ne sont pas idéales, vous pouvez vous
épargner de la frappe en configurant les variables d'environnement
PGDATABASE, PGHOST, PGPORT
et/ou PGUSER avec les valeurs appropriées (pour les variables
d'environnement supplémentaires, voir Section 33.14). Il
est aussi pratique d'avoir un fichier ~/.pgpass pour
éviter d'avoir régulièrement à saisir les mots de passe. Voir Section 33.15 pour plus d'informations.
Une autre façon d'indiquer les paramètres de connexion est dans une chaîne
conninfo ou une URI qui est
utilisée à la place du nom d'une
base de données. Ce mécanisme vous donne un grand contrôle sur la
connexion. Par exemple :
$psql "service=monservice sslmode=require"$psql postgresql://dbmaster:5433/mydb?sslmode=require
De cette façon, vous pouvez aussi utiliser LDAP pour la recherche de paramètres de connexion, comme décrit dans Section 33.17. Voir Section 33.1.2 pour plus d'informations sur toutes les options de connexion disponibles.
Si la connexion ne peut pas se faire, quelle qu'en soit la raison (c'est-à-dire droits non suffisants, serveur arrêté sur l'hôte cible, etc.), psql renverra une erreur et s'arrêtera.
Si l'entrée et la sortie standard correspondent à
un terminal, alors psql fixe le paramètre
d'encodage client à la valeur « auto », afin de pouvoir
détecter l'encodage approprié d'après les paramètres régionaux (définis
par la variable système LC_CTYPE pour les systèmes
Unix).
Si cela ne fonctionne pas comme attendu, il est possible de forcer
l'encodage du client en renseignant la variable d'environnement
PGCLIENTENCODING.
Dans le cas normal, psql fournit une invite avec
le nom de la base de données sur laquelle psql
est connecté suivi par la chaîne =>. Par exemple
$ psql basetest
psql (10.23)
Type "help" for help.
basetest=>
À l'invite l'utilisateur peut saisir des commandes SQL. Ordinairement, les lignes en entrée sont envoyées vers le serveur quand un point-virgule de fin de commande est saisi. Une fin de ligne ne termine pas une commande. Du coup, les commandes peuvent être saisies sur plusieurs lignes pour plus de clarté. Si la commande a été envoyée et exécutée sans erreur, ses résultats sont affichés sur l'écran.
Si des utilisateurs en qui vous n'avez pas confiance ont accès à une base
qui n'a pas adopté la
méthode sécurisée d'utilisation
des schémas, démarrez votre session en supprimant de votre
search_path les schémas ouverts en écriture au public.
On peut ajouter options=-csearch_path= à la chaîne de
connexion ou exécuter
SELECT pg_catalog.set_config('search_path', '', false)
avant toute autre commande SQL. Cette considération n'est pas propre à
psql ; elle s'applique à chaque interface qui
exécute des commandes SQL quelconques.
À chaque fois qu'une commande est exécutée, psql vérifie aussi les événements de notification générés par LISTEN et NOTIFY.
Alors que les blocs de commentaire de type C sont transmis au serveur pour traitement et suppression, les commentaires au standard SQL sont supprimés par psql.
Tout ce que vous saisissez dans psql qui commence par un antislash non échappé est une métacommande psql, traitée par psql lui-même. Ces commandes aident à rendre psql plus utile pour l'administration ou pour l'écriture de scripts. Les métacommandes sont plus souvent appelées les commandes slash ou antislash.
Le format d'une commande psql est l'antislash suivi immédiatement d'un verbe de commande et de ses arguments. Les arguments sont séparés du verbe de la commande et les uns des autres par un nombre illimité d'espaces blancs.
Pour inclure des espaces blancs dans un argument, vous pouvez le mettre
entre des guillemets simples. Pour inclure un guillemet simple dans un
argument, vous devez écrire deux guillemets simples dans un texte compris
entre guillemets simples. Tout ce qui est contenu dans des guillemets
simples est sujet aux substitutions du style langage C :
\n (nouvelle ligne), \t (tabulation),
\b (retour arrière), \r (retour
chariot), \f (saut de page),
\chiffres (octal), and
\xchiffres (hexadécimal).
Un antislash précédant tout autre caractère dans une chaîne entre guillemets
reproduit ce caractère, quel qu'il soit.
Si un deux-points sans guillemets (:) suivi d'un nom
de variable psql apparaît dans un argument,
il est remplacé par la valeur de la variable, comme décrit dans Interpolation SQL.
Les formes :' et
variable_name':" décrites ici
fonctionnent également.
variable_name"
Dans un argument, le texte entre des guillemets inverses
(`) est pris comme une ligne de commande, qui est passée
au shell. La sortie de la commande (dont tous les retours à la ligne sont
supprimés) remplace le texte entre guillemets inverses.
Dans le texte à l'intérieur des guillemets inverses, ne se déroule
ni échappement ni autre traitement, à l'exception de
: où
variable_namevariable_name est une
variable psql, qui sera remplacée par sa valeur.
De plus, les occurences de
:' sont
remplacées par la valeur de la variable correctement échappée pour devenir
un unique argument de commande shell (cette dernière forme est presque
toujours préférable, sauf à être absolument sûr du contenu de la
variable). Comme les caractères retour chariot et saut de ligne ne
peuvent être échappés correctement sur toutes les plateformes, la
forme variable_name':' renvoie
un message d'erreur et ne remplace pas la valeur de la variable quand ces
caractères sont présents dans la valeur.
variable_name'
Quelques commandes prennent un identifiant SQL (comme un
nom de table) en argument. Ces arguments suivent les règles de la syntaxe
SQL : les lettres sans guillemets sont forcées en
minuscule alors que les guillemets doubles (") protègent les
lettres de la conversion de casse et autorisent l'incorporation d'espaces
blancs dans l'identifiant. À l'intérieur des guillemets doubles, les
guillemets doubles en paire se réduisent à un seul guillemet double dans le nom
résultant. Par exemple, FOO"BAR"BAZ est interprété comme
fooBARbaz et "Un nom ""bizarre" devient
Un nom "bizarre.
L'analyse des arguments se termine à la fin de la ligne ou quand un autre
antislash non entre guillemets est rencontré. Un antislash non entre
guillemets est pris pour le début d'une nouvelle
métacommande. La séquence spéciale \\ (deux antislashes)
marque la fin des arguments et continue l'analyse des commandes
SQL, si elles existent. De cette façon, les commandes
SQL et psql peuvent être
mixées librement sur une ligne. Mais dans tous les cas, les arguments d'une
métacommande ne peuvent pas continuer après la fin de la ligne.
De nombreuses métacommandes utilisent le buffer de la requête actuelle. Ce buffer contient simplement le texte de la commande SQL qui a été écrite mais pas encore envoyée au serveur pour exécution. Cela comprendra les lignes saisies précédentes ainsi que tout texte présent avant la métacommande de la même ligne.
Les métacommandes suivantes sont définies :
\a
Si le format d'affichage de table actuel est non aligné, il est
basculé à aligné. S'il n'est pas non aligné, il devient non aligné.
Cette commande est conservée pour des raisons de compatibilité. Voir
\pset pour une solution plus générale.
\c ou \connect [ -reuse-previous=on|off ] [ nom_base [ nom_utilisateur ] [ hôte ] [ port ] | conninfo ]
Établit une nouvelle connexion à un serveur
PostgreSQL. Les paramètres de connexion
utilisés peuvent être spécifiés en utilisant soit la syntaxe par
position (une ou plusieurs parmi le nom de la base, le nom de
l'utilisateur, l'hôte et le port) soit une chaîne de connexion
conninfo telle qu'elle est détaillée dans Section 33.1.1. Si aucun argument n'est donné, une
nouvelle connexion est réalisée en utilisant les mêmes paramètres
qu'auparavant.
Utiliser - comme valeur d'un des paramètres
nom_base, nom_utilisateur, hôte ou port est équivalent à l'omission de ce
paramètre.
La nouvelle connexion peut réutiliser les paramètres de connexion de
la précédente connexion ; non seulement le nom de la base, de
l'utilisateur, l'hôte et le port, mais aussi les autres paramètres
tels que sslmode. Par défaut, les
paramètres sont ré-utilisés dans la syntaxe par position, mais pas
quand une chaîne de connexion conninfo est
donnée. Passer en premier argument
-reuse-previous=on ou
-reuse-previous=off surcharge ce comportement par
défaut. Si les paramètres sont ré-utilisés, alors tout paramètre non
spécifié explicitement comme un paramètre de position ou dans une
chaîne de connexion conninfo est pris dans
les paramètres de la connexion existante. Une exception concerne le
changement du paramètre host de sa valeur
précédente utilisant la syntaxe par position, et tout paramétrage de
hostaddr présent dans les paramètres de la
connexion existant est supprimé. De plus, tout mot de passe utilisé
pour la connexion existante sera réutilisé seulement si l'utilisateur,
l'hôte et le port ne sont pas modifiés. Quand la commande ne spécifie
pas ou ne réutilise pas une paramètre particulier, sa valeur
libpq par défaut est utilisé.
Si la nouvelle connexion est réussie, la connexion précédente est fermée. Si la tentative de connexion échoue (mauvais nom d'utilisateur, accès refusé, etc.), la connexion précédente est conservée si psql est en mode interactif. Lors de l'exécution d'un script non interactif, le traitement s'arrêtera immédiatement avec une erreur. Cette distinction a été choisie d'une part comme facilité pour l'utilisateur confronté aux fautes de frappe, d'autre part en tant que sécurité pour que des scripts n'agissent pas par erreur sur la mauvaise base de données.
Exemples :
=> \c mydb myuser host.dom 6432
=> \c service=foo
=> \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable"
=> \c -reuse-previous=on sslmode=require -- change uniquement sslmode
=> \c postgresql://tom@localhost/mydb?application_name=myapp
\C [ titre ]
Initialise ou supprime le titre des tables affichées en
résultat d'une requête. Cette commande
est équivalente à \pset title . (Le nom de cette
commande provient de « caption », car elle avait précédemment
pour seul but d'initialiser l'en-tête dans une table
HTML.)
titre
\cd [ répertoire ]
Change le répertoire courant en
répertoire. Sans argument, le
répertoire personnel de l'utilisateur devient le répertoire courant.
Pour afficher votre répertoire courant, utilisez
\! pwd.
\conninfoAffiche des informations sur la connexion en cours à la base de données.
\copy { table [ ( liste_colonnes ) ] | ( requête ) }
{ from | to }
{ 'nomfichier' | program 'commande' | stdin | stdout | pstdin | pstdout }
[ [ with ] ( option [, ...] ) ]Réalise une opération de copie côté client. C'est une opération qui exécute une commande SQL, COPY, mais au lieu que le serveur lise ou écrive le fichier spécifié, psql lit ou écrit le fichier en faisant le routage des données entre le serveur et le système de fichiers local. Ceci signifie que l'accès et les droits du fichier sont ceux de l'utilisateur local, pas celui du serveur, et qu'aucun droit de superutilisateur n'est requis.
Quand la clause program est présente,
commande est exécuté par
psql et les données provenant ou fournies à
commande sont routées entre
le serveur et le client. Encore une fois, les droits d'exécution sont
ceux de l'utilisateur local, et non du serveur, et les droits
superutilisateur ne sont pas nécessaires.
Pour \copy ... from stdin, les lignes de données
sont lues depuis la même source qui a exécuté la commande, continuant
jusqu'à ce que \. soit lu ou que le flux atteigne
EOF. Cette option est utile pour remplir des tables
depuis les scripts SQL même.
Pour \copy ... to stdout, la sortie est envoyée au
même endroit que la sortie des commandespsql,
et le statut de la commande COPY n'est pas affiché (puisqu'il pourrait être
confondu avec une ligne de données).
Pour lire et écrire sur les entrées et sorties de psql
sans prendre en compte la source de commande courante ou
l'option count
\o, écrivez
from pstdin ou to pstdout.
La syntaxe de cette commande est similaire à celle de la commande
SQL COPY.
Toutes les options autres que les source/destination des données sont
spécifié comme pour COPY.
À cause de cela, des règles spéciales d'analyse sont appliquées à la
métacommande \copy. Contrairement à la majorité des
autres métacommandes, l'intégralité du reste de la ligne est toujours
pris en compte en tant qu'arguments de \copy,
et ni l'interpolation des variables ni la substitution par guillemets
inverses ne seront effectuées sur les arguments.
Une autre façon d'obtenir le même résultat que \copy ...
to est d'utiliser la commande SQL
COPY ... TO STDOUT et de la finir avec \g
ou nom_fichier\g
|. Contrairement à
programme\copy, cette méthode permet à la commande d'aller
sur plusieurs lignes. De plus, l'interpolation de variable et
l'expansion des guillemets inverses peuvent être utilisées.
Ces opérations ne sont pas aussi efficaces que la commande
SQL COPY avec un fichier ou
avec les données fournies pour/par un programme car toutes les
données doivent passer via la connexion client/serveur. Pour les
grandes quantités de données, la commande SQL
pourrait être préférable.
\copyrightAffiche le copyright et les termes de distribution de PostgreSQL.
\crosstabview [
colV
[ colH
[ colD
[ sortcolH
] ] ] ]
Exécute le tampon de requête actuel (tout comme \g)
et affiche le résultat dans un tableau croisé. La requête doit
renvoyer au moins trois colonnes. La colonne en sortie identifiée par
colV devient l'en-tête
vertical et la colonne en sortie identifiée par colH devient l'en-tête horizontal.
colD identifie la colonne
en sortie à afficher à l'intérieur de la grille. sortcolH identifie une colonne
optionnelle de tri pour l'en-tête horizontal.
Chaque spécification de colonne peut être un numéro de colonne (en
commençant à 1) ou un nom de colonne. Les règles SQL habituelles de
casse et de guillemet s'appliquent aux noms de colonne. En cas
d'omission, la colonne 1 est utilisée pour colV et la colonne 2 est utilisée pour
colH. colH doit différer de colV. Si colD n'est pas indiqué, alors il doit
y avoir exactement trois colonnes dans le résultat de la requête et la
colonne qui n'est ni colV
ni colH est utilisée pour
colD.
L'en-tête vertical, affiché comme colonne la plus à gauche, contient les valeurs
trouvées dans la colonne colV, dans
le même ordre que dans les résultats de la requête, mais sans les duplicats.
L'en-tête horizontal, affiché comme la première ligne, contient les valeurs
trouvées dans la colonne colH,
sans duplicats. Par défaut, ils apparaissent dans le même ordre que les
résultats de la requête. Mais si l'argument optionnel
sortcolH est renseigné, il
identifie une colonne dont les valeurs doivent être des entiers et les
valeurs provenant de colH
apparaîtront dans l'en-tête horizontal trié suivant les valeurs correspondantes
de sortcolH.
À l'intérieur du tableau croisé, pour chaque valeur
x distincte de colH et pour chaque valeur
y distincte de colV, la cellule située à
l'intersection (x,y) contient la valeur de la
colonne colD dans la ligne de résultat de la
requête pour laquelle la valeur de colH est x et la
valeur de colV est
y. Si cette ligne n'existe pas, la cellule est
vide. S'il existe plusieurs lignes, une erreur est renvoyée.
\d[S+] [ motif ]
Pour chaque relation (table, vue, vue matérialisée, index, séquence ou
table distante) ou type composite correspondant au
motif, affiche toutes les
colonnes, leurs types, le tablespace (s'il ne s'agit pas du tablespace
par défaut) et tout attribut spécial tel que NOT
NULL ou les valeurs par défaut. Les index, contraintes, règles
et déclencheurs associés sont aussi affichés. Pour les tables distantes,
le serveur distant associé est aussi affiché. (Ce qui
« correspond au motif » est défini dans
motifs
ci-dessous.)
Pour certains type de relation, \d affiche des informations
supplémentaires pour chaque colonne ; colonne valeur pour les séquences,
expression indexée pour les index, options du wrapper de données distantes
pour les tables distantes.
Le forme de la commande \d+ est identique, sauf que
des informations plus complètes sont affichées : tout commentaire associé avec
les colonnes de la table est affiché, ainsi que la présence d'OID dans
la table, la définition de la vue (si la relation ciblée est une vue), un
réglage de replica
identity autre que celui par défaut.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
Si \d est utilisé sans argument
motif, il est équivalent,
en plus commode, à \dtvmsE qui affiche une liste de
toutes les tables, vues, vues matérialisées, séquences et tables
distantes. Ce n'est qu'un outil pratique.
\da[S] [ motif ]
Liste toutes les fonctions d'agrégat disponibles, avec le type en retour
et les types de données sur lesquels elles opèrent. Si motif est spécifié, seuls les agrégats
dont les noms commencent par le motif sont affichés.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
\dA[+] [ motif ]
Liste les méthodes d'accès. Si motif est précisé, seules sont
affichées les méthodes d'accès dont le nom correspond au motif. Si
+ est ajouté au nom de la commande, chaque méthode
d'accès est listée avec sa fonction gestionnaire et sa description
associées.
\db[+] [ motif ]
Liste tous les tablespaces disponibles. Si motif est spécifié, seuls les
tablespaces dont le nom correspond au motif sont affichés. Si
+ est ajouté au nom de commande, chaque tablespace
est listé avec ses options associées, sa taille sur disque, ses droits
et sa description.
\dc[S+] [ motif ]
Liste les conversions entre les encodages de
jeux de caractères. Si motif est spécifié, seules les
conversions dont le nom correspond au motif sont listées.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
Si + est ajouté au nom de la commande, chaque objet
est listé avec sa description associée.
\dC[+] [ motif ]
Liste les conversions de types.
Si motif est indiqué,
seules sont affichées les conversions dont le type source ou cible
correspond au motif.
Si + est ajouté au nom de la commande, chaque objet
est listé avec sa description associée.
\dd[S] [ motif ]
Affiche les descriptions des objets du type contrainte,
classe d'opérateur, famille d'opérateur,
règle et trigger. Tous les autres
commentaires peuvent être visualisés avec les commandes antislash
respectives pour ces types d'objets.
\dd Affiche les descriptions des objets correspondant au motif ou des objets du type
approprié si aucun
argument n'est donné. Mais dans tous les cas, seuls les objets qui ont
une description sont listés.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
Les descriptions des objets peuvent être créées avec la commande SQL COMMENT.
\dD[S+] [ motif ]
Liste les domaines. Si motif est spécifié, seuls les
domaines dont le nom correspond au motif sont affichés.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
Si + est ajouté au nom de la commande, chaque objet
est listé avec sa description associée.
\ddp [ motif ]
Liste les paramètres par défaut pour les privilèges d'accès. Une entrée est affichée pour chaque rôle
(et schéma, si c'est approprié) pour lequel les paramètres
par défaut des privilèges ont été modifiés par rapport aux paramètres par défaut intégrés.
Si motif est
spécifié, seules les entrées dont le nom de rôle ou le nom de schéma
correspond au motif sont listées.
La commande ALTER DEFAULT PRIVILEGES sert à positionner les privilèges d'accès par défaut. La signification de l'affichage des privilèges est expliquée à la page de GRANT.
\dE[S+] [ motif ]\di[S+] [ motif ]\dm[S+] [ motif ]\ds[S+] [ motif ]\dt[S+] [ motif ]\dv[S+] [ motif ]
Dans ce groupe de commandes, les lettres E,
i, m, s,
t et v
correspondent respectivement à table distante, index, vue matérialisée,
séquence, table et vue.
Vous pouvez indiquer n'importe quelle combinaison de ces lettres, dans
n'importe quel ordre, pour obtenir la liste de tous les objets
de ces types. Par exemple, \dit liste les index et
tables. Si + est ajouté à la fin de la commande, chaque
objet est listé avec sa taille physique sur disque et sa description
associée s'il y en a une.
Si motif est spécifié,
seuls les objets dont les noms correspondent au motif sont listés.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
\des[+] [ motif ]
Liste les serveurs distants (mnémonique : « external
servers »).
Si motif est
spécifié, seuls les serveurs dont le nom correspond au motif sont
affichés. Si la forme \des+ est utilisée, une description
complète de chaque serveur est affichée, incluant liste de contrôle
d'accès du serveur (ACL), type, version, options et description.
\det[+] [ motif ]
Liste les tables distantes (mnémotechnique : « tables externes »).
Si un motif est fourni, seules les entrées
concernant les tables ou les schémas en correspondance seront listées. Si vous utilisez la
forme \det+, les options génériques et la description de la table distante seront également affichées.
\deu[+] [ motif ]
Liste les correspondances d'utilisateurs (mnémonique :
« external users »).
Si motif est
spécifié, seules les correspondances dont le nom correspond au motif sont
affichées. Si la forme \deu+ est utilisée, des
informations supplémentaires sur chaque correspondance d'utilisateur
sont affichées.
\deu+ risque aussi d'afficher le nom et le mot de
passe de l'utilisateur distant, il est donc important de faire attention
à ne pas les divulguer.
\dew[+] [ motif ]
Liste les wrappers de données distantes (mnémonique : « external
wrappers »).
Si motif est
spécifié, seuls les wrappers dont le nom correspond au motif sont
affichés. Si la forme \dew+ est utilisée, les ACL,
options et description du wrapper sont aussi affichées.
\df[antwS+] [ motif ]
Liste les fonctions, ainsi que leurs types de données pour le résultat, leurs
types de données pour les arguments et les
types de fonctions, qui sont classés comme « agg » (agrégat),
« normal », « trigger », or « window ».
Afin de n'afficher que les fonctions d'un type spécifié,
ajoutez les lettres correspondantes, respectivement a,
n, t, or w à la commande. Si motif est
spécifié, seules les fonctions dont le nom correspond au motif sont
affichées.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
Si la forme \df+ est utilisée, des informations
supplémentaires sur chaque fonction sont affichées, incluant la
volatibilité, le parallélisme, le propriétaire, la classification en
sécurité, les droits d'accès, le langage, le code source et la
description.
Pour rechercher des fonctions prenant des arguments ou des valeurs de
retour d'un type spécifique, utilisez les capacités de recherche du
paginateur pour parcourir la sortie de \df.
\dF[+] [ motif ]
Liste les configurations de la recherche plein texte.
Si motif est spécifié,
seules les configurations dont le nom correspond au motif seront
affichées. Si la forme \dF+ est utilisée, une
description complète de chaque configuration est affichée, ceci
incluant l'analyseur de recherche plein texte et la liste de dictionnaire
pour chaque type de jeton de l'analyseur.
\dFd[+] [ motif ]
Liste les dictionnaires de la recherche plein texte.
Si motif est spécifié,
seuls les dictionnaires dont le nom correspond au motif seront
affichés. Si la forme \dFd+ est utilisée, des
informations supplémentaires sont affichées pour chaque dictionnaire,
ceci incluant le motif de recherche plein texte et les valeurs des
options.
\dFp[+] [ motif ]
Liste les analyseurs de la recherche plein texte.
Si motif est spécifié,
seuls les analyseurs dont le nom correspond au motif seront
affichés. Si la forme \dFp+ est utilisée, une
description complète de chaque analyseur est affichée,
ceci incluant les fonctions sous-jacentes et la liste des types de jeton
reconnus.
\dFt[+] [ motif ]
Liste les motifs de la recherche plein texte.
Si motif est spécifié,
seuls les motifs dont le nom correspond au motif seront
affichés. Si la forme \dFt+ est utilisée, des
informations supplémentaires sont affichées pour chaque motif, ceci
incluant les noms des fonctions sous-jacentes.
\dg[S+] [ pattern ]
Liste les rôles des bases de données.
(Comme les concepts d'« utilisateurs » et « groupes »
ont été unifiés dans les « rôles », cette commande est
maintenant équivalente à \du.)
Par défaut, seuls les rôles créés par des utilisateurs sont affichés ;
ajoutez le modificateur S pour inclure les rôles
système. Si motif est spécifié, seuls les rôles
dont le nom correspond au motif sont listés.
Si la forme \dg+ est utilisée, des informations
supplémentaires sont affichées pour chaque rôle ; actuellement,
cela ajoute le commentaire pour chaque rôle.
\dl
Ceci est un alias pour \lo_list, qui affiche une
liste des Large Objects.
\dL[S+] [ motif ]
Affiche les langages procéduraux.
Si un motif est spécifié,
seuls les langages dont les noms correspondent au motif sont listés.
Par défaut, seuls les langages créés par les utilisateurs sont affichés ; il faut
spécifier l'option S pour inclure les objets système.
Si + est ajouté à la fin de la commande, chaque
langage sera affiché avec ses gestionnaire d'appels, validateur, droits
d'accès, et ce même s'il s'agit d'un objet système.
\dn[S+] [ motif ]
Liste les schémas (espaces de noms). Si motif est
spécifié, seuls les schémas dont le nom correspond au motif sont
listés.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
Si + est ajouté à la fin de la commande, chaque
objet sera affiché avec ses droits et son éventuelle description.
\do[S+] [ motif
]
Liste les opérateurs avec les types de leur opérande et résultat.
Si motif est
spécifié, seuls les opérateurs dont le nom correspond au motif sont
listés.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
Si + est ajouté au nom de la commande, des
informations supplémentaire sur chaque opérateur est affiché,
actuellement uniquement le nom de la fonction sous-jacente.
\dO[S+] [ motif ]
Affiche les collationnements.
Si motif est
spécifié, seuls les collationnements dont le nom correspond au
motif sont listés. Par défaut, seuls les objets créés par les utilisateurs
sont affichés ; fournissez un motif ou le modificateur S
pour afficher les objets système. Si + est ajouté à la fin
de la commande, chacun des collationnements sera affiché avec son éventuelle
description.
Notez que seuls les collationnements compatibles avec l'encodage de la base de
données courante sont affichés, les résultats peuvent donc varier selon les
différentes bases d'une même instance.
\dp [ motif ]
Liste les tables, vues et séquences
avec leur droits d'accès associés. Si motif est spécifié, seules les tables,
vues et séquences dont le nom correspond au motif sont listées.
Les commandes GRANT et REVOKE sont utilisées pour configurer les droits d'accès. Les explications sur le sens de l'affichage des privilèges sont sous GRANT.
\drds [ role-pattern [ database-pattern ] ]
Liste les paramètres de configuration définis. Ces paramètres peuvent
être spécifiques à un rôle, spécifiques à une base, ou les deux.
role-pattern et
database-pattern servent à choisir sur quels rôles
spécifiques ou quelles bases de données les paramètres sont listés. Si ces options sont
omises, ou si on spécifie *, tous les paramètres sont listés, y
compris ceux qui ne sont pas spécifiques, respectivement, à un rôle ou
une base.
Les commande ALTER ROLE et ALTER DATABASE servent à définir les paramètres de configuration par rôle et par base de données.
\dRp[+] [ pattern ]
Liste les publications de réplication.
Si pattern est spécifié,
seules les publications dont le nom correspond au motif sont listées.
Si + est ajouté à la fin du nom de la commande, les
tables associées à chaque publication sont également affichées.
\dRs[+] [ pattern ]
Liste les souscriptions de réplication.
Si pattern est spécifié,
seules les souscriptions dont le nom correspond au motif sont
listées.
Si + est ajouté à la fin du nom de la commande, des
propriétés supplémentaires de la souscription sont affichées.
\dT[S+] [ motif ]
Liste les types de données.
Si motif est
spécifié, seuls les types dont le nom correspond au motif sont
affichés. Si + est ajouté à la fin de la commande,
chaque type est listé avec son nom interne et sa taille, ses
valeurs autorisées si c'est un type enum, et ses permissions
associées.
Par défaut, seuls les objets créés par les utilisateurs sont affichés ;
fournissez un motif ou le modificateur S pour afficher
les objets système.
\du[S+] [ pattern ]
Liste les rôles de la base de données.
(Depuis que les concepts des « utilisateurs » et « groupes »
ont été unifiés en des « rôles », cette commande est équivalent à
\dg.)
Par défaut, seuls les rôles créés par des utilisateurs sont affichés.
Ajoutez le modificateur S pour inclure les rôles
système.
Si motif est indiqué,
seuls les rôles dont le nom correspond au motif sont listés. Si la
forme \du+ est utilisée, des informations
supplémentaires sont affichées pour chaque rôle ; actuellement,
cela ajoute le commentaire pour chaque rôle.
\dx[+] [ motif ]
Affiche les extensions installées.
Si motif est
spécifié, seules les entensions dont le nom correspond au motif sont affichées.
Avec la forme \dx+, tous les objets dépendants de chacune
des extensions correspondantes sont également listés.
\dy[+] [ motif ]
Liste les triggers d'événements. Si motif est indiqué, seuls les triggers
d'événements dont les noms correspondent au motif sont listés. Si
+ est ajouté au nom de la commande, chaque objet est
listé avec sa description.
\e (or \edit) [ nomfichier ] [ numero_ligne ]
Si nomfichier est
spécifié, le fichier est édité ; en quittant l'éditeur, le contenu
du fichier est recopié dans le tampon de requête. Si aucun paramètre nomfichier
n'est fourni, le tampon de requête courant est copié dans un fichier
temporaire qui édité de la même manière. Ou bien, si le tampon actuel de
requête est vide, la dernière requête exécutée est copiée vers un
fichier temporaire et éditée de la même manière.
Le nouveau tampon de requête est ensuite ré-analysé suivant les règles
habituelles de psql, où le tampon complet est
traité comme une seule ligne. Toute requête complète est exécutée
immédiatemment ; c'est-à-dire que si le tampon de requête contient ou se
termine par un point-virgule, tout ce qui précède est exécuté. Tout ce
qui reste attendra dans le tampon de requête ; en tapant point-virgule
ou \g, le contenu sera envoyé, tandis que
\r annulera en effaçant le tampon de requête.
Traiter le buffer comme une ligne unique affecte principalement les
métacommandes : tout ce qui se trouve dans le tampon après une
métacommande sera pris en tant qu'argument(s) de la métacommande, même
si cela s'étend sur plusieurs lignes (du coup, vous ne pouvez pas faire
de scripts de cette façon. Utilisez \i pour cela).
Si vous indiquez un numéro de ligne, psql positionnera le curseur sur cette ligne du fichier ou du tampon de requête. Notez que si un seul argument comportant uniquement des caractères numériques est fourni à la commande, psql considère qu'il s'agit d'un numéro de ligne, et non pas un nom de fichier.
Voir dans Environnement comment configurer et personnaliser votre éditeur.
\echo texte [ ... ]Affiche les arguments sur la sortie standard, séparés par un espace et suivis par une nouvelle ligne. Ceci peut être utile pour intégrer des informations sur la sortie des scripts. Par exemple :
=> \echo `date`
Tue Oct 26 21:40:57 CEST 1999
Si le premier argument est -n sans guillemets,
alors la fin de ligne n'est pas écrite.
Si vous utilisez la commande \o pour rediriger la
sortie de la requête, vous pouvez aussi utiliser
\qecho au lieu de cette commande.
\ef [ description_fonction [ line_number ] ]
Cette commande récupère et édite la définition de la fonction
désignée sous la forme d'une commande CREATE OR REPLACE
FUNCTION.
L'édition est faite de la même façon que pour \edit.
Une fois l'éditeur fermé, la commande mise à jour attend
dans le tampon de requête ; tapez ; ou
\g pour l'envoyer, ou \r pour
l'annuler.
La fonction cible peut être spécifiée par son nom seul, ou par son
nom et ses arguments, par exemple foo(integer, text).
Les types d'arguments doivent être fournis s'il y a plus d'une fonction
du même nom.
Si aucune fonction n'est spécifiée, un modèle d'ordre CREATE
FUNCTION vierge est affiché pour édition.
Si vous indiquez un numéro de ligne, psql positionnera le curseur sur cette ligne dans le corps de la fonction. (Notez que le corps de la fonction, typiquement, ne commence pas sur la première ligne du fichier.)
Contrairement à la plupart des autres métacommandes, l'intégralité du
reste de la ligne est toujours pris en compte en tant qu'argument(s)
de \ef, et ni l'interpolation des variables ni la
substitution par guillemets inverses ne seront effectuées sur les
arguments.
Voir dans Environnement la façon de configurer et personnaliser votre éditeur.
\encoding [ codage ]Initialise l'encodage du jeu de caractères du client. Sans argument, cette commande affiche l'encodage actuel.
\errverbose
Répète le message d'erreur le plus récent avec une verbosité maximale,
comme si VERBOSITY était configuré à
verbose et SHOW_CONTEXT à
always
\ev [ nom_vue [ numero_ligne ] ]
Cette commande récupère et édite la définition de la vue désignée, sous
la forme d'une commande CREATE OR REPLACE VIEW.
L'édition se termine de la même façon que pour
\edit. Après avoir quitté l'éditeur, la commande
mise à jour attend dans le tampon de requête ; saisir un point-
virgule ou \g pour l'envoyer, ou
\r pour annuler.
Si aucune vue n'est indiquée, un CREATE VIEW modèle
est présenté pour l'édition.
Si un numéro de ligne est indiqué, psql positionnera le curseur sur la ligne indiquée pour la définition de la vue.
Contrairement à la majorité des autres métacommandes, l'intégralité du
reste de la ligne est toujours pris en compte en tant qu'arguments
de \ev, et ni l'interpolation des variables ni la
substitution par guillemets inverses ne seront effectuées sur les
arguments.
\f [ chaîne ]
Initialise le champ séparateur pour la sortie de requête non alignée.
La valeur par défaut est la barre verticale (|). C'est
équivalent à \pset fieldsep.
\g [ nomfichier ]\g [ |commande ]
Envoie le tampon de requête en entrée vers le serveur et stocke en
option la sortie de la requête dans
nomfichier
ou envoie dans un tube (pipe)
la sortie vers un autre shell exécutant
commande au lieu de
l'exécuter comme habituellement. Le fichier ou la commande
n'est écrit que si la requête renvoit zéro ou plus
enregistrements, mais pas si la requête échoue ou s'il s'agit d'une
commande SQL ne renvoyant pas de données.
Si le tampon de la requête est vide, la dernière requête envoyée est
ré-exécutée à la place. En dehors de cette exception, \g
sans argument est essentiellement équivalent à un point-virgule.
Un \g avec argument est une alternative ponctuelle
à la commande \o.
Si l'argument débute par |, alors l'intégralité du
reste de la ligne est pris en tant que
commande à exécuter
et ni l'interpolation des variables ni la substitution par guillemets
inverses n'y sont effectuées. Le reste de la ligne est simplement
passé littéralement au shell.
\gexec
Envoie le tampon de requête actuel au serveur, puis traite chaque
colonne de chaque ligne du résultat de la requête (s'il y en a)
comme une requête à
exécuter. Par exemple, pour créer un index sur chaque colonne de
ma_table :
=>SELECT format('create index on ma_table(%I)', attname)->FROM pg_attribute->WHERE attrelid = 'ma_table'::regclass AND attnum > 0->ORDER BY attnum->\gexecCREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX
Les requêtes générées sont exécutées dans l'ordre dans lequel les lignes sont
renvoyées, et de gauche à droite sur chaque ligne s'il y a plus d'une
colonne. Les champs NULL sont ignorés. Les requêtes générées sont
envoyées litéralement au serveur pour traitement, donc elles ne
peuvent pas être des métacommandes psql ni
contenir des références de variables psql.
Si une requête individuelle échoue, l'exécution des requêtes suivantes
continue, sauf si ON_ERROR_STOP est configuré.
L'exécution de chaque requête est sujette au traitement de
ECHO. (Configurer ECHO à
all ou à queries est souvent
conseillé lors de l'utilisation de \gexec.) La
trace de requêtes, le mode étape par étape, le chronométrage et les
autres fonctionnalités d'exécution des requêtes s'appliquent aussi à
chaque requête générée.
Si le tampon de requête courant est vide, la dernière requête envoyée est ré-exécutée à la place.
\gset [ préfixe ]Envoie la requête courante du tampon au serveur et stocke le résultat de la requête dans des variables psql (voir Variables). La requête à exécuter doit renvoyer exactement une ligne. Chaque colonne de la ligne est enregistrée dans une variable séparée, nommée de la même façon que la colonne. Par exemple :
=>SELECT 'bonjour' AS var1, 10 AS var2->\gset=>\echo :var1 :var2bonjour 10
Si vous précisez un préfixe préfixe, cette chaîne est ajoutée aux
noms de colonne de la requête pour créer les noms de variable à
utiliser :
=>SELECT 'bonjour' AS var1, 10 AS var2->\gset result_=>\echo :result_var1 :result_var2bonjour 10
Si le résultat d'une colonne est NULL, la variable correspondante n'est pas initialisée.
Si la requête échoue ou ne renvoie pas une ligne, aucune variable n'est modifiée.
Si le tampon de requête courant est vide, la dernière requête envoyée est ré-exécutée à la place.
\gx [ filename ]\gx [ |command ]
\gx est équivalent à \g, mais
force l'affichage étendu pour cette requête. Voir \x.
\h (ou \help) [
commande ]
Fournit la syntaxe sur la commande SQL spécifiée. Si
commande n'est pas
spécifiée, alors psql liste toutes les
commandes pour lesquelles une aide en ligne est disponible. Si
commande est un astérisque
(*), alors l'aide en ligne de toutes les commandes
SQL est affichée.
Contrairement à la plupart des autres métacommandes, l'intégralité du
reste de la ligne est toujours pris en compte en tant qu'argument(s)
de \help, et ni l'interpolation des variables ni la
substitution par guillemets inverses ne seront effectuées sur les
arguments.
Pour simplifier la saisie, les commandes qui consistent en plusieurs mots
n'ont pas besoin d'être entre guillemets. Du coup, il est correct de
saisir \help alter table.
\H ou \html
Active le format d'affichage HTML des requêtes. Si
le format HTML est déjà activé, il est basculé au
format d'affichage défaut (texte aligné). Cette commande existe pour
la compatibilité et la praticité, mais voyez \pset
pour configurer les autres options d'affichage.
\i ou \include nomfichier
Lit l'entrée à partir du fichier nomfichier et l'exécute comme si elle
avait été saisie sur le clavier.
Si nomfichier est -
(tiret), l'entrée standard est lue jusqu'à une indication EOF
ou la métacommande \q. Ceci peut être utilisé
pour intercaler des entrées interactives entre des entrées de fichiers.
Notez que le comportement de Readline ne sera activé que s'il est
actif au niveau supérieur.
Si vous voulez voir les lignes sur l'écran au moment de leur lecture,
vous devez initialiser la variable ECHO à
all.
\if expression\elif expression\else\endif
Ce groupe de commandes implémente les blocs conditionnels imbriqués.
Un bloc conditionnel doit commencer par un \if et se
terminer par un \endif. Entre les deux, il peut y
avoir plusieurs clauses \elif, pouvant être suivies
facultativement par une unique clause \else. Des
requêtes ordinaires et d'autres commandes antislash peuvent apparaître
(et c'est généralement le cas) entre les commandes formant le bloc
conditionnel.
Les commandes \if et \elif
lisent leurs arguments et les évaluent en tant qu'expression booléenne.
Si l'expression renvoie true, alors le traitement
continue normalement ; sinon, les lignes sont ignorées jusqu'à un
\elif, \else, ou
\endif correspondant.
Dès qu'un test \if ou \elif a
réussi, les arguments des commandes \elif ultérieures
du même bloc ne sont pas évaluées mais sont traitées comme fausses.
Les lignes qui suivent un \else ne sont traitées
que si aucune commande \if or \elif
correspondante n'a réussie.
L'argument d'expression
d'une commande \if or \elif est
soumis à l'interpolation des variables et la substitution par guillemets
inverses, tout comme n'importe quelle autre commande antislash. Après
cela, il est évalué comme la valeur d'une variable d'option on/off.
Une valeur valide est n'importe quelle correspondance non sensible à la
case et non-ambiguë parmi :
true, false, 1,
0, on, off,
yes, no. Par exemple,
t, T et tR
seront tous considérés comme true.
Les expressions ne s'évaluant pas correctement à vrai ou faux généreront un avertissement et seront traitées comme fausses.
Les lignes qui sont évitées sont analysées syntaxiquement pour
identifier les requêtes et les commandes antislash, mais les
requêtes ne sont pas envoyées au serveur, et les commandes antislash
autres que conditionnelles
(\if, \elif,
\else, \endif) sont ignorées.
Les commandes conditionnelles sont vérifiées seulement pour valider
l'emboîtement. Les références des variables des lignes évitées ne sont
pas interpolées et les substitutions par guillemets inverses ne seront
pas effectuées non plus.
Toutes les commandes antislash d'un bloc conditionnel doivent
apparaître dans le même fichier source. Si EOF est atteint dans le
fichier d'entrée principal ou un fichier \include
avant que tous les blocs \if locaux ne soient
fermés, alors psql générera une erreur.
Voici un exemple :
-- vérifier l'existence de deux enregistrements distincts dans la base et
-- enregistrer les résultats dans deux variables psql différentes
SELECT
EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer,
EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee
\gset
\if :est_client
SELECT * FROM customer WHERE customer_id = 123;
\elif :est_employe
\echo 'est un employé mais pas un client'
SELECT * FROM employee WHERE employee_id = 456;
\else
\if yes
\echo 'ni un client ni un employé'
\else
\echo 'ce message ne s\'affichera jamais'
\endif
\endif
\ir ou \include_relative nom_fichier
La commande \ir est similaire à \i,
mais résout les chemins différemment. Lors d'une exécution en mode
interactif, les deux commandes se comportent de la même façon. Néanmoins,
lorsqu'elles sont appelées par un script, \ir
interprète les chemins à partir du répertoire où le script est enregistré,
plutôt qu'à partir du répertoire courant.
\l[+] ou \list[+] [ motif ]
Liste les bases de données du serveur en indiquant leur nom,
propriétaire, encodage de caractères, et droits d'accès.
Si pattern est spécifié,
seules les bases de données dont le nom correspond au motif sont listées.
Si + est ajouté à la fin de la commande, la taille
des bases, les tablespaces par défaut et les descriptions sont aussi
affichées. (Les tailles ne sont disponibles que pour les bases
auxquelles l'utilisateur courant a le droit de se connecter.)
\lo_export loid nomfichier
Lit l'objet large d'OID loid à partir de la base de données
et l'écrit dans nomfichier. Notez que ceci est
subtilement différent de la fonction serveur
lo_export, qui agit avec les droits de
l'utilisateur avec lequel est exécuté le serveur de base de données et
sur le système de fichiers du serveur.
Utilisez \lo_list pour trouver
l'OID de l'objet large.
\lo_import nomfichier [ commentaire ]Stocke le fichier dans un Large Object PostgreSQL. En option, il associe le commentaire donné avec l'objet. Exemple :
foo=> \lo_import '/home/pierre/pictures/photo.xcf' 'une
photo de moi'
lo_import 152801
La réponse indique que le Large Object a reçu l'ID 152801, qui peut être
utilisé pour accéder de nouveau à l'objet créé. Pour une meilleure
lisibilité, il est recommandé de toujours associer un commentaire
compréhensible par un humain avec chaque objet. Les OID et les
commentaires sont visibles avec la commande \lo_list.
Notez que cette commande est subtilement différente de la fonction
serveur lo_import car elle agit en tant
qu'utilisateur local sur le système de fichier local plutôt qu'en tant
qu'utilisateur du serveur et de son système de fichiers.
\lo_listAffiche une liste de tous les Large Objects PostgreSQL actuellement stockés dans la base de données, avec tous les commentaires fournis par eux.
\lo_unlink loid
Supprime le Large Object d'OID
loid de la base
de données.
Utilisez \lo_list pour trouver
l'OID d'un Large Object.
\o ou \out [ nomfichier ]\o ou \out [ |commande ]
S'arrange pour sauvegarder les résultats des prochaines requêtes dans
le fichier nomfichier ou
d'envoyer les résultats à la commande shell commande. Si aucun argument n'est
fourni, le résultat de la requête va sur la sortie standard.
Si l'argument commence par |, alors l'intégralité du
reste de la ligne est considérée en tant que commande
à exécuter et ni l'interpolation des variables ni la substitution par
guillemets inverses ne seront effectuées. Le reste de ligne est
simplement envoyée littéralement au shell.
Les « résultats de requête » incluent toutes les tables,
réponses de commande et messages d'avertissement obtenus du serveur de
bases de données, ainsi que la sortie de différentes commandes
antislash qui envoient des requêtes à la base de données (comme
\d), mais sans message d'erreur.
Pour intercaler du texte entre des résultats de requête, utilisez
\qecho.
\p ou \printAffiche le tampon de requête actuel sur la sortie standard. Si le tampon de requête actuel est vide, la requête la plus récemment exécutée est affichée à la place.
\password [ nom_utilisateur ]
Modifie le mot de passe de l'utilisateur indiqué (par défaut,
l'utilisateur en cours). Cette commande demande le nouveau mot de passe,
le chiffre et l'envoie au serveur avec la commande ALTER
ROLE. Ceci vous assure que le nouveau mot de passe n'apparaît
pas en clair dans l'historique de la commande, les traces du serveur
ou ailleurs.
\prompt [ texte ] nom
Demande la saisie d'un texte par l'utilisateur. Ce texte sera affecté à
la variable nom. Une
chaîne supplémentaire, texte,
peut être donnée. (Pour pouvoir saisir plusieurs mots, entourez le texte
par des guillemets simples.)
Par défaut, \prompt utilise le terminal pour les
entrées et sorties. Néanmoins, si la bascule -f est
utilisée, \prompt utilise l'entrée et la sortie
standard.
\pset [ option [ valeur ] ]
Cette commande initialise les options affectant l'affichage des tableaux
de résultat de requête. option décrit l'option à initialiser.
La sémantique de valeur varie en fonction de
l'option sélectionnée. Pour certaines options, omettre valeur a pour conséquence de basculer ou désactiver l'option,
tel que cela est décrit pour chaque option. Si aucun comportement de ce type
n'est mentionné, alors omettre valeur occasionne simplement l'affichage de la configuration actuelle.
\pset sans aucun argument affiche l'état actuel de
toutes les options d'affichage.
Les options ajustables d'affichage sont :
border
Le valeur doit être
un nombre. En général, plus grand est ce nombre, plus les tables
ont de bordures et de lignes mais ceci dépend du format. Dans le
format HTML, cela se traduira directement en un
attribut border=.... Dans la plupart des autres
formats, seules les valeurs 0 (sans bordure), 1 (lignes interne de
séparation) et 2 (cadre du tableau) ont un sens, et les valeurs
au-dessus de 2 seront traitées de la même façon que
border = 2. Les formats
latex et latex-longtable
autorisent en plus une valeur de 3 pour ajouter des lignes de
séparation entre les lignes de données.
columns
Positionne la largeur pour le format wrapped ,
ainsi que la largeur à partir de laquelle la sortie est suffisamment
longue pour nécessiter le paginateur ou pour basculer sur l'affichage
vertical dans le mode étendu automatique.
Si l'option est positionnée à zéro (la valeur par défaut), la largeur de la colonne est contrôlée
soit par la variable d'environnement COLUMNS, soit par la largeur d'écran détectée si
COLUMNS n'est pas positionnée.
De plus, si columns vaut zéro, alors le format
wrapped affecte seulement la sortie écran.
Si columns ne vaut pas zéro, alors les sorties
fichier et tubes (pipes) font
l'objet de retours à la ligne
à cette largeur également.
expanded (ou x)
Si une valeur est
précisée, elle doit être soit on soit
off, ce qui activera ou désactivera le mode
étendu, soit auto.
Si valeur est omis,
la commande bascule le paramètre entre les valeurs on et off.
Quand le mode étendu est activé, les résultats des requêtes sont
affichés sur deux colonnes, avec le nom de la colonne sur la gauche
et ses données sur la droite. Ce mode est utile si la donnée ne tient
pas sur l'écran dans le mode « horizontal » habituel. Dans
le mode auto, le mode étendu est utilisé quand la sortie de la requête
a plus d'une colonne et est plus large que l'écran. Sinon, le mode habituel
est utilisé. Le mode auto est seulement intéressant lors de
l'utilisation des formats aligné et wrapped .
Si d'autres formats sont sélectionnés, il se comporte toujours comme
si le mode étendu était désactivé.
fieldsep
Indique le séparateur de champ à utiliser dans le mode d'affichage
non aligné. De cette façon, vous pouvez créer, par exemple, une
sortie séparée par des tabulations ou des virgules, que d'autres
programmes pourraient préférer. Pour configurer une tabulation comme
champ séparateur, saisissez \pset fieldsep
'\t'. Le séparateur de champ par défaut est
'|' (une barre verticale).
fieldsep_zeroConfigure le séparateur de champs pour qu'il utilise un octet zéro dans le format non aligné en sortie.
footer
Si le paramètre valeur est précisé, il doit valoir soit
on, soit off, ce qui a pour effet d'activer
ou de désactiver l'affichage du pied de tableau (le compte : ().
Si le paramètre n rows)valeur est omis, la commande bascule entre
l'affichage du pied de table ou sa désactivation.
format
Initialise le format d'affichage parmi unaligned,
aligned, wrapped, html,
asciidoc, latex (utilise tabular),
latex-longtable ou
troff-ms.
Les abréviations uniques sont autorisées.
Le format unaligned écrit toutes les colonnes d'un enregistrement sur une seule ligne,
séparées par le séparateur de champ courant. Ceci est utile pour crééer des sorties qui doivent être
lues par d'autres programmes (au format séparé par des caractère tabulation ou par des virgules, par exemple).
Le format aligned est le format de sortie texte standard, lisible par les humains,
joliement formaté ; c'est le format par défaut.
Le format wrapped est comme aligned, sauf qu'il retourne à
la ligne dans les données de grande taille afin que la sortie tienne dans la largeur
de colonne cible. La largeur cible est déterminée comme décrit à l'option
columns. Notez que psql n'essaie pas de revenir à la ligne dans
les titres de colonnes. Par conséquent, si la largeur totale nécessaire pour le titre
de colonne est plus grande que la largeur cible, le format
wrapped se comporte de la même manière que aligned.
Les formats html, asciidoc, latex,
latex-longtable et troff-ms
produisent des tableaux destinées à être inclus dans des documents
utilisant les langages de balisage respectifs. Ce ne sont pas des
documents complets ! Ce n'est pas forcément nécessaire en
HTML mais en LaTeX,
vous devez avoir une structure de document complet.
latex-longtable nécessite aussi les paquets
LaTeX longtable et
booktabs.
linestyle
Positionne le style des lignes de bordure sur
ascii, old-ascii
unicode.
Les abréviations uniques sont autorisées. (Cela signifie qu'une
lettre suffit.)
La valeur par défaut est ascii.
Cette option affecte seulement les formats de sortie
aligned et
wrapped.
Le style ascii utilise les caractères basiques
ASCII. Les retours à la ligne dans les données
sont représentés par un symbole + dans la marge
de droite.
Quand le format wrapped déroule les données
d'une ligne à l'autre sans caractère retour à la ligne, un point
(.) est affiché dans la marge droite de la
première ligne et à nouveau dans la marge gauche de la ligne
suivante.
Le style old-ascii utilise des caractères basiques ASCII,
utilisant le style de formatage utilisé dans
PostgreSQL 8.4 and et les versions plus anciennes.
Les retours à la ligne dans les données sont représentés par un symbole :
à la place du séparateur de colonnes placé à gauche. Quand les données sont réparties sur plusieurs
lignes sans qu'il y ait de caractère de retour à la ligne dans les données, un symbole ; est utilisé
à la place du séparateur de colonne de gauche.
Le style unicode utilise les caractères Unicode de dessin de boîte.
Les retours à la ligne dans les données sont représentés par un symbole de retour à la ligne
dans la marge de droite. Lorsque les données sont réparties sur plusieurs lignes, sans qu'il y ait de caractère de retour à la ligne dans les données, le symbole ellipse est affiché dans
la marge de droite de la première ligne, et également dans la marge de gauche de la ligne suivante.
Quand le paramètre border vaut plus que zéro, l'option linestyle
détermine également les caractères utilisés pour dessiner les lignes de bordure.
Les simples caractères ASCII fonctionnent partout, mais les
caractères Unicode sont plus jolis sur les affichages qui les reconnaissent.
null
Positionne la chaîne de caractères à afficher à la place d'une valeur null.
Par défaut rien n'est affiché, ce qui peut facilement être confondu avec une
chaîne de caractères vide. Par exemple, on peut préférer
\pset null '(null)'.
numericlocale
Si valeur est précisée, elle doit valoir soit
on, soit off
afin d'activer ou désactiver l'affichage d'un caractère dépendant de la locale
pour séparer des groupes de chiffres à gauche du séparateur décimal.
Si valeur est omise, la commande bascule entre
la sortie numérique classique et celle spécifique à la locale.
pager
Contrôle l'utilisation d'un paginateur pour les requêtes et les
affichages de l'aide de psql. Si la variable
d'environnement PAGER est configurée, la sortie est
envoyée via un tube (pipe) dans
le programme spécifié. Sinon, une valeur par
défaut dépendant de la plateforme (comme more)
est utilisée.
Quand l'option pager vaut off, le paginateur
n'est pas utilisé. Quand l'option pager vaut
on, et que cela est approprié, c'est-à-dire
quand la sortie est dirigée vers un terminal et ne tient pas dans
l'écran, le paginateur est utilisé.
L'option pager peut également être positionnée à always,
ce qui a pour effet d'utiliser le paginateur pour toutes les sorties terminal,
que ces dernières tiennent ou non dans l'écran.
\pset pager,
sans préciser valeur,
bascule entre les états "paginateur activé" et "paginateur désactivé".
pager_min_lines
Si pager_min_lines est configuré à un numéro
supérieur à la hauteur de page, le programme de pagination ne sera
appelé que s'il y a au moins ce nombre de lignes à afficher.
La configuration par défaut est 0.
recordsepIndique le séparateur d'enregistrement (ligne) à utiliser dans le mode d'affichage non aligné. La valeur par défaut est un caractère de retour chariot.
recordsep_zeroConfigure le séparateur d'enregistrements pour qu'il utilise un octet zéro dans le format non aligné en sortie.
tableattr (ou T)
Dans le format HTML, ceci indique les attributs
à placer dans la balise table. Ce
pourrait être par exemple cellpadding ou
bgcolor. Notez que vous ne voulez probablement pas
spécifier border puisqu'il est déjà pris en compte
par \pset border. Si valeur n'est pas précisée, aucun
attribut de table n'est positionné.
Dans le format latex-longtable, ceci contrôle
la largeur proportionnelle de chaque colonne contenant un type de
données aligné à gauche. Il est spécifié en tant que liste de
valeurs séparées par des espaces blancs, par exemple
'0.2 0.2 0.6'. Les colonnes en sortie non
spécifiées utilisent la dernière valeur indiquée.
title (or C)
Initialise le titre de la table pour toutes les tables affichées
ensuite. Ceci peut être utilisé pour ajouter des balises de description
à l'affichage. Si aucun valeur n'est donné, le titre n'est pas
initialisé.
tuples_only (ou t)
Si valeur est spécifiée, elle doit
valoir soit on, soit off, ce qui va
activer ou désactiver le mode « tuples seulement ».
Si valeur est omise,
la commande bascule entre la sortie normale et la sortie
« tuples seulement ».
La sortie normale comprend des informations supplémentaires telles que
les en-têtes de colonnes, les titres, et différents pieds. Dans le mode
« tuples seulement », seules les données de la table sont affichées.
unicode_border_linestyle
Configure le style d'affichage de la bordure pour le style de
ligne unicode soit à single
soit à double.
unicode_column_linestyle
Configure le style d'affichage de la colonne pour le style de
ligne unicode soit à single
soit à double.
unicode_header_linestyle
Configure le style d'affichage de l'en-tête pour le style de
ligne unicode soit à single
soit à double.
Des exemples d'utilisation de ces différents formats sont disponibles dans la section Exemples.
Il existe plusieurs raccourcis de commandes pour
\pset. Voir
\a, \C, \f,
\H, \t, \T
et \x.
\q ou \quitQuitte le programme psql. Avec un script, seule l'exécution du script est terminée.
\qecho texte [ ... ]
Cette commande est identique à \echo sauf que
les affichages sont écrits dans le canal d'affichage des requêtes,
configuré par \o.
\r ou \resetRéinitialise (efface) le tampon de requêtes.
\s [ nomfichier ]
Envoie l'historique de la ligne de commandes de
psql dans nomfichier.
Si nomfichier est omis,
l'historique est écrit sur la sortie standard (en utilisant le paginateur
si approprié). Cette commande n'est pas disponible si
psql a été construit sans le support de
Readline.
\set [ nom [ valeur [ ... ]]]
Initialise la variable nom de psql à valeur ou, si plus d'une valeur est
donnée, à la concaténation de toutes les valeurs. Si un seul argument est
donné, la variable est configurée avec une valeur vide.
Pour désinitialiser une variable, utilisez la commande
\unset.
\set sans arguments affiche le nom et la valeur de toutes
les variables psql actuellement configurées.
Les noms de variables valides peuvent contenir des lettres, chiffres et tirets bas (_). Voir la section Variables ci-dessous pour les détails. Les noms des variables sont sensibles à la casse.
Certaines variables sont spéciales, dans le sens qu'elles contrôlent le comportement de psql ou qu'elles sont mises à jour pour refléter l'état de la connexion. Ces variables sont documentées plus bas dans Variables.
Cette commande est sans relation avec la commande SQL SET.
\setenv nom [ valeur ]
Configure la variable d'environnement nom à valeur, ou si la
valeur n'est pas fournie,
désinitialise la variable d'environnement. Par exemple :
testdb=>\setenv PAGER lesstestdb=>\setenv LESS -imx4F
\sf[+] description_fonction
Cette commande récupère et affiche la définition d'une fonction sous la forme d'une
commande CREATE OR REPLACE FUNCTION.
La définition est affichée via le canal de sortie courant, tel que défini par \o.
La fonction cible peut être spécifiée par son seul nom, ou bien par
ses nom et arguments, par exemple, foo(integer, text).
Fournir les types des arguments devient obligatoire si plusieurs
fonctions portent le même nom.
Si + est ajouté à la commande, les numéros de lignes
sont affichés, la ligne 1 débutant à partir du corps de la fonction.
Contrairement à la majorité des autres métacommandes, l'intégralité du
reste de la ligne est toujours pris en tant qu'argument(s) de
\sf et ni l'interpolation des variables ni la
substitution par guillemets inverses ne seront effectuées.
\sv[+] view_name
Cette commande récupère et affiche la définition de la vue nommée,
dans la forme d'une commande CREATE OR REPLACE
VIEW. La définition est affichée au travers du canal de
sortie actuel, comme configuré par \o.
Si + est ajouté au nom de commande, les lignes de
sorties sont numérotées à partir de 1.
Contrairement à la majorité des autres métacommandes, l'intégralité du
reste de la ligne est toujours pris en tant qu'argument(s) de
\sv et ni l'interpolation des variables ni la
substitution par guillemets inverses ne sont effectuées dans les arguments.
\t
Bascule l'affichage des en-têtes de nom de colonne en sortie et celle du
bas de page indiquant le nombre de lignes. Cette commande est
équivalente à \pset tuples_only et est fournie pour en
faciliter l'accès.
\T options_table
Spécifie les attributs qui seront placés dans le tag
table pour le format de sortie HTML.
Cette commande est équivalente à \pset
tableattr .
options_table
\timing [ on | off ]Avec un paramètre, affiche ou supprime l'affichage du temps d'exécution de chaque requête. Sans paramètre, commute l'affichage entre on et off. L'affichage est en millisecondes ; les intervalles plus longs qu'une seconde sont affichés au format minutes:secondes et les champs heures et jours sont ajoutés si nécessaires.
\unset nom
Désinitialise (supprime) la variable psql
nom.
La plupart des variables qui contrôlent le comportement de
psql ne peuvent pas être désinitialisées ;
la commande \unset est interprétée comme les
remettant à leur valeur par défaut.
Voir Variables
plus bas.
\w ou \write nomfichier\w ou \write |commande
Place le tampon de requête en cours dans le fichier nomfichier ou l'envoie via un tube à la
commande shell commande.
Si le tampon de requête actuel est vide, la dernière requête exécutée
est affichée à nouveau.
Si l'argument débute par |, alors l'intégralité du
reste de la ligne est pris en tant que
commande à exécuter
et ni l'interpolation des variables ni la substitution par guillemets
inverses n'y sont effectuées. Le reste de la ligne est simplement
passé littéralement au shell.
\watch [ seconds ]
Exécute en répété le tampon de requête courant (comme
\g) jusqu'à être interrompu explicitement ou que la
requête échoue. Attend le nombre spécifié de secondes (2 par défaut)
entre les exécutions. Chaque résultat de requête est affiché avec un
en-tête qui inclut la chaîne \pset title (si c'est
activé), l'heure du début de la requête, et l'intervalle.
Si le tampon de requête actuel est vide, la dernière requête envoyée est exécutée à nouveau.
\x [ on | off | auto ]
Configure ou bascule le mode étendu de formatage en table. C'est équivalent à
\pset expanded.
\z [ motif ]
Liste les tables, vues et séquences
avec leur droits d'accès associés. Si un motif est spécifié, seules les tables,
vues et séquences dont le nom correspond au motif sont listées.
Ceci est un alias pour \dp (« affichage des
droits »).
\! [ commande ]
Sans argument, échappe vers un sous-shell ; psql
reprendra quand le sous-shell se terminera. Avec un argument, exécute
la commande shell commande.
Contrairement à la majorité des autres métacommandes, l'intégralité du
reste de la ligne est toujours pris en compte en tant qu'arguments
de \!, et ni l'interpolation des variables ni la
substitution par guillemets inverses ne seront effectuées sur les
arguments. Le reste de la ligne est simplement envoyé directement au
shell.
\? [ thème ]
Affiche l'aide. Le paramètre optionnel thème (par défaut à
commands) sélectionne les parties de
psql à expliquer :
commands décrit les métacommandes de
psql ; options
décrit les options en ligne de commande de
psql ; et variables
affiche de l'aide sur les variables de configuration de
psql.
Les différentes commandes \d acceptent un paramètre
motif pour spécifier le(s)
nom(s) d'objet à afficher. Dans le cas le plus simple, un motif est
seulement le nom exact de l'objet. Les caractères à l'intérieur du
motif sont normalement mis en minuscule comme pour les noms SQL ;
par exemple, \dt FOO affichera la table nommée
foo. Comme pour les noms SQL, placer des guillemets
doubles autour d'un motif empêchera la mise en minuscule. Si vous devez
inclure un guillemet double dans un motif, écrivez-le en double en
accord avec les règles sur les identifiants SQL. Par exemple,
\dt "FOO""BAR" affichera la table nommée
FOO"BAR (et non pas foo"bar).
Contrairement aux règles normales pour les noms SQL, vous pouvez placer
des guillemets doubles simplement autour d'une partie d'un motif,
par exemple \dt FOO"FOO"BAR affichera la table nommée
fooFOObar.
Lorsque le paramètre motif
est complètement absent, la commande \d affiche tous les objets
visibles dans le chemin de recherche courant -- cela est équivalent à l'utilisation du motif
*.
(Un objet est dit visible si le schéma qui le contient
est dans le chemin de recherche et qu'aucun objet de même type et même nom n'apparaît
avant dans le chemin de recherche. Cela est équivalent à dire que
l'objet peut être référencé par son nom sans préciser explicitement
le schéma.)
Pour voir tous les objets de la base quelle que soit leur visibilité,
utilisez le motif *.* .
À l'intérieur d'un motif, * correspond à toute
séquence de caractères (et aussi à aucun) alors que ? ne
correspond qu'à un seul caractère. (Cette notation est comparable à celle des
motifs de nom de fichier Unix.) Par exemple, \dt int*
affiche les tables dont le nom commence avec int. Mais à
l'intérieur de guillemets doubles, * et ?
perdent leurs significations spéciales et sont donc traités directement.
Un motif qui contient un point (.) est interprété comme
le motif d'un nom de schéma suivi par celui d'un nom d'objet. Par exemple,
\dt foo*.*bar* affiche toutes les tables dont le nom
inclut bar et qui sont dans des schémas dont le
nom commence avec foo. Sans point, le motif correspond
seulement aux objets qui sont visibles dans le chemin de recherche
actuel des schémas. De nouveau, un point dans des guillemets doubles
perd sa signification spéciale et est traité directement.
Les utilisateurs avancés peuvent utiliser des expressions rationnelles comme
par exemple les classes de caractère ([0-9] pour tout
chiffre). Tous les caractères spéciaux d'expression rationnelle fonctionnent
de la façon indiquée dans Section 9.7.3, sauf pour
le . qui est pris comme séparateur (voir ci-dessus),
l'étoile (*) qui est transformée en l'expression
rationnelle .* et ? qui est transformée
en ., et $ qui est une correspondance
littérale. Vous pouvez émuler ces caractères si besoin en
écrivant ? pour .,
( pour
R+|)R*( pour
R|)R?$ n'est pas nécessaire en tant que caractère d'une
expression rationnelle car le motif doit correspondre au nom complet,
contrairement à l'interprétation habituelle des expressions rationnelles
(en d'autres termes, $ est ajouté automatiquement à
votre motif). Écrivez * au début et/ou à la fin si
vous ne souhaitez pas que le motif soit ancré.
Notez qu'à l'intérieur de guillemets doubles, tous les
caractères spéciaux des expressions rationnelles perdent leur signification
spéciale et sont traités directement. De plus, ces caractères sont traités
littéralement dans les motifs des noms d'opérateurs (par exemple
pour l'argument de \do).
psql fournit des fonctionnalités de substitution de variable similaire aux shells de commandes Unix. Les variables sont simplement des paires nom/valeur où la valeur peut être toute chaîne, quelle que soit sa longueur. Le nom doit consister en lettres (incluant les lettres non latines), chiffres et tirets bas.
Pour configurer une variable, utilisez la
métacommande psql \set.
Par exemple :
basetest=> \set foo bar
initialise la variable foo avec la valeur
bar. Pour récupérer le contenu de la variable, précédez
le nom avec un caractère deux-points, par exemple :
basetest=> \echo :foo
bar
Ceci fonctionne avec les commandes SQL et les métacommandes standards. Il y a plus de détails dans Interpolation SQL, ci-dessous.
Si vous appelez \set sans second argument, la variable
est initialisée avec une chaîne vide. Pour désinitialiser (c'est-a-dire
supprimer) une
variable, utilisez la commande \unset.
Pour afficher les valeurs de toutes les variables, appelez
\set sans argument.
Les arguments de \set sont sujets aux même règles de
substitution que les autres commandes. Du coup, vous pouvez construire des
références intéressantes comme \set :foo 'quelquechose'
et obtenir des « liens doux » ou des « variables de
variables » comme, respectivement, en Perl ou
PHP. Malheureusement (ou
heureusement ?), on ne peut rien faire
d'utile avec ces constructions. D'un autre côté, \set bar
:foo est un moyen parfaitement valide de copier une variable.
Un certain nombre de ces variables sont traitées d'une façon particulière par psql. Elles représentent certaines configurations d'options pouvant être changées à l'exécution en modifiant la valeur de la variable ou, dans certains cas, représentent un état modifiable de psql. La convention veut que tous les noms de variables traités spécialement utilisent des lettres ASCII en majuscule (et éventuellement des chiffres et des tirets bas). Pour s'assurer une compatibilité maximum dans le futur, éviter d'utiliser de tels noms de variables pour vos propres besoins.
Les variables qui contrôlent le comportement de psql
ne peuvent pas être désinitialisées ou se voir affecter des valeurs
incorrectes. Une commande \unset est autorisée mais
interprétée comme remettant la variable à sa valeur par défaut. Une commande
\set sans second argument est interprétée comme affectant
on à la variable, pour les variables de contrôle qui
acceptent cette valeur, et sera rejeté pour les autres. Les variables de
contrôle qui acceptent les valeurs on
et off accepteront également d'autres formes communes
d'écriture des valeurs booléennes, comme true et
false.
Voici une liste des variables spéciales :
AUTOCOMMIT
Si actif (on, valeur par défaut), chaque commande SQL est
automatiquement validée si elle se termine avec succès. Pour suspendre
la validation dans ce mode, vous devez saisir une commande SQL
BEGIN ou START TRANSACTION. Lorsqu'elle est
désactivée (off) ou non initialisée, les commandes SQL ne
sont plus validées tant que vous ne lancez pas explicitement
COMMIT ou END. Le mode sans autocommit
fonctionne en lançant implicitement un BEGIN,
juste avant toute commande qui n'est pas déjà dans un bloc de
transaction et qui n'est pas elle-même un BEGIN ou une autre
commande de contrôle de transaction, ou une commande qui ne peut pas être
exécutée à l'intérieur d'un bloc de transaction (comme VACUUM).
Dans le mode sans autocommit, vous devez annuler explicitement toute
transaction échouée en saisissant ABORT ou
ROLLBACK. Gardez aussi en tête que si vous sortez d'une
session sans validation, votre travail est perdu.
Le mode auto-commit est le comportement traditionnel de
PostgreSQL alors que le mode sans autocommit est plus
proche des spécifications SQL. Si vous préférez sans autocommit, vous
pouvez le configurer dans le fichier psqlrc
global du système ou dans votre fichier ~/.psqlrc.
COMP_KEYWORD_CASE
Détermine la casse à utiliser lors de la complétion d'un mot clé SQL.
S'il est configuré à lower ou upper,
le mot complété sera, respectivement, en minuscule ou en majuscule.
Si la variable est configurée à preserve-lower ou
preserve-upper (valeur par défaut), le mot complété
sera dans la casse du mot déjà saisi, mais les mots qui n'ont pas eu un
début de saisie seront complétés, respectivement, soit en minuscule soit
en majuscule.
DBNAMELe nom de la base de données à laquelle vous êtes actuellement connecté. Ceci est configuré à chaque fois que vous vous connectez à une base de données (ainsi qu'au lancement du programme) mais peut être changé ou désinitialisé.
ECHO
Si cette variable est initialisée à all, toutes les
lignes non vides saisies sont envoyées sur la sortie standard tout de
suite après leur lecture. (Ceci ne s'applique pas aux lignes lues de
façon interactive.) Pour sélectionner ce comportement au lancement du
programme, utilisez l'option -a. Si
ECHO vaut queries,
psql affiche chaque requête sur la sortie
standard comme elle est envoyée au serveur. L'option pour choisir ce
comportement est -e. Si elle est configurée à
errors, seules les requêtes échouées seront
affichées sur la sortie standard des erreurs. L'option en ligne de
commande pour ce comportement est -b. Si elle est
configurée à none (valeur par défaut), alors aucune requête n'est
affichée.
ECHO_HIDDEN
Quand cette variable est initialisée à on et qu'une
commande antislash est envoyée à la base de données, la requête est
d'abord affichée. Cette fonctionnalité vous aide à étudier le
fonctionnement interne de
PostgreSQL et fournir des fonctionnalités
similaires dans vos propres programmes. (Pour sélectionner ce
comportement au lancement du programme, utilisez l'option
-E.) Si vous configurez la variable avec la valeur
noexec, les requêtes sont juste affichées mais ne
sont pas réellement envoyées au serveur ni exécutées.
La valeur par défaut est off.
ENCODING
Le codage courant du jeu de caractères du client.
Il est fixé à chaque fois que vous vous connectez à une base de données
(y compris au démarrage du programme), et quand vous changez
l'encodage avec \encoding, mais il peut être changé ou
désinitialisé.
FETCH_COUNT
Si cette variable est un entier plus grand que zéro, les résultats des
requêtes SELECT sont récupérés et affichés en groupe de
ce nombre de lignes, plutôt que par le comportement par défaut
(récupération de l'ensemble complet des résultats avant l'affichage).
Du coup, seule une petite quantité de mémoire est utilisée, quelle que
soit la taille de l'ensemble des résultats. Une configuration entre
100 et 1000 est habituellement utilisée lors de l'activation de cette
fonctionnalité.
Gardez en tête que lors de l'utilisation de cette fonctionnalité, une
requête pourrait échouer après avoir affiché quelques lignes.
Bien que vous puissiez utiliser tout format de sortie avec cette
fonctionnalité, le format par défaut, aligned,
rend mal car chaque groupe de FETCH_COUNT lignes
sera formaté séparément, modifiant ainsi les largeurs de colonnes
suivant les lignes du groupe. Les autres formats d'affichage
fonctionnent mieux.
HISTCONTROL
Si cette variable est configurée à ignorespace, les
lignes commençant avec un espace n'entrent pas dans la liste de
l'historique. Si elle est initialisée avec la valeur
ignoredups, les lignes correspondant aux précédentes
lignes de l'historique n'entrent pas dans la liste. Une valeur de
ignoreboth combine les deux options. Si elle est
configurée avec none), toutes les lignes lues dans le mode interactif sont
sauvegardées dans la liste de l'historique.
Cette fonctionnalité a été plagiée sans vergogne sur Bash.
HISTFILE
Le nom du fichier utilisé pour stocker l'historique. Si désinitialisé,
le nom du fichier sera la valeur de la variable d'environnement
PSQL_HISTORY. Si celle-ci n'est pas initialisée, la
valeur par défaut sera ~/.psql_history ou
%APPDATA%\postgresql\psql_history sur Windows.
Par exemple, mettre :
Cette fonctionnalité a été plagiée sans vergogne sur Bash.
HISTSIZELe nombre maximum de commandes à stocker dans l'historique des commandes (par défaut 500). Aucune limite ne sera appliquée si une valeur négative est donnée.
Cette fonctionnalité a été plagiée sans vergogne sur Bash.
HOSTL'hôte du serveur de la base de données sur lequel vous êtes actuellement connecté. Ceci est configuré à chaque fois que vous vous connectez à une base de données (ainsi qu'au lancement du programme) mais peut être changé ou désinitialisé.
IGNOREEOFSi configuré à 1 ou inférieur, envoyer un caractère EOF (habituellement Ctrl+D) dans une session interactive de psql ferme l'application. Si configuré à une valeur numérique supérieure, alors autant de caractères EOF consécutifs doivent être saisis pour terminer une session interactive. Une valeur non numérique sera interprétée comme valant 10. La valeur par défaut est 0.
Cette fonctionnalité a été plagiée sans vergogne sur Bash.
LASTOID
La valeur du dernier OID affecté, renvoyée à partir d'une commande
INSERT ou lo_import. La
validité de cette variable est seulement garantie jusqu'à
l'affichage du résultat de la commande SQL suivante.
ON_ERROR_ROLLBACK
Lorsqu'il est actif (on), si une instruction d'un bloc de
transaction génère une erreur, cette dernière est ignorée et la
transaction continue. Lorsqu'il vaut interactive, ces
erreurs sont seulement ignorées lors des sessions interactives, mais
ne le sont pas lors de la lecture de scripts. Lorsqu'il est configuré
à off (valeur par défaut), une instruction générant une
erreur dans un bloc de transaction annule la transaction complète. Le
mode avec on fonctionne en exécutant un
SAVEPOINT implicite pour vous, juste avant chaque commande
se trouvant dans un bloc de transaction, et annule jusqu'au
point de sauvegarde si la commande échoue.
ON_ERROR_STOP
Par défaut, le traitement des commandes continue après une
erreur. Quand cette variable est positionnée à on, le traitement
sera immédiatement arrêté dès la première erreur rencontrée.
En mode interactif, psql
reviendra à l'invite de commande ; sinon
psql quittera en renvoyant le code
d'erreur 3 pour distinguer ce cas des conditions d'erreurs
fatales, qui utilisent le code 1. Dans tous les cas, tout script
en cours d'exécution (le script de plus haut niveau, s'il y a, et
tout autre script qui pourrait avoir été appelé) sera terminé
immédiatement. Si la chaîne de commande de plus haut niveau contient
plusieurs commandes SQL, le traitement s'arrêtera à la commande
en cours.
PORTLe port du serveur de la base de données sur lequel vous êtes actuellement connecté. Ceci est configuré à chaque fois que vous vous connectez à une base de données (ainsi qu'au lancement du programme) mais peut être changé ou désinitialisé.
PROMPT1PROMPT2PROMPT3Ils spécifient à quoi doit ressembler l'invite psql. Voir Invite ci-dessous.
QUIET
Configurer cette variable à on est équivalent à
l'option -q en ligne
de commande. Elle n'est probablement pas très utile en mode
interactif.
SERVER_VERSION_NAMESERVER_VERSION_NUM
Le numéro de version du serveur sous la forme d'une chaîne de
caractères, par exemple 9.6.2,
10.1 ou 11beta1, et sous sa
forme numérique, par exemple 90602 ou
100001. Ces variables sont configurées à chaque
fois que vous vous connectez à une base de données (y compris au
lancement du programme) mais peuvent être modifiées ou déconfigurées.
SHOW_CONTEXT
Cette variable peut être configurée avec les valeurs
never, errors ou
always pour contrôler si les champs
CONTEXT sont affichés dans les messages du serveur.
La valeur par défaut est errors (signifiant que ce
contexte sera affiché dans les messages d'erreur et non pas dans les
notes et avertissements). Ce paramètre n'a pas d'effet quand
VERBOSITY est configuré à terse.
(Voir aussi \errverbose, à utiliser quand vous
voulez une version verbose du dernier message d'erreur reçu.)
SINGLELINE
Configurer cette variable à on est équivalent à
l'option -S en ligne de commande.
SINGLESTEP
Configuer cette variable à on est équivalent à
l'option -s en ligne de commande.
USERL'utilisateur de la base de données sur laquelle vous êtes actuellement connecté. Ceci est configuré à chaque fois que vous vous connectez à une base de données (ainsi qu'au lancement du programme) mais peut être changé ou désinitialisé.
VERBOSITY
Cette variable peut être configurée avec les valeurs
default, verbose (bavard)
ou terse (succinct) pour
contrôler la verbosité des rapports d'erreurs.
(Voir aussi \errverbose à utiliser quand vous avez
besoin d'une version verbeuse de l'erreur que vous venez de
récupérer.)
VERSIONVERSION_NAMEVERSION_NUM
Ces variables sont configurées au démarrage du programme pour
refléter la version de psql respectivement
sous la forme d'une chaîne de caractères, d'une chaîne courte (par
exemple 9.6.2, 10.1 ou
11beta1) d'un nombre (par exemple
90602 ou 100001). Elles peuvent
être modifiées ou désinitialisées.
Une fonctionnalité clé des variables psql est
que vous pouvez les substituer (« interpolation ») dans des
requêtes SQL standards, ainsi qu'en arguments de
métacommandes. De plus, psql fournit des
fonctionnalités vous assurant que les valeurs des variables utilisées
comme constantes et identifiants SQL sont correctement mises entre
guillemets. La syntaxe pour l'interpolation d'une valeur sans guillemets
est de préfixer le nom de la variable avec le symbole deux-points
(:). Par exemple :
basetest=>\set foo 'ma_table'basetest=>SELECT * FROM :foo;
envoie alors la requête pour la table ma_table. Notez que cela peut
être dangereux ; la valeur de la variable est copiée de façon litérale, elle peut
même contenir des guillemets non fermés, ou bien des commandes antislash. Vous devez
vous assurer que cela a du sens à l'endroit où vous les utilisez.
Lorsqu'une valeur doit être utilisée comme une chaîne SQL litérale ou un identifiant, il est plus sûr de s'arranger pour qu'elle soit entre guillemets. Afin de mettre en guillemets la valeur d'une variable en tant que chaîne SQL litérale, écrivez un caractère deux-points, suivi du nom de la variable entouré par des guillemets simples. Pour mettre entre guillemet la valeur en tant qu'identifiant SQL, écrivez un caractère deux-points suivi du nom de la valeur entouré de guillemets doubles. Ces constructions gèrent correctement les guillemets et autres caractères spéciaux intégrés dans la valeur de la variable. L'exemple précédent peut s'écrire de façon plus sûre ainsi :
testdb=>\set foo 'my_table'testdb=>SELECT * FROM :"foo";
L'interpolation de variables ne sera pas réalisée à l'intérieur de litéraux
et d'identifiants SQL mis entre guillemets. Du coup, une
construction comme ':foo' ne fonctionne pas pour avoir
un litéral entre guillemets à partir de la valeur d'une variable (il serait
même dangereux que cela fonctionne car ça ne peut pas gérer correctement
les guillemets embarqués dans la valeur).
Un exemple de l'utilisation de ce mécanisme est la copie du contenu d'un fichier dans la colonne d'une table. Tout d'abord, chargez le fichier dans une variable puis interpolez la valeur de la valeur en tant que chaîne de caractères :
basetest=>\set contenu `cat mon_fichier.txt`basetest=>INSERT INTO ma_table VALUES (:'contenu');
(Notez que cela ne fonctionnera par si le fichier
mon_fichier.txt contient des octets nuls. psql ne
gère pas les octets nuls inclus dans les valeurs de variable.)
Comme des caractères deux-points peuvent légitimement apparaître dans les
commandes SQL, une tentative apparente d'interpolation (comme :nom,
:'nom', ou :"nom") n'est pas remplacée, sauf si
la variable nommée est actuellement positionnée. Dans tous les cas, vous pouvez échapper un
caractère deux-points avec un antislash pour le protéger des substitutions.
La syntaxe deux-points pour les variables est du SQL standard pour les langages de requête embarqués, comme ECPG. La syntaxe avec les deux-points pour les tranches de tableau et les conversions de types sont des extensions PostgreSQL, qui peut parfois provoquer un conflit avec l'utilisation standard. La syntaxe avec le caractère deux-points pour échapper la valeur d'une variable en tant que chaîne SQL litérale ou identifiant est une extension psql.
Les invites psql peuvent être personnalisées
suivant vos préférences. Les trois variables PROMPT1,
PROMPT2 et PROMPT3 contiennent des
chaînes et des séquences d'échappement spéciales décrivant l'apparence de
l'invite. L'invite 1 est l'invite normale qui est lancée quand
psql réclame une nouvelle commande. L'invite 2 est
lancée lorsqu'une saisie supplémentaire est attendue lors de la saisie de la
commande, par exemple parce que la commande n'a pas été terminée avec un
point-virgule ou qu'un guillemet n'a pas été fermé.
L'invite 3 est lancée lorsque vous
exécutez une commande SQL
COPY FROM stdin et que
vous devez saisir les valeurs des lignes sur le terminal.
La valeur de la variable prompt sélectionnée est affichée littéralement
sauf si un signe pourcentage (%) est rencontré. Suivant
le prochain caractère, certains autres textes sont substitués. Les
substitutions définies sont :
%M
Le nom complet de l'hôte (avec le nom du domaine) du serveur de la
base de données ou [local] si la connexion est
établie via une socket de domaine Unix ou
[local:,
si la socket de domaine Unix n'est pas dans l'emplacement par défaut
défini à la compilation.
/répertoire/nom]
%m
Le nom de l'hôte du serveur de la base de données, tronqué au
premier point ou [local] si la connexion se fait
via une socket de domaine Unix.
%>Le numéro de port sur lequel le serveur de la base de données écoute.
%n
Le nom d'utilisateur de la session. (L'expansion de cette valeur
peut changer pendant une session après une commande SET
SESSION AUTHORIZATION.)
%/Le nom de la base de données courante.
%~Comme %/ mais l'affichage est un
~ (tilde) si la base de données est votre base de
données par défaut.
%#
Si l'utilisateur de la session est un superutilisateur, alors un
# sinon un >.
(L'expansion de cette valeur peut changer durant une session
après une commande SET SESSION
AUTHORIZATION.)
%pL'identifiant du processus serveur (PID) pour cette connexion.
%R
Dans le prompt 1 normalement =, mais
@ si la session est dans une branche inactive d'un
bloc conditionnel, ou ^ en mode simple ligne,
ou ! si la session est
déconnectée de la base (ce qui peut arriver si \connect
échoue). Dans le prompt 2, %R est remplacé par un
caractère qui dépend de la raison pour laquelle
psql attend des entrées
supplémentaires : - si la commande n'est juste pas
terminée, mais * s'il y a un commentaire
/* ... */ non terminé,
un guillemet simple pour une chaîne de caractères entre guillemets simples
non terminée,
un guillemet double pour un identifiant échappé non terminé,
un signe dollar pour une chaîne de caractères entre dollars,
ou ( s'il y a une parenthèse ouvrante sans correspondance.
Dans le prompt 3, %R n'a aucun effet.
%x
État de la Transaction : une chaîne vide lorsque vous n'êtes pas
dans un bloc de transaction, ou * si vous y êtes, ou
! dans une transaction échouée, ou
? lorsque l'état de la transaction est indéterminé (par
exemple parce qu'il n'y a pas de connexion).
%l
Le numéro de ligne dans la requête courante, en partant
de 1.
%chiffresLe caractère avec ce code numérique est substitué.
%:nom:
La valeur de la variable nom de psql.
Voir la section Variables pour les détails.
%`commande`
La sortie de la commande,
similaire à la substitution
par « guillemets inverse » classique.
%[ ... %]
Les invites peuvent contenir des caractères de contrôle du terminal
qui, par exemple, modifient la couleur, le fond ou le style du texte
de l'invite, ou modifient le titre de la fenêtre du terminal. Pour
que les fonctionnalités d'édition de ligne de
Readline fonctionnent correctement, les
caractères de contrôle non affichables doivent être indiqués comme
invisibles en les entourant avec %[ et
%]. Des paires multiples de ceux-ci peuvent
survenir à l'intérieur de l'invite. Par exemple :
basetest=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '
a pour résultat une invite en gras (1;), jaune sur
noir (33;40) sur les terminaux compatibles
VT100.
Pour insérer un pourcentage dans votre invite, écrivez
%%. Les invites par défaut sont
'%/%R%# ' pour les invites 1 et 2 et
'>> ' pour l'invite 3.
Cette fonctionnalité a été plagiée sans vergogne sur tcsh.
psql supporte la bibliothèque
Readline pour une édition et une recherche
simplifiée et conviviale de la ligne de commande. L'historique des commandes
est automatiquement sauvegardé lorsque psql
quitte et est rechargé quand psql est lancé. La
complétion par tabulation est aussi supportée bien que la logique de
complétion n'ait pas la prétention d'être un analyseur
SQL. Les requêtes générées par complétion peuvent aussi
interférer avec les autres commandes SQL, par exemple SET
TRANSACTION ISOLATION LEVEL. Si pour quelque raison que ce soit
vous n'aimez pas la complétion par tabulation, vous pouvez la désactiver en
plaçant ceci dans un fichier nommé .inputrc de votre
répertoire personnel :
$if psql
set disable-completion on
$endif
(Ceci n'est pas une fonctionnalité psql mais Readline. Lisez sa documentation pour plus de détails.)
COLUMNS
Si \pset columns vaut zéro, contrôle la largeur pour
le format wrapped et la largeur pour déterminer si
une sortie large a besoin du paginateur ou doit être basculé en format
vertical dans le mode automatique étendu.
PAGER
Si les résultats d'une requête ne tiennent pas sur l'écran, ils sont
envoyés via un tube sur cette commande. Les valeurs typiques sont
more ou less. La valeur par défaut
dépend de la plateforme. L'utilisation du paginateur peut être
désactivée en configurant PAGER à vide ou en utilisant
les options relatives au paginateur de la commande
\pset.
PGDATABASEPGHOSTPGPORTPGUSERParamètres de connexion par défaut (voir Section 33.14).
PSQL_EDITOREDITORVISUAL
Éditeur utilisé par les commandes \e
\ef et \ev. Les variables sont
examinées dans l'ordre donné ; la première initialisée est utilisée.
Les éditeurs intégrés par défaut sont vi sur
les systèmes Unix et notepad.exe sur les
systèmes Windows.
PSQL_EDITOR_LINENUMBER_ARG
Lorsque les commandes \e ou \ef
sont utilisées avec un argument spécifiant le numéro de ligne,
cette variable doit indiquer l'argument en ligne de commande à
fournir à l'éditeur de texte. Pour les éditeurs les plus courants,
tels qu'emacs ou
vi, vous pouvez simplement initialiser
cette variable avec le signe +. Il faut inclure le caractère
d'espacement en fin de la valeur de la variable si la syntaxe de
l'éditeur nécessite un espace entre l'option à spécifier et le
numéro de ligne. Par exemple :
PSQL_EDITOR_LINENUMBER_ARG='+'
PSQL_EDITOR_LINENUMBER_ARG='--line '
La valeur par défaut est + sur les systèmes Unix
(ce qui correspond à la bonne configuration pour l'éditeur par
défaut, vi, et est utilisable généralement
avec la plupart des éditeurs courants) ; par contre, il n'y
a pas de valeur par défaut pour les systèmes Windows.
PSQL_HISTORY
Emplacement alternatif pour le fichier d'historique des commandes.
L'expansion du symbole ~ est réalisée.
PSQLRC
Emplacement alternatif pour le fichier .psqlrc de l'utilisateur. L'expansion
du symbôle ~ est réalisée.
SHELL
Commande exécutée par la commande \!.
TMPDIR
Répertoire pour stocker des fichiers temporaires. La valeur par défaut est
/tmp.
Cet outil, comme la plupart des autres outils PostgreSQL, utilise aussi les variables d'environnement supportées par la bibliothèque libpq (voir Section 33.14).
psqlrc et ~/.psqlrc
Sauf si une option -X est fournie,
psql tente de lire et exécuter les commandes
provenant du fichier global au système (psqlrc), puis
du fichier utilisateur (~/.psqlrc) après la connexion
à la base de données mais avant d'accepter les commandes interactives.
Ces fichiers sont utilisés pour configurer le client et le serveur
à votre goût, généralement en utilisant les commandes \set
et SET.
Le fichier de configuration au niveau système est nommé
psqlrc et est placé dans le répertoire de
configuration système de l'installation. Il est facilement identifiable
en exécutant pg_config --sysconfdir. Par défaut, ce
répertoire doit être ../etc/ relatif au répertoire
contenant les exécutables PostgreSQL. Le nom de
ce répertoire peut être configuré explicitement avec la variable
d'environnement PGSYSCONFDIR.
Le fichier de configuration personnel de l'utilisateur est nommé
.psqlrc et est placé à la racine du répertoire
personnel de l'utilisateur. Sur Windows, qui manque d'un tel concept,
le fichier de configuration personnel est nommé
%APPDATA%\postgresql\psqlrc.conf. L'emplacement
du fichier de configuration personnel peut être configuré explicitement
via la variable d'environnement PSQLRC.
Le fichier niveau système et le fichier de l'utilisateur peuvent être
spécifiques à la version de psql en ajoutant un tiret et la version mineure ou
majeure, par exemple ~/.psqlrc-9.2 ou
~/.psqlrc-9.2.5. Le fichier dont la version est la
plus proche sera lu à la place d'un fichier sans indication de version.
.psql_history
L'historique de la ligne de commandes est stocké dans le fichier
~/.psql_history ou
%APPDATA%\postgresql\psql_history sur Windows.
L'emplacement du fichier historique peut aussi être configuré explicitement
avec la variable psql HISTFILE
ou avec la variable d'environnement PSQL_HISTORY.
psql fonctionne mieux avec des serveurs de la
même version ou d'une version majeure plus ancienne. Les commandes
antislashs peuvent échouer si le serveur est plus récent que
psql. Néanmoins, les commandes antislashs
de la famille \d devraient fonctionner avec tous
les serveurs jusqu'à la version 7.4, bien que pas nécessairement avec
des serveurs plus récents que psql lui-même.
Les fonctionnalités générales d'exécution de commandes SQL et d'affichage
des résultats des requêtes devraient aussi fonctionner avec les serveurs
d'une version majeure plus récente mais ce ne peut être garanti dans
tous les cas.
Si vous voulez utiliser psql pour vous connecter à différentes versions majeures, il est recommandé d'utiliser la dernière version de psql. Autrement, vous pouvez conserver une copie de psql pour chaque version majeure utilisée et vous assurer que la version utilisée correspond au serveur respectif. En pratique, cette complication supplémentaire n'est pas nécessaire.
Avant PostgreSQL 9.6, l'option
-c impliquait -X
(--no-psqlrc) ; ceci n'est plus le cas.
Avant PostgreSQL 8.4, psql autorisait le premier argument d'une commande antislash à une seule lettre à commencer directement après la commande, sans espace supplémentaire. Maintenant, un espace blanc est requis.
psql est construit comme une « application de type console ». Comme les fenêtres console de Windows utilisent un codage différent du reste du système, vous devez avoir une attention particulière lors de l'utilisation de caractères sur 8 bits à l'intérieur de psql. Si psql détecte une page de code problématique, il vous avertira au lancement. Pour modifier la page de code de la console, deux étapes sont nécessaires :
Configurez la page code en saisissant cmd.exe /c chcp
1252. (1252 est une page code appropriée pour
l'Allemagne ; remplacez-la par votre valeur.) Si vous
utilisez Cygwin, vous pouvez placer cette commande dans
/etc/profile.
Configurez la police de la console par Lucida Console
parce que la police raster ne fonctionne pas avec la page de code ANSI.
Le premier exemple montre comment envoyer une commande sur plusieurs lignes d'entrée. Notez le changement de l'invite :
basetest=>CREATE TABLE ma_table (basetest(>premier integer not NULL default 0,basetest(>second text)basetest->;CREATE TABLE
Maintenant, regardons la définition de la table :
basetest=> \d ma_table
Table "public.ma_table"
Column | Type | Collation | Nullable | Default
---------+---------+-----------+----------+---------
premier | integer | | not null | 0
second | text | | |
Maintenant, changeons l'invite par quelque chose de plus intéressant :
basetest=> \set PROMPT1 '%n@%m %~%R%# '
pierre@localhost basetest=>
Supposons que nous avons rempli la table de données et que nous voulons les regarder :
pierre@localhost basetest=> SELECT * FROM ma_table;
premier | second
---------+--------
1 | un
2 | deux
3 | trois
4 | quatre
(4 rows)
Vous pouvez afficher cette table de façon différente en utilisant la
commande \pset :
pierre@localhost basetest=>\pset border 2Border style is 2. pierre@localhost basetest=>SELECT * FROM ma_table;+---------+--------+ | premier | second | +---------+--------+ | 1 | un | | 2 | deux | | 3 | trois | | 4 | quatre | +---------+--------+ (4 rows) pierre@localhost basetest=>\pset border 0Border style is 0. pierre@localhost basetest=>SELECT * FROM ma_table;premier second ------- ------ 1 un 2 deux 3 trois 4 quatre (4 rows) pierre@localhost basetest=>\pset border 1Border style is 1. pierre@localhost basetest=>\pset format unalignedOutput format is unaligned. pierre@localhost basetest=>\pset fieldsep ","Field separator is ",". pierre@localhost basetest=>\pset tuples_onlyShowing only tuples. pierre@localhost basetest=>SELECT second, premier FROM ma_table;un,1 deux,2 trois,3 quatre,4
Vous pouvez aussi utiliser les commandes courtes :
pierre@localhost basetest=>\a \t \xOutput format is aligned. Tuples only is off. Expanded display is on. pierre@localhost basetest=>SELECT * FROM ma_table;-[ RECORD 1 ]--- premier | 1 second | un -[ RECORD 2 ]--- premier | 2 second | deux -[ RECORD 3 ]--- premier | 3 second | trois -[ RECORD 4 ]--- premier | 4 second | quatre
En cas de besoin, les résultats de la requête peuvent être affichés dans une
représentation croisée avec la commande \crosstabview :
testdb=>SELECT first, second, first > 2 AS gt2 FROM my_table;premier | second | gt2 ---------+--------+----- 1 | un | f 2 | deux | f 3 | trois | t 4 | quatre | t (4 rows) testdb=>\crosstabview premier secondpremier | un | deux | trois | quatre ---------+----+------+-------+-------- 1 | f | | | 2 | | f | | 3 | | | t | 4 | | | | t (4 rows)
Ce deuxième exemple montre une table de multiplication avec les lignes triées en ordre numérique inverse et les colonnes dans un ordre numérique ascendant indépendant.
testdb=>SELECT t1.premier as "A", t2.premier+100 AS "B", t1.premier*(t2.premier+100) as "AxB",testdb(>row_number() over(order by t2.premier) AS ordtestdb(>FROM ma_table t1 CROSS JOIN ma_table t2 ORDER BY 1 DESCtestdb(>\crosstabview "A" "B" "AxB" ordA | 101 | 102 | 103 | 104 ---+-----+-----+-----+----- 4 | 404 | 408 | 412 | 416 3 | 303 | 306 | 309 | 312 2 | 202 | 204 | 206 | 208 1 | 101 | 102 | 103 | 104 (4 rows)