Documentation PostgreSQL 14.22 » Référence » Applications client de PostgreSQL » psql

Précédent | Niveau supérieur | Suivant
pg_verifybackup | Sommaire | reindexdb

## psql

psql — terminal interactif PostgreSQL

## Synopsis

`psql` [`option`...] [`nombase` [`nomutilisateur`]]

## Description

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.

## Options

`-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 `aligned`.) 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. (Voir Section 53.2.2.1 pour plus de détails sur la gestion par le serveur des chaînes contenant plusieurs requêtes.) 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

`--csv`

  Passe au format de sortie CSV (Comma-Separated Values) Ceci est équivalent à `\pset format csv`.

`-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 < `nomfichier``. En général, les deux feront ce que vous souhaitez, mais utiliser `-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ôte``

  Indique 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`

  Bascule en affichage 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-readline`

  N'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-step`

  S'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-line`

  S'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.

  ### Note

  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`
`--version`

  Affiche 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`
`--password`

  Force 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.

## Code de sortie

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.

## Usage

### Se connecter à une base de données

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 34.15). Il est aussi pratique d'avoir un fichier `~/.pgpass` pour éviter d'avoir régulièrement à saisir les mots de passe. Voir Section 34.16 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 34.18. Voir Section 34.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`.

### Saisir des commandes SQL

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 (14.22)
    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.

### Métacommandes

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 `\x` `chiffres` (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 `:'`variable_name`'` et `:"`variable_name`"` décrites ici fonctionnent également. La syntaxe `:{?`variable_name`}` permet de tester si une variable est définie. Elle est substituée par TRUE ou FALSE. Échapper le symbole deux-points avec un antislash le protège de la substitution.

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 `:`variable_name`` où `variable_name` est une variable psql, qui sera remplacée par sa valeur. De plus, les occurrences de `:'`variable_name`'` 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.

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 antislashs) 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 34.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é), la connexion précédente sera conservée et psql sera en mode interactif. Mais lors de l'exécution d'un script non interactif, l'ancienne connexion est fermée et une erreur est renvoyée. Ceci pourrait terminer ou non le script ; si cela ne le fait pas, toutes les commandes d'accès à la base échoueront jusqu'à ce qu'une autre commande `\connect` soit exécutée avec succès. Cette distinction a été choisie pour faciliter la vie de l'utilisateur en cas de fautes de frappe, et en même temps comme mécanisme de sécurité pour que les scripts n'agissent pas sur la mauvaise base de données. Notez que, quand une commande `\connect` tente de réutiliser des paramètres, les valeurs ré-utilisées sont celles de la dernière connexion réussie, pas celles des tentatives échouées faites après. Néanmoins, dans le cas d'un échec d'un `\connect` non interactif, aucun paramètre ne peut être réutilisé après coup car le script pourrait s'attendre à la réutilisation des valeurs de `\connect` échoué.

  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 `titre``. (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.)

`\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.

  ### Astuce

  Pour afficher votre répertoire courant, utilisez `\! pwd`.

`\conninfo`

  Affiche des informations sur la connexion en cours à la base de données.

`\copy { `table` [ ( `liste_colonnes` ) ] } `from` { `'nomfichier'` | program `'commande'` | stdin | pstdin } [ [ with ] ( `option` [, ...] ) ] [ where `condition` ]`
`\copy { `table` [ ( `liste_colonnes` ) ] | ( `requête` ) } `to` { `'nomfichier'` | program `'commande'` | stdout | 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 super-utilisateur 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 super-utilisateur 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 `count`` 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 `\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.

  ### Astuce

  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 `nom_fichier`` ou `\g |`programme``. Contrairement à `\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.

  ### Astuce

  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. De plus, du fait de cette méthode de passage, `\copy ... from` dans le mode CSV traitera de façon erronée une donnée `\.` seule sur une ligne en la prenant pour un marqueur de fin de données.

`\copyright`

  Affiche 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 and the access method name if the relation has an access method.

  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.

  ### Note

  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.

`\dAc[+] [`access-method-pattern` [`input-type-pattern`]]`

  Liste les classes d'opérateurs (voir Section 52.33). Si `access-method-pattern` est spécifié, seules les classes d'opérateurs associées avec les méthodes d'accès dont les noms correspondent au motif sont listées. Si `input-type-pattern` est spécifié, seules les classes d'opérateurs associées avec les types en entrée dont les noms correspondent au motif sont listées. Si `+` est ajouté au nom de la commande, chaque classe d'opérateur est affichée avec sa famille d'opérateur associée et propriétaire.

`\dAf[+] [`access-method-pattern` [`input-type-pattern`]]`

  Liste les familles d'opérateur (voir Section 38.16.5). Si `access-method-pattern` est spécifié, seules les familles d'opérateur associées avec les méthodes d'accès dont les noms correspondent au motif sont listées. Si `input-type-pattern` est spécifié, seules les familles d'opérateur associées avec les types en entrée dont les noms correspondent au motif sont listées. Si `+` est ajouté au nom de la commande, chaque famille d'opérateur est affichée avec son propriétaire.

`\dAo[+] [`access-method-pattern` [`operator-family-pattern`]]`

  Liste les fonctions associées avec les familles d'opérateur (Section 38.16.2). Si `access-method-pattern` est spécifié, seuls les membres des familles d'opérateur associés avec les méthodes d'accès dont les noms correspondent au motif sont listés. Si `operator-family-pattern` est spécifié, seuls les membres des familles d'opérateur dont les noms correspondent au motif sont listés. Si `+` est ajouté au nom de la commande, chaque opérateur est listé avec sa famille d'opérateur de tri (s'il en a un).

`\dAp[+] [`access-method-pattern` [`operator-family-pattern`]]`

  Listes les procédures de support associées avec les familles d'opérateur (Section 38.16.3). Si `access-method-pattern` est spécifié, seules les fonctions des familles d'opérateur associées avec les méthodes d'accès dont le nom correspond au motif sont listées. Si `operator-family-pattern` est spécifié, seules les fonctions des familles d'opérateur dont les noms correspondent au motif sont listées. Si `+` est ajouté au nom de la commande, chaque fonction est affiché de façon verbeuse, avec sa liste réelle de paramètres.

`\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érateurs`, `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 Section 5.7.

`\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, `\dti` liste les index et tables. Si `+` est ajouté à la fin de la commande, chaque objet est listé avec son statut de persistence (permanent, temporaire, non journalisé), 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.

  ### Attention

  `\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[anptwS+] [ `motif` [ `motif_arg` ... ] ]`

  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 », « procedure », « trigger », or « window ». Afin de n'afficher que les fonctions d'un type spécifié, ajoutez les lettres correspondantes, respectivement `a`, `n`, `p`, `t`, or `w` à la commande. Si `motif` est spécifié, seules les fonctions dont le nom correspond au motif sont affichées. Tout argument supplémentaire est un motif pour un nom de type, faisant correspondance aux noms de type du premier argument de la fonction, puis du second, et ainsi de suite. (Les fonctions correspondantes peuvent avoir plus d'arguments que le nombre de types d'argument indiqués. Pour empêcher cela, ajoutez un tiret `-` comme fin pour `motif_arg`.) 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.

`\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` [ `motif_arg` [ `motif_arg` ] ] ]`

  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. Si un `motif_arg` est indiqué, seuls les opérateurs préfixes dont le nom du type de l'argument droit correspond au motif sont listés. Si deux `motif_arg` sont indiqués, seuls les opérateurs binaires dont les noms des types d'argument correspondent à ces motifs sont listés. (Autrement, écrivez `-` pour l'argument inutilisé d'un opérateur unaire.) 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 Section 5.7.

`\dP[itn+] [ `motif` ]`

  Liste les tables partitionnées. Si `motif` est spécifié, seules les entrées dont le nom correspond au motif sont listées. Les modificateurs `t` (tables) et `i` (index) peuvent être ajoutés à la commande pour filtrer le type d'objet à lister. Par défaut, les tables et index partitionnés sont listés.

  Si le modificateur `n` (« nested ») est indiqué, ou si un motif est spécifié, alors les partitions qui ne sont pas à la racine sont incluses, et une colonne indique le parent de chaque objet partitionné.

  Si `+` est ajouté à la commande, la somme des tailles de chaque partition est aussi affichée, ainsi que la description de la relation. Si `n` est combiné avec `+`, deux tailles sont affichées : l'une incluant la taille totale des partitions directement attachées, l'autre montrant la taille totale de toutes les partitions, y compris les sous-partitions attachées indirectement.

`\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.

`\dX [ `motif` ]`

  Liste les statistiques étendues. Si `motif` est indiqué, seules les statistiques étendues dont le nom correspond à ce motif sont listées.

  Le statut de chaque type de statistique étendue est affichée dans une colonne nommée d'après le type de statistique (par exemple Ndistinct). `defined` signifie qu'il a été réclamé lors de la création des statistiques, et NULL signifie qu'il n'a pas été réclamé. Vous pouvez utiliser `pg_stats_ext` si vous voulez savoir si la commande `ANALYZE` a été exécutée et si les statistiques sont disponibles pour le planificateur.

`\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.

  Si vous éditez un fichier ou la requête précédente, et que vous quittez l'éditeur sans modifier le fichier, le tampon de requête est effacé. Sinon 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édiatement ; 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é et supprimé du tampon de requête. Ce qui reste dans le tampon de requête est réaffiché. 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.

  ### Astuce

  Voir dans Environnement, ci-dessous, comment configurer et personnaliser votre éditeur.

`\echo `texte` [ ... ]`

  Affiche les arguments évalués sur la sortie standard, séparés par des espaces 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 (ni le premier argument).

  ### Astuce

  Si vous utilisez la commande `\o` pour rediriger la sortie de la requête, vous pouvez aussi utiliser `\qecho` au lieu de cette commande. See also `\warn`.

`\ef [ `description_fonction` [ `line_number` ] ]`

  Cette commande récupère et édite la définition de la fonction ou procédure désignée sous la forme d'une commande `CREATE OR REPLACE FUNCTION` ou `CREATE OR REPLACE PROCEDURE`. L'édition est faite de la même façon que pour `\edit`. Si vous quittez l'éditeur sans sauvegarder, la requête est annulée. Si vous sauvegardez et quittez l'éditeur, la commande mise à jour est exécutée immédiatement si vous y ajoutez un point-virgule. Sinon elle est ré-affichée 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.

  ### Astuce

  Voir dans Environnement, ci-dessous, 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`. Si vous quittez l'éditeur sans sauvegarder, la requête est annulée. Si vous sauvegardez et quittez l'éditeur, la commande mise à jour est exécutée immédiatement si vous y ajoutez un point-virgule. Sinon, elle est réaffichée ; 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 [ (`option`=`value` [...]) ] [ `filename` ]`
`\g [ (`option`=`value` [...]) ] [ |`command` ]`

  Envoie le tampon de requête en entrée vers le serveur pour exécution.

  Si des parenthèses apparaissent après `\g`, elles entourent une liste séparée par des espaces de clauses d'option formatées `option``=``value`, qui sont interprétées de la même façon que des commandes `\pset` `option` `value`, mais prennent effet seulement pour la durée de cette requête. Dans cette liste, les espaces ne sont pas permis autour des signes `=` mais sont requis entre chaque clause d'option. Si `=``value` sont omis, l'option nommée `option` est modifiée de la même façon que pour `\pset` `option` sans `value` explicite.

  Si un argument `filename` ou `|``command` est donné, la commande 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 renvoie 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. Avec des arguments, `\g` fournit une alternative « one-shot » à la commande `\o`, et permet en plus des ajustements uniques aux options de format de sortie normalement affectées par `\pset`.

  Quand le dernier 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.

`\gdesc`

  Affiche la description (c'est-à-dire les noms et types de données des colonnes) pour le résultat de la requête contenue dans le tampon. La requête n'est pas réellement exécutée. Cependant, si elle contient une erreur de syntaxe, l'erreur sera rapportée de la façon habituelle.

  Si le tampon de requête est vide, la requête la plus récemment envoyée est décrite à la place.

`\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
      -> \gexec
      CREATE 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 ci-dessous). 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 :var2
      bonjour 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_var2
      bonjour 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 [ (`option`=`value` [...]) ] [ `filename` ]`
`\gx [ (`option`=`value` [...]) ] [ |`command` ]`

  `\gx` est équivalent à `\g`, sauf qu'il force le mode de sortie étendue pour cette requête, comme si `expanded=on` était inclus dans la liste des options `\pset`. Voir aussi `\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.

  ### Note

  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.

  ### Note

  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 est_client,
          EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as est_employe
      \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.

  ### Astuce

  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_list`

  Affiche 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.

  ### Astuce

  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.

  ### Astuce

  Pour intercaler du texte entre des résultats de requête, utilisez `\qecho`.

`\p` ou `\print`

  Affiche 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.

  `csv_fieldsep`

    Spécifie le séparateur de champ à utiliser pour le format de sortie CSV. Lorsque le caractère de séparation apparaît dans la valeur d'un champ, le champ est affiché encadré par des guillemets, suivant les règles standards du CSV. La valeur par défaut est une virgule.

  `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, 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_zero`

    Configure 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 : `(`n` rows)`). Si le paramètre `valeur` est omis, la commande bascule entre l'affichage du pied de table ou sa désactivation.

  `format`

    Initialise le format d'affichage parmi `aligned`, `asciidoc`, `csv`, `html`, `latex`, `latex-longtable`, `troff-ms`, `unaligned` ou `wrapped`. Les abréviations uniques sont autorisées.

    Le format `aligned` est le format de sortie standard, lisible par les humains, plaisamment formaté ; c'est le format par défaut.

    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. Toutefois, le caractère séparateur n'est pas géré spécifiquement s'il apparaît dans la valeur d'une colonne ; le format CSV peut être mieux adapté pour ces cas de figure.

    Le format `csv` sort les valeurs des colonnes séparées par des virgules, en appliquant les règles d'échappement décrites dans la RFC 4180. Cette sortie est compatible avec le format CSV de la commande serveur `COPY`. Une ligne d'entête avec les noms des colonnes est produite sauf si le paramètre `tuples_only` est à `on`. Le titre et le pied de table ne figurent pas dans la sortie. Chaque ligne se termine par la séquence de fin de ligne qui dépend du système d'exploitation, et qui est typiquement un seul caractère de nouvelle ligne (`\n`) sur les systèmes Unix, ou une séquence constituée d'un retour chariot et nouvelle ligne (`\r\n`) sur Microsoft Windows. Un caractère de séparation de champs autre que la virgule peut être choisi avec `\pset csv_fieldsep`.

    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 `asciidoc`, `html`, `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. Le format `latex` utilise l'environnement `tabular` de LaTeX. Le format `latex-longtable` requiert 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 `PSQL_PAGER` ou `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.

  `recordsep`

    Indique 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_zero`

    Configure 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.

  ### Astuce

  Il existe plusieurs raccourcis de commandes pour `\pset`. Voir `\a`, `\C`, `\f`, `\H`, `\t`, `\T` et `\x`.

`\q` ou `\quit`

  Quitte 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 `\reset`

  Réinitialise (efface) le tampon de requêtes.

`\restrict `clé_mode_restreint``

  Entrez en mode « restreint » avec la clé fournie. Dans ce mode, la seule méta-commande autorisée est `\unrestrict` pour quitter le mode restreint. La clé ne doit contenir que des caractères alphanumériques.

  Cette commande a principalement comme but d'être utilisé avec les sauvegardes textes générées par pg_dump, pg_dumpall et pg_restore, mais elle peut être utile ailleurs.

`\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.

  ### Note

  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 less
      testdb=> \setenv LESS -imx4F

`\sf[+] `description_fonction``

  Cette commande récupère et affiche la définition d'une fonction ou procédure sous la forme d'une commande `CREATE OR REPLACE FUNCTION` ou `CREATE OR REPLACE PROCEDURE`. 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.

`\unrestrict `clé_mode_restreint``

  Quitte le mode restreint (un mode où toutes les autres méta-commandes sont bloquées), à condition que la clé indiquée corresponde à celle donnée à `\restrict` quand le mode restreint a été activé.

  Cette commande a principalement comme but d'être utilisé avec les sauvegardes textes générées par pg_dump, pg_dumpall et pg_restore, mais elle peut être utile ailleurs.

`\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.

`\warn `text` [ ... ]`

  Cette commande est identique à `\echo` sauf que la sortie sera écrite sur la sortie des erreurs de psql plutôt que la sortie standard.

`\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.

`\;`

  Un antislash suivi d'un point-virgule n'est pas une méta-commande comme les commandes précédentes. Cela permet d'ajouter un point-virgule au tampon de requête sans autre traitement.

  D'ordinaire, psql envoie une commande SQL au serveur dès qu'il atteint un point-virgule de fin de commande, y compris s'il reste du texte sur la ligne courante. Donc, par exemple :

      select 1; select 2; select 3;

  résultera en trois commandes SQL envoyées individuellement au serveur, les résultats de chacune étant affichés avant l'exécution de la commande suivante. Néanmoins, un point-virgule saisi avec un antislash avant, `\;`, ne déclenchera pas le traitement de la commande, pour que la commande précédente et la commande suivante soient en fait combinées et envoyées au serveur comme une seule requête. Par exemple

      select 1\; select 2\; select 3;

  résultera en l'envoi des trois commandes SQL en une seule requête lorsque le premier point-virgule sans antislash est atteint. Le serveur exécute une telle requête comme une seule transaction, sauf s'il y a des commandes `BEGIN`/`COMMIT` explicites incluses dans la chaîne pour la diviser en plusieurs transactions. (Voir Section 53.2.2.1 pour plus de détails sur la gestion par le serveur des chaînes de plusieurs requêtes.) psql n'affiche que les résultats de la dernière requête pour chaque chaîne qu'il reçoit. Dans cet exemple, bien que les trois `SELECT` sont exécutés, psql affichera seulement le `3`.

#### Motifs

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 de relation 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. Un motif de relation contenant deux points est interprété comme un nom de base suivi d'un motif de nom de schéma suivi d'un motif de nom d'objet. La partie sur le nom de la base de données ne sera pas traitée comme un motif et doit correspondre au nom de la base de données en cours, sinon une erreur sera renvoyée.

Un motif de schéma contenant un point (`.`) est interprété comme un nom de base suivi d'un motif de nom de schéma. Par exemple, `\dn mydb.*foo*` affiche tous les schémas dont le nom inclut `foo`. La partie sur le nom de la base de données ne sera pas traitée comme un motif et doit correspondre au nom de la base de données en cours, sinon une erreur sera renvoyée.

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 `.`, `(`R`+|)` pour ``R`*` et `(`R`|)` pour ``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`).

### Fonctionnalités avancées

#### Variables

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.

### Note

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`).

  ### Note

  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.

  ### Note

  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.

`DBNAME`

  Le 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é.

`ERROR`

  `true` si la dernière requête SQL a échoué, `false` si elle a réussi. Voir aussi `SQLSTATE`.

`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.

  ### Astuce

  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.

`HIDE_TABLEAM`

  Si cette variable est positionnée à `true`, le détail de la méthode d'accès d'une table n'est pas affiché. C'est surtout utile pour les tests de non-régression.

`HIDE_TOAST_COMPRESSION`

  Si cette variable est configurée à `true`, les détails sur la méthode de compression ne sont pas affichés. Ceci est principalement utile pour les tests de régression.

`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.

  ### Note

  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 :

      \set HISTFILE ~/.psql_history-:DBNAME

  dans `~/.psqlrc` fera en sorte que psql maintienne un historique pour chaque base.

  ### Note

  Cette fonctionnalité a été plagiée sans vergogne sur Bash.

`HISTSIZE`

  Le 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.

  ### Note

  Cette fonctionnalité a été plagiée sans vergogne sur Bash.

`HOST`

  L'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é.

`IGNOREEOF`

  Si 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.

  ### Note

  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. Les serveurs PostgreSQL depuis la version 12 ne gèrent plus la colonne système OID, et de ce fait LASTOID sera toujours à 0 à la suite d'une commande `INSERT` sur ces serveurs.

`LAST_ERROR_MESSAGE`
`LAST_ERROR_SQLSTATE`

  Le message d'erreur principal et le code SQLSTATE associé pour la plus récente requête en échec dans la session psql en cours, ou une chaîne vide et `00000` s'il n'y a eu aucune erreur dans la session actuelle.

`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.

`PORT`

  Le 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é.

`PROMPT1`
`PROMPT2`
`PROMPT3`

  Ils 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.

`ROW_COUNT`

  Le nombre de lignes renvoyées ou affectées par la dernière requête SQL, ou 0 si la requête a échoué ou si elle n'a pas renvoyée un nombre de lignes.

`SERVER_VERSION_NAME`
`SERVER_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` ou `sqlstate`. (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`

  Configurer cette variable à `on` est équivalent à l'option `-s` en ligne de commande.

`SQLSTATE`

  Le code d'erreur (voir Annexe A) associé avec l'échec de la dernière requête SQL, ou `00000` si elle a réussi.

`USER`

  L'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), `terse` (succinct) ou `sqlstate` 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.)

`VERSION`
`VERSION_NAME`
`VERSION_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.

#### Interpolation SQL

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 spéciale `:{?`name`}` renvoie TRUE ou FALSE suivant l'existence ou non de la variable, et est donc toujours substituée, sauf si le symbole deux-points est échappé avec un antislash.

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.

#### Invite

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:`/répertoire/nom`]`, si la socket de domaine Unix n'est pas dans l'emplacement par défaut défini à la compilation.

`%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 super-utilisateur, alors un `#` sinon un `>`. (L'expansion de cette valeur peut changer durant une session après une commande `SET SESSION AUTHORIZATION`.)

`%p`

  L'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`.

`%``chiffres`

  Le 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.

`%w`

  Espace blanc de même taille que la sortie la plus récente de `PROMPT1`. Cela peut être utilisé comme paramètre `PROMPT2`, pour que les instructions multi-lignes soient alignées avec la première ligne, mais il n'y a pas de deuxième prompt visible.

Pour insérer un pourcentage dans votre invite, écrivez `%%`. Les invites par défaut sont `'%/%R%x%# '` pour les invites 1 et 2 et `'>> '` pour l'invite 3.

### Note

Cette fonctionnalité a été plagiée sans vergogne sur tcsh.

#### Édition de la ligne de commande

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.)

## Environnement

`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.

`PGDATABASE`
`PGHOST`
`PGPORT`
`PGUSER`

  Paramètres de connexion par défaut (voir Section 34.15).

`PG_COLOR`

  Indique si la couleur doit être utilisée dans les messages de diagnostic. Les valeurs possibles sont `always`, `auto`, `never`.

`PSQL_EDITOR`
`EDITOR`
`VISUAL`

  É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. Si aucun des deux n'est configuré, le système utilise `vi` par défaut 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.

`PSQL_PAGER`
`PAGER`

  Si les résultats d'une requête ne tiennent pas sur l'écran, ils sont envoyés à cette commande. Les valeurs typiques sont `more` ou `less`. L'utilisation du paginateur peut être désactivé en configurant `PSQL_PAGER` ou `PAGER` à une chaîne vide ou en ajustant les options relatives au paginateur avec la commande `\pset`. Ces variables sont examinées dans l'ordre listé ; la première qui est configurée est utilisée. Si aucune n'est configurée, le comportement par défaut est d'utiliser `more` sur la plupart des plateformes et `less` sur Cygwin.

`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 34.15).

## Fichiers

`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`.

## Notes

- 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.

## Notes pour les utilisateurs sous Windows

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.

## Exemples

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 2
    Border 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 0
    Border 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 1
    Border style is 1.
    pierre@localhost testdb=> \pset format csv
    Output format is csv.
    pierre@localhost basetest=> \pset tuples_only
    Tuples only is on.
    pierre@localhost basetest=> SELECT second, premier FROM
    ma_table;
    un,1
    deux,2
    trois,3
    quatre,4
    pierre@localhost testdb=> \pset format unaligned
    Output format is unaligned.
    pierre@localhost testdb=> \pset fieldsep '\t'
    Field separator is "    ".
    pierre@localhost testdb=> SELECT second, first FROM my_table;
    un      1
    deux    2
    trois   3
    quatre  4

Vous pouvez aussi utiliser les commandes courtes :

    pierre@localhost basetest=> \a \t \x
    Output 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

De plus, ces options de format de sortie peuvent être affectées juste pour une requête en utilisant `\g` :

    pierre@localhost basetest=> SELECT * FROM my_table
    pierre@localhost basetest-> \g (format=aligned tuples_only=off expanded=on)
    -[ RECORD 1 ]-
    first  | 1
    second | one
    -[ RECORD 2 ]-
    first  | 2
    second | two
    -[ RECORD 3 ]-
    first  | 3
    second | three
    -[ RECORD 4 ]-
    first  | 4
    second | four

Voici un exemple utilisant la commande `\df` pour trouver seulementles fonctions dont le nom correspond à `int*pl` et donc le second argument est de type `bigint` :

    testdb=> \df int*pl * bigint
                              List of functions
       Schema   |  Name   | Result data type | Argument data types | Type
    ------------+---------+------------------+---------------------+------
     pg_catalog | int28pl | bigint           | smallint, bigint    | func
     pg_catalog | int48pl | bigint           | integer, bigint     | func
     pg_catalog | int8pl  | bigint           | bigint, bigint      | func
    (3 rows)

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 premier, second, premier > 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 second
    premier | 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 ord
    testdb(> FROM ma_table t1 CROSS JOIN ma_table t2 ORDER BY 1 DESC
    testdb(> \crosstabview "A" "B" "AxB" ord
     A | 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)