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 êtres lues à partir d'un fichier. De plus, il fournit un certain nombre de méta-commandes et plusieurs fonctionnalités style shell pour faciliter l'écriture des scripts et automatiser un nombre varié 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 aligné.)

-b, --echo-errors

Affiche les commandes SQL échouées sur la sortie standard des erreurs. C'est équivalent à configurer la variable ECHO à errors.

-c commande, --command=commande

Indique que psql doit exécuter une chaîne de commande, commande, puis s'arrêter. Cette option est utile dans les scripts shell. Les fichiers de démarrage (psqlrc et ~/.psqlrc) sont ignorés avec cette option.

commande doit être soit une chaîne de commandes complètement analysable par le serveur (c'est-à-dire qui ne contient aucune des fonctionnalités spécifiques de psql), soit une seule commande antislash. Du coup, vous ne pouvez pas mixer les commandes SQL et les méta-commandes psql avec cette option. Pour réussir ceci, vous pouvez envoyer la chaîne dans un tube vers psql, par exemple : echo "\x \\ SELECT * FROM foo;" | psql. (\\ est la méta-commande séparateur.)

Si la chaîne de commandes contient plusieurs commandes SQL, elles sont traitées dans une seule transaction sauf si des commandes BEGIN/COMMIT explicites sont inclues dans la chaîne pour la diviser en plusieurs transactions. Ceci est différent du comportement adopté quand la même chaîne est envoyée dans l'entrée standard de psql. De plus, seul le résultat de la dernière commande SQL est renvoyé.

À cause de ces comportements historiques, placer plus d'une commande dans la chaîne fournie à l'option -c a souvent des résultats inattendus. Il est préférable de fournir plusieurs commandes sur l'entrée standard de psql, soit en utilisant echo comme illustré ci-dessus, soit avec un document shell en ligne, par exemple :

psql <<EOF
\x
SELECT * FROM foo;
EOF

-d nombase, --dbname=nombase

Indique le nom de la base de données où se connecter. Ceci est équivalent à spécifier nombase comme premier argument de la ligne de commande qui n'est pas une option.

Si ce paramètre contient un signe = ou commence avec un préfixe valide d'URI (postgresql:// ou postgres://), il est traité comme une chaîne conninfo. Voir Section 31.1.1, « Chaînes de connexion » pour plus d'informations.

-e, --echo-queries

Copie toutes les commandes qui sont envoyées au serveur 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

Utilise le fichier nomfichier comme source des commandes au lieu de lire les commandes de façon interactive. Une fois que le fichier est entièrement traité, psql se termine. Ceci est globalement équivalent à la méta-commande \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éta-commande \q. 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 légère chance qu'utiliser cette option réduira la surcharge du lancement. 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

Active l'affichage en tableau HTML. Ceci est équivalent à \pset format html ou à la commande \H.

-l, --list

Liste toutes les bases de données disponibles puis quitte. Les autres option non relatives à la connexion sont ignorées. Ceci est similaire à la méta-commande \list.

-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 de commandes. Ceci est utile quand on veut désactiver la gestion de la tabulation pour l'action 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 des informations diverses. 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 à la commande \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éta-commandes sur une ligne, l'ordre d'exécution n'est pas toujours clair pour l'utilisateur non expérimenté.

-t, --tuples-only

Désactive l'affichage des noms de colonnes et le pied de page contenant le nombre de résultats, etc. Ceci est équivalent à la méta-commande \t.

-T options_table, --table-attr=options_table

Permet d'indiquer les options à placer à l'intérieur d'une balise table en HTML. Voir \pset 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éta-commande \set. Notez que vous devez séparer nom et valeur par un signe égal sur la ligne de commande. Pour désinitialiser une variable, enlevez le signe d'égalité. Pour simplement initialiser une variable sans valeur, utilisez le signe égal sans passer de valeur. Ces affectations sont réalisées lors de la toute première étape du lancement, du coup les variables réservées à des buts internes peuvent être é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éta-commande \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.

Cette option n'est jamais obligatoire car psql demandera automatiquement un mot de passe si le serveur exige une authentification par 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éta-commande \connect ainsi que la tentative de connexion initiale.

-x, --expanded

Active le mode de formatage de table étendu. Ceci est équivalent à la commande \x.

-X,, --no-psqlrc

Ne lit pas le fichier de démarrage (ni le fichier système psqlrc ni celui de l'utilisateur ~/.psqlrc).

-z, --field-separator-zero

Configure le séparateur de champs pour une sortie non alignée avec un octet zéro.

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

-1, --single-transaction

Quand psql exécute un script, ajouter cette option englobe le script avec les instructions BEGIN/COMMIT pour tout faire dans une seule transaction. Ceci nous assure que soit toutes les commandes se terminent avec succès, soit aucune modification n'est enregistrée.

Si le script utilise lui-même BEGIN, COMMIT ou ROLLBACK, cette option n'aura pas les effets désirés. De plus, si le script contient toute commande qui ne peut pas être exécutée à l'intérieur d'un bloc de transaction, indiquer cette option provoquera l'échec de cette commande (et du coup de la transaction entière).

-?, --help[=theme]

Affiche de l'aide sur psql puis quitte. Le paramètre optionnel theme (par défaut à options) sélectionne les parties de psql à expliquer : commands décrit les méta-commandes 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 se termine normalement, 1 s'il y a eu une erreur fatale de son fait (pas assez de mémoire, fichier introuvable), 2 si la connexion au serveur s'est interrompue ou a été annulée, 3 si une erreur est survenue dans un script et si la variable ON_ERROR_STOP a été initialisé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 que vous souhaitez connecter. psql peut connaître ces paramètres à partir d'options en ligne de commande, respectivement -d, -h, -p et -U. Si un argument autre qu'une option est rencontré, il est 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 les options ne sont pas requises, des valeurs par défaut sont applicables. Si vous omettez le nom de l'hôte, psql se connecte via un socket de domaine Unix à un serveur sur l'hôte local ou via TCP/IP sur localhost pour les machines qui n'ont pas 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 du 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 correctes, vous pouvez vous simplifier la vie 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 31.14, « Variables d'environnement »). Il est aussi intéressant d'avoir un fichier ~/.pgpass pour éviter d'avoir régulièrement à saisir des mots de passe. Voir Section 31.15, « Fichier de mots de passe » 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 31.17, « Recherches LDAP des paramètres de connexion ». Voir Section 31.1.2, « Mots clés de la chaîne de connexion » 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 renvoie une erreur et s'arrête.

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 cette méthode échoue, 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 (9.5.4)
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 est envoyée et exécutée sans erreur, les résultats de la commande sont affichés sur l'écran.

À chaque fois qu'une commande est exécutée, psql vérifie aussi les événements de notification générés par LISTEN(7) et NOTIFY(7).

Tant que des blocs de commentaire de tpe C sont passés au serveur pour traitement et suppression, les commentaires du standard SQL sont supprimés par psql.

Meta-commandes

Tout ce que vous saisissez dans psql qui commence par un antislash non échappé est une méta-commande psql qui est 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éta-commandes 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 à la ligne), \f (form feed), \chiffres (octal), and \xchiffres (hexadécimal). Un antislash précédant tout autre caractère dans une chaîne entre guillemets simples est ignoré.

Dans un argument, le texte qui est à l'intérieur de guillemets inverses (`) est pris sur une ligne de commande qui est passée au shell. La sortie de la commande (dont tous les retours à la ligne sont supprimés) replace le texte entre guillemets inverses.

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.

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 quand d'autres antislash non entre guillemets surviennent. Ceci est pris pour le début d'une nouvelle méta-commande. La séquence spéciale \\ (deux antislashes) marque la fin des arguments et continue l'analyse des commandes SQL, si elles existent. De cette façon, les commandes SQL et psql peuvent être mixées librement sur une ligne. Mais dans tous les cas, les arguments d'une meta-commande ne peuvent pas continuer après la fin de la ligne.

Les meta-commandes suivantes sont définies :

\a

Si le format actuel d'affichage d'une table 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 ]

Établie 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 soit les chaînes de connexion conninfo telles qu'elles sont détaillées dans Section 31.1, « Fonctions de contrôle de connexion à la base de données ».

Quand la méta-commande n'indique pas le nom de la base, l'utilisateur, l'hôte ou le port, la nouvelle connexion peut ré- utiliser les valeurs provenant de la connexion précédente. Par défaut, les valeurs de la connexion précédente sont ré-utilisées sauf lors du traitement d'une chaîne de connexion conninfo. Utiliser -reuse- previous=on ou -reuse-previous=off comme premier argument surcharge ce comportement. Quand la commande ne spécifie ou ne réutilise un paramètre particulier, la valeur par défaut de la libpq est utilisée. Utiliser - comme valeur d'un des paramètres nom_base, nom_utilisateur, hôte ou port est équivalent à l'omission de ce paramètre.

Si la nouvelle connexion est réussie, la connexion précédente est fermée. Si la tentative de connexion échoue (mauvais nom d'utilisateur, accès refusé, etc.), la connexion précédente est conservée si psql est en mode interactif. Lors de l'exécution d'un script non interactif, le traitement s'arrêtera immédiatement avec une erreur. Cette distinction a été choisie pour deux raisons : aider l'utilisateur face aux fautes de frappe et en tant que mesure de précaution pour qu'un script n'agisse pas par erreur sur la mauvaise base.

Exemples :

=> \c mydb myuser host.dom 6432
=> \c service=foo
=> \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable"
=> \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 ]

Modifie le répertoire courant par 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

Outputs information about the current database connection.

\copy { table [ ( liste_colonnes ) ] | ( requête ) } { from | to } { 'nomfichier' | program 'commande' | stdin | stdout | pstdin | pstdout } [ [ with ] ( option [, ...] ) ]

Réalise une opération de copy côté client. C'est une opération qui exécute une commande SQL, COPY(7), mais au lieu que le serveur lise ou écrive le fichier spécifié, psql lit ou écrit le fichier en faisant le routage des données entre le serveur et le système de fichiers local. Ceci signifie que l'accès et les droits du fichier sont ceux de l'utilisateur local, pas celui du serveur, et qu'aucun droit de superutilisateur n'est requis.

Quand la clause program est présente, commande est exécuté par psql et les données provenant ou fournies à commande sont routées entre le serveur et le client. Encore une fois, les droits d'exécution sont ceux de l'utilisateur local, et non pas du serveur, et que 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 populer des tables en ligne dans des scripts SQL. 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(7). Toutes les options autre que la source et destination sont comme il est spécifié pour COPY(7). A cause de cela, des règles spéciales d'analyse sont appliquées à la commande \copy. En particulier, les règles de variables de substitution et d'échappement des antislash de psql ne s'appliquent pas.

Astuce

Cette opération n'est pas aussi efficace que la commande COPY en SQL parce que toutes les données doivent passer au travers de la connexion client/serveur. Pour les grosses masses de données, la commande SQL est préférable.

\copyright

Affiche le copyright et les termes de distribution de PostgreSQL™.

\d[S+] [ motif ]

Pour chaque relation (table, vue, index, séquence ou table distante) ou type composite correspondant au motif, affiche toutes les colonnes, leur 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, ainsi que la définition de la vue si la relation est une vue. Pour les tables distantes, le serveur distant associé est aussi affiché. (Ce qui « Correspond au motif » est défini ci-dessous.)

Pour chaque type de relation, \d affiche des informations supplémentaires pour chaque colonne ; colonne valeur pour les séquences, expression indexée pour les index, options du wrapper de données distantes pour les tables distantes.

Le forme de la commande \d+ est identique, sauf que des informations plus complètes sont affichées : tout commentaire associé avec les colonnes de la table est affiché, ainsi que la présence d'OID dans la table, la définition de la vue (si la relation ciblée est une vue),un réglage de replica identity autre que celui par défaut.

Par défaut, seuls les objets créés par les utilisateurs sont affichés ; fournissez un motif ou le modificateur S pour afficher les objets systèmes.

Note

Si \d est utilisé sans argument motif, c'est équivalent, en plus commode, à \dtvsE qui affiche une liste de toutes les tables, vues, séquences et tables distantes.

\da[S] [ motif ]

Liste toutes les fonctions d'agrégat disponibles, avec lee type de 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èmes.

\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èmes. Si + est ajouté au nom de la commande, chaque objet est listé avec sa description associée.

\dC[+] [ motif ]

Liste les conversions de types. Si motif est indiqué, seules sont affichées les conversions dont le type source ou cible correspond au motif. Si + est ajouté au nom de la commande, chaque objet est listé avec sa description associée.

\dd[S] [ motif ]

Affiche les descriptions des objets du type contrainte, classe d'opérateur, famille d'opérateur, règle et trigger. Tous les autres commentaires peuvent être visualisés avec les commandes antislashs 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èmes.

Les descriptions des objets peuvent être ajoutées avec la commande SQL COMMENT(7).

\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(7) sert à positionner les privilèges d'accès par défaut. Le sens de l'affichage des privilèges est expliqué à la page de GRANT(7).

\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èmes. Si + est ajouté au nom de la commande, chaque objet est listé avec sa description associée.

\dE[S+] [ motif ], \di[S+] [ motif ], \dm[S+] [ motif ], \ds[S+] [ motif ], \dt[S+] [ motif ], \dv[S+] [ motif ]

Dans ce groupe de commandes, les lettres E, i, m, s, t et v correspondent respectivement à table distante, index, vue matérialisée, séquence, table et vue. Vous pouvez indiquer n'importe quelle combinaison de ces lettres, dans n'importe quel ordre, pour obtenir la liste de tous les objets de ces types. Par exemple, \dit liste les index et tables. Si + est ajouté à la fin de la commande, chaque objet est listé avec sa taille physique sur disque et sa description associée s'il y en a une. Si motif est spécifié, seuls les objets dont les noms correspondent au motif sont listés. Par défaut, seuls les objets créés par les utilisateurs sont affichés ; fournissez un motif ou le modificateur S pour afficher les objets systèmes.

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

\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 la liste de contrôle d'accès du serveur (ACL), type, version, options et description.

\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 distants (mnémonique : « external wrappers »). Si motif est spécifié, seuls les wrappers dont le nom correspond au motif sont affichés. Si la forme \dew+ est utilisée, les ACL, options et description du wrapper sont aussi affichées.

\df[antwS+] [ motif ]

Liste les fonctions, ainsi que leurs arguments, types de retour, et types de fonctions, qui sont classés comme « agg » (agrégat), « normal », « trigger », or « window ». Afin de n'afficher que les fonctions d'un type spécifié, ajoutez les lettres correspondantes, respectivement a, n, t, or w à la commande. Si motif est spécifié, seules les fonctions dont le nom correspond au motif sont affichées. Par défaut, seuls les objets créés par les utilisateurs sont affichés ; fournissez un motif ou le modificateur S pour afficher les objets systèmes. Si la forme \df+ est utilisée, des informations supplémentaires sur chaque fonction sont affichées, incluant la sécurité, volatibilitén, le propriétaire, le langage, le code source et la description.

Astuce

Pour rechercher des fonctions prenant des arguments ou des valeurs de retour d'un type spécifique, utilisez les capacités de recherche du paginateur pour parcourir la sortie de \df.

\dF[+] [ motif ]

Liste les configurations de la recherche plein texte. Si motif est spécifié, seules les configurations dont le nom correspond au motif seront affichées. Si la forme \dF+ est utilisée, une description complète de chaque configuration est affichée, ceci incluant l'analyseur de recherche plein texte et la liste de dictionnaire pour chaque type de jeton de l'analyseur.

\dFd[+] [ motif ]

Liste les dictionnaires de la recherche plein texte. Si motif est spécifié, seuls les dictionnaires dont le nom correspond au motif seront affichés. Si la forme \dFd+ est utilisée, des informations supplémentaires sont affichées pour chaque dictionnaire, ceci incluant le motif de recherche plein texte et les valeurs des options.

\dFp[+] [ motif ]

Liste les analyseurs de la recherche plein texte. Si motif est spécifié, seuls les analyseurs dont le nom correspond au motif seront affichés. Si la forme \dFp+ est utilisée, une description complète de chaque analyseur est affichée, ceci incluant les fonctions sous-jacentes et les types de jeton reconnu.

\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[+] [ motif ]

Liste les rôles des bases de données. (Comme les concepts des « utilisateurs » et « groupes » ont été unifiés dans les « rôles », cette commande est maintenant équivalente à \du.) 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 objets larges.

\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èmes. 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. 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èmes. Si + est ajouté à la fin de la commande, chaque objet sera affiché avec ses droits et son éventuelle description.

\do[S+] [ motif ]

Liste les opérateurs avec leur opérande et type en retour. Si motif est spécifié, seuls les opérateurs dont le nom correspond au motif sont listés. Par défaut, seuls les objets créés par les utilisateurs sont affichés ; fournissez un motif ou le modificateur S pour afficher les objets systèmes. 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èmes. 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(7) et REVOKE(7) sont utilisées pour configurer les droits d'accès. Les explications sur le sens de l'affichage des privilèges sont sous GRANT(7).

\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 - respectivement - 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 à un rôle ou à une base, respectivement.

Les commande ALTER ROLE(7) et ALTER DATABASE(7) servent à définir les paramètres de configuration par rôle et par base de donné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, ainsi que ses valeurs autorisées si c'est un type enum. 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èmes.

\du[+] [ motif ]

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.) Si motif est indiqué, seuls les rôles dont le nom correspond au motif sont listés. Si la forme \du+ est utilisée, des informations supplémentaires sont affichées pour chaque rôle ; actuellement, cela ajoute le commentaire pour chaque rôle.

\dx[+] [ motif ]

Affiche les extensions installées. Si motif est spécifié, seules les entensions dont le nom correspond au motif sont affichées. Avec la forme \dx+, tous les objets dépendants de chacune des extensions correspondantes sont également listés.

\dy[+] [ motif ]

Liste les triggers d'événements. Si motif est indiqué, seuls les triggers d'événements dont les noms correspondent au motif sont listés. Si + est ajouté au nom de la commande, chaque objet est listé avec sa description.

\e (or \edit) [ nomfichier ] [ numero_ligne ]

Si nomfichier est spécifié, le fichier est édité ; en quittant l'éditeur, son contenu 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 et édité à l'identique.

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. (Du coup, vous ne pouvez pas faire de scripts de cette façon. Utilisez \i pour cela.) Ceci signifie que si la requête se termine avec (ou contient) un point-virgule, elle est immédiatement exécutée. Dans les autres cas, elle attend simplement dans le tampon de requête un point-virgule ou un \g pour l'envoyer, ou encore un \r pour annuler.

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 la façon de configurer et personnaliser votre éditeur.

\echo texte [ ... ]

Affiche les arguments sur la sortie standard séparés par un espace et suivi 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.

Astuce

Si vous utilisez la commande \o pour rediriger la sortie de la requête, vous pourriez souhaiter utiliser \qecho au lieu de cette commande.

\ef [ description_fonction [ line_number ] ]

Cette commande récupère et édite la définition de la fonction désignée au moyen d'une commande CREATE OR REPLACE FUNCTION. L'édition est faite de la même façon que pour \edit. Après que l'éditeur se soit fermé, la commande mise à jour attend dans le tampon de requête ; tapez ; ou \g pour l'envoyer, ou \r pour l'annuler.

La fonction cible peut être spécifiée par son nom seul, ou par son nom et ses arguments, par exemple foo(integer, text). Les types d'arguments doivent être fournis s'il y a plus d'une fonction du même nom.

Si aucune fonction n'est spécifiée, un modèle d'ordre CREATE FUNCTION vierge est affiché pour édition.

Si vous indiquez un numéro de ligne, psql positionnera le curseur sur cette ligne dans le corps de la fonction. (Notez que le corps de la fonction ne commence pas sur la première ligne du fichier.)

Astuce

Voir dans Environnement la façon de configurer et personnaliser votre éditeur.

\encoding [ codage ]

Initialise l'encodage du jeu de caractères du client. Sans argument, cette commande affiche l'encodage actuel.

\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 (|). Voir aussi \pset comme moyen générique de configuration des options d'affichage.

\g [ nomfichier ], \g [ |commande ]

Envoie le tampon de requête en entrée vers le serveur et stocke en option la sortie de la requête dans nomfichier ou envoie dans un tube la sortie vers un autre shell exécutant commande. Le fichier ou la commande est écrite seulement si la requête renvoit zéro ou plus d'enregistrements, mais pas si la requête échoue ou s'il s'agit d'une commande SQL ne renvoyant pas de données.

Un simple \g est virtuellement équivalent à un point-virgule. Un \g avec argument est une alternative en « un coup » à la commande \o.

\gset [ préfixe ]

Envoie la requête courante du tampon au serveur et stocke le résultat de la requête dans des variables psql (voir Variables). La requête à exécuter doit renvoyer exactement une ligne. Chaque colonne de la ligne est enregistrée dans une variable séparée, nommée de la même façon que la colonne. Par exemple :

=> SELECT 'bonjour' AS var1, 10 AS var2
-> \gset
=> \echo :var1 :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.

\h (ou \help) [ commande ]

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

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 est pour la compatibilité mais voir \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 lu jusqu'à arriver à la fin de fichier ou à la méta-commande \q. Ceci peut être utilisé pour intégrer des entrées interactives avec 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.

\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 objet large PostgreSQL™. En option, il associe le commentaire donné avec l'objet. Exemple :

foo=> \lo_import '/home/peter/pictures/photo.xcf' 'une
photo de moi'
lo_import 152801

La réponse indique que l'objet large 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 objets larges PostgreSQL™ actuellement stockés dans la base de données, avec tous les commentaires fournis par eux.

\lo_unlink loid

Supprime l'objet large d'OID loid de la base de données.

Astuce

Utilisez \lo_list pour trouver l'OID d'un objet large.

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

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 intégrer du texte entre les résultats de requête, utilisez \qecho.

\p ou \print

Affiche le tampon de requête actuel sur la sortie standard.

\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 encore 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 tables résultat de la 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 bordure et de ligne mais ceci dépend du format. Dans le format HTML, cela se traduire 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 zero, alors le format wrapped affecte seulement la sortie écran. Si columns ne vaut pas zéro, alors les sorties fichier et tubes (pipe) font l'objet de retours à la ligne à cette largeur également.

expanded (ou x)

Si une valeur est précisée, elle doit être soit on soit off, ce qui activera ou désactivera le mode étendu, soit auto. Si valeur est omis, la commande bascule le paramètre entre les valeurs on et off. Quand le mode étendu est activé, les résultats des requêtes sont affichés sur deux colonnes, avec le nom de la colonne sur la gauche et ses données sur la droite. Ce mode est utile si la donnée ne tient pas sur l'écran dans le mode « horizontal » habituel. Dans le mode auto, le mode étendu est utilisé à chaque fois que la sortie de la requête est plus grande que l'écran. Sinon, le mode habituel est utilisé. Le mode auto est seulement intéressant lors de l'utilisation des formats aligné et wrapped . Si d'autres formats sont sélectionnés, il se comporte toujours comme si le mode étendu était désactivé.

fieldsep

Indique le séparateur de champ à utiliser dans le mode d'affichage non aligné. De cette façon, vous pouvez créer, par exemple, une sortie séparée par des tabulations ou des virgules, que d'autres programmes pourraient préférer. Pour configurer une tabulation comme champ séparateur, saisissez \pset fieldsep '\t'. Le séparateur de champ par défaut est '|' (une barre verticale).

fieldsep_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 table (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 unaligned, aligned, wrapped, html, asciidoc, latex (utilise tabular), latex-longtable ou troff-ms. Les abréviations uniques sont autorisées. (ce qui signifie qu'une lettre est suffisante.)

Le format unaligned écrit toutes les colonnes d'un enregistrement sur une seule ligne, séparées par le séparateur de champ courant. Ceci est utile pour crééer des sorties qui doivent être lues par d'autres programmes (au format séparé par des caractère tabulation ou par des virgules, par exemple).

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

Le format wrapped est comme aligned, sauf qu'il retourne à la ligne dans les données de grande taille afin que la sortie tienne dans la largeur de colonne cible. La largeur cible est déterminée comme cela est décrit à l'option columns. Notez que psql n'essaie pas de revenir à la ligne dans les titres de colonnes. Par conséquent, si la largeur totale nécessaire pour le titre de colonne est plus grande que la largeur cible, le format wrapped se comporte de la même manière que aligned.

Les formats html, asciidoc, latex, latex-longtable et troff-ms produisent des tables destinées à être inclues dans des documents utilisant le langage de marques respectif. Ce ne sont pas des documents complets ! Ce n'est pas forcément nécessaire en HTML mais en LaTeX, vous devez avoir une structure de document complet. latex-longtable nécessite aussi les paquets LaTeX longtable et booktabs.

linestyle

Positionne le style des lignes de bordure sur ascii, old-ascii unicode. Les abréviations uniques sont autorisées. (Cela signifie qu'une lettre suffit.) La valeur par défaut est ascii. Cette option affecte seulement les formats de sortie aligned et wrapped.

Le style ascii utilise les caractères basiques ASCII . Les retours à la ligne dans les données sont représentés par un symbole + dans la marge de droite. Si le format wrapped est sélectionné, un retour chariot est ajouté à l'affichage pour les valeurs dont la taille à l'affichage est trop importante pour tenir dans une cellule de la colonne associée. Un point (.) est affiché dans la marge droite de la ligne avant le retour chariot et un autre point est affiché 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, vous pouvez préférer afficher \pset null '(null)'.

numericlocale

Si valeur est précisée, elle doit valoir soit on, soit off afin d'activer ou désactiver l'affichage d'un caractère dépendant de la locale pour séparer des groupes de chiffres à gauche du séparateur décimal. Si valeur est omise, la commande bascule entre la sortie numérique classique et celle spécifique à la locale.

pager

Contrôle l'utilisation d'un paginateur pour les requêtes et les affichages de l'aide de psql. Si la variable d'environnement PAGER est configurée, la sortie est envoyée via un tube 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é".

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.

pager_min_lines

Si pager_min_lines est configuré à un numéro supérieur à la hauteur de page, le programme de pagination ne sera pas appelé sauf s'il y a au moins ce nombre de lignes à afficher. La configuration par défaut est 0.

recordsep_zero

Configure le séparateur d'enregistrements pour qu'il utilise un octet zéro dans le format non aligné en sortie.

tableattr (or T)

Dans le format HTML, ceci indique les attributs à placer dans la balise table tag. Cela pourrait être par exemple cellpadding ou bgcolor. Notez que vous ne voulez probablement pas spécifier border car c'est 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 [ texte ]

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 entê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, \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.

\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 seulement un 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.

Bien que vous puissiez configurer toute variable comme vous le souhaitez, psql traite certaines variables de façon spéciale. Elles sont documentées dans la section sur les variables.

Note

Cette commande est sans relation avec la commande SQL SET(7).

\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 sous la forme d'une commande CREATE OR REPLACE FUNCTION. La définition est affichée via le canal de sortie courant, tel que défini par \o.

La fonction cible peut être spécifiée par son seul nom, ou bien par ses nom et arguments, par exemple, foo(integer, text). Fournir les types des arguments devient obligatoire si plusieurs fonctions portent le même nom.

Si + est ajouté à la commande, les numéros de lignes sont affichés, la ligne 1 débutant à partir du corps de la fonction.

\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 ]

Sans paramètre, affiche le temps pris par chaque instruction SQL, en millisecondes, ou arrête cet affichage. Avec paramètre, force la valeur au paramètre.

\unset nom

Désinitialise (supprime) la variable psql nom.

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

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

\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 droit d'accès associé. 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 ]

Lance un shell séparé ou exécute la commande shell commande. Les arguments ne sont pas interprétés, le shell les voit tel quel. En particulier, les règles de substitution de variables et les échappements d'antislash ne s'appliquent pas.

\? [ theme ]

Affiche l'aide. Le paramètre optionnel theme (par défaut à commands) sélectionne les parties de psql à expliquer : commands décrit les méta-commandes 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.

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 en priorité dans le chemin de recherche. Cela est équivalent à dire que l'objet peut être référencé par son nom sans préciser explicitement le schéma.) Pour voir tous les objets de la base quelle que soit leur visibilité, utilisez le motif *.* .

À l'intérieur d'un motif, * correspond à toute séquence de caractères (et aussi à aucun) alors que ? ne correspond qu'à un seul caractère. (Cette notation est comparable à celle des motifs de nom de fichier Unix.) Par exemple, \dt int* affiche les tables dont le nom commence avec int. Mais à l'intérieur de guillemets doubles, * et ? perdent leurs significations spéciales et sont donc traités directement.

Un motif qui contient un point (.) est interprété comme le motif d'un nom de schéma suivi par celui d'un nom d'objet. Par exemple, \dt foo*.*bar* affiche toutes les tables dont le nom inclut bar et qui sont dans des schémas dont le nom commence avec foo. Sans point, le motif correspond seulement avec les objets qui sont visibles dans le chemin de recherche actuel des schémas. De nouveau, un point dans des guillemets doubles perd sa signification spéciale et est traité directement.

Les utilisateurs avancés peuvent utiliser des expressions rationnelles comme par exemple les classes de caractère ([0-9] pour tout chiffre). Tous les caractères spéciaux d'expression rationnelle fonctionnent de la façon indiquée dans Section 9.7.3, « Expressions rationnelles POSIX », 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, quel que soit sa longueur. Le nom doit consister en des lettres (includant des lettres non latines), des chiffres et des tirets bas.

Pour configurer une variable, utilisez la méta-commande 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éta-commandes 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 (ou 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, 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. Bien que vous pouvez utiliser ces variables dans d'autres buts, cela n'est pas recommandé, car le comportement du programme pourrait devenir vraiment étrange très rapidement. La convention veut que tous les noms de variables traités spécialement utilisent des lettres ASCII en majuscule (avec en option des chiffres et des tirets bas). Pour s'assurer une compatibilité maximum dans le futur, éviter d'utiliser de tels noms de variables pour votre propre besoin. 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éttion d'un mot clé SQL. Si c'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 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 ceci 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 ceci est -b. Si elle n'est pas configurée ou si elle est configurée à none (ou toute autre valeur que celles ci-dessus), 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.

ENCODING

Le codage courant du jeu de caractères du client.

FETCH_COUNT

Si cette variable est un entier positif, les résultats de la requête 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.

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 n'est pas initialisée ou si elle est configurée avec none (ou toute autre valeur que celles-ci, toutes les lignes lues dans le mode interactif sont sauvegardées dans la liste de l'historique.

Note

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

HISTFILE

Le nom du fichier utilisé pour stocker l'historique. La valeur par défaut est ~/.psql_history. Par exemple, utiliser :

\set HISTFILE ~/.psql_history- :DBNAME

dans ~/.psqlrc fera que psql maintiendra un historique séparé pour chaque base de données.

Note

Cette fonctionnalité a été plagiée sans honte à partir de Bash.

HISTSIZE

Le nombre de commandes à stocker dans l'historique des commandes. La valeur par défaut est 500.

Note

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

HOST

L'hôte du serveur de la base de données où 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 désinitialisé.

IGNOREEOF

Si non initialisé, envoyer un caractère EOF (habituellement Ctrl+D) dans une session interactive de psql ferme l'application. Si elle est configurée avec une valeur numérique, ce nombre de caractères EOF est ignoré avant la fin de l'application. Si la variable est configurée mais n'a pas de valeur numérique, la valeur par défaut est de 10.

Note

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

LASTOID

La valeur du dernier OID affecté, renvoyée à partir d'une commande INSERT ou lo_import. La validité de cette variable est seulement garantie jusqu'à l'affichage du résultat de la commande SQL suivante.

ON_ERROR_ROLLBACK

Lorsqu'il est actif (on), si une instruction d'un bloc de transaction génère une erreur, cette dernière est ignorée et la transaction continue. Lorsqu'il vaut interactive, ces erreurs sont seulement ignorées lors des sessions interactives, mais ne le sont pas lors de la lecture de scripts. Lorsqu'il n'est pas configuré ou quand il vaut off, une instruction générant une erreur dans un bloc de transaction annule la transaction complète. Le mode on_error_rollback-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 dernier 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. Dans le 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 haut niveau et tout autre script qui pourrait avoir été appelé) sera terminé immédiatement. Si la chaîne de commande de 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 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.

SINGLELINE

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

SINGLESTEP

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

USER

L'utilisateur de la base de données où 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 désinitialisé.

VERBOSITY

Cette variable peut être configurée avec les valeurs default, verbose (bavard) ou terse (succinct) pour contrôler la verbosité des rapports d'erreurs.

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éta-commandes. 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 backslash. 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 les 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 backslash pour le protéger des substitutions.

La syntaxe deux-points pour les variables est du SQL standard pour les langages de requête embarqués, comme ECPG. La syntaxe avec les deux-points pour les tranches de tableau et les conversions de types sont des extensions PostgreSQL™ extensions, 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 parce que la commande n'a pas été terminée avec un point-virgule ou parce 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 superutilisateur, alors un # sinon un >. (L'expansion de cette valeur peut changer durant une session après une commande SET SESSION AUTHORIZATION.)

%R

Sur l'invite 1, habituellement =, mais ^ en mode une-ligne, ou ! si la session est déconnectée de la base de données (ce qui peut arriver si \connect échoue). Sur l'invite 2, %R est remplacé par un caractère dépendant de ce que psql attend en entrée : - si la commande n'est pas terminée, * si le commentaire /* ... */ n'est pas terminé, un guillement simple si la chaîne de caractère n'est pas terminée, un guillemet double si l'identifiant entre guillemets doubles n'est pas terminé, un dollar si une chaîne entre dollars n'est pas terminée ou ( s'il manque une parenthèse gauche. Dans l'invite 3, %R ne produit rien.

%x

État de la Transaction : une chaîne vide lorsque vous n'êtes pas dans un bloc de transaction ou * si vous vous y trouvez, ou ! si vous êtes dans une transaction échouée, ou enfin ? lorsque l'état de la transaction est indéterminé (par exemple à cause d'une rupture de la connexion).

%l

Le numéro de ligne dans la requête courante, en commençant à partir 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 pairs multiples de ceux-ci pourraient survenir à l'intérieur de l'invite. Par exemple :

basetest=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '

a pour résultat une invite en gras (1;), jaune sur noir (33;40) sur les terminaux compatibles VT100.

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

Note

Cette fonctionnalité a été plagiée 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 quelques raisons 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.

PAGER

Si les résultats d'une requête ne tiennent pas sur l'écran, ils sont envoyés via un tube sur cette commande. Les valeurs typiques sont more ou less. La valeur par défaut dépend de la plateforme. L'utilisation du paginateur peut être désactivée en utilisant la commande \pset.

PGDATABASE, PGHOST, PGPORT, PGUSER

Paramètres de connexion par défaut (voir Section 31.14, « Variables d'environnement »).

PSQL_EDITOR, EDITOR, VISUAL

Éditeur utilisé par les commandes \e et \ef. Les variables sont examinées dans l'ordre donné ; la première initialisée est utilisée.

Les éditeurs intégrés par défaut sont vi sur les systèmes Unix et notepad.exe sur les systèmes Windows.

PSQL_EDITOR_LINENUMBER_ARG

Lorsque les commandes \e ou \ef sont utilisées avec un argument spécifiant le numéro de ligne, cette variable doit indiquer l'argument en ligne de commande à fournir à l'éditeur de texte. Pour les éditeurs les plus courants, tels qu'emacs™ ou vi™, vous pouvez simplement initialiser cette variable avec le signe +. Il faut inclure le caractère d'espacement en fin de la valeur de la variable si la syntaxe de l'éditeur nécessite un espace entre l'option à spécifier et le numéro de ligne. Par exemple :

PSQL_EDITOR_LINENUMBER_ARG='+'
PSQL_EDITOR_LINENUMBER_ARG='--line '

La valeur par défaut est + sur les systèmes Unix (ce qui correspond à la bonne configuration pour l'éditeur par défaut, vi, et est utilisable généralement avec la plupart des éditeurs courants) ; par contre, il n'y a pas de valeur par défaut pour les systèmes Windows.

PSQL_HISTORY

Emplacement alternatif pour le fichier d'historique des commandes. L'expansion du symbôle ~ est réalisée.

PSQLRC

Emplacement alternatif pour le fichier .psqlrc de l'utilisateur. L'expansion du symbôle ~ est réalisée.

SHELL

Commande exécutée par la commande \!.

TMPDIR

Répertoire pour stocker des fichiers temporaires. La valeur par défaut est /tmp.

Cet outil, comme la plupart des autres outils PostgreSQL™, utilise aussi les variables d'environnement supportées par la bibliothèque libpq (voir Section 31.14, « Variables d'environnement »).

Fichiers

psqlrc et ~/.psqlrc

Sauf si une option -X ou -c 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 d'environnement PSQL_HISTORY.

Notes

Dans une vie précédente, psql permettait au premier argument d'une commande antislash à une seule lettre de commencer directement après la commande, sans espace séparateur. À partir de PostgreSQL™ 8.4, ce n'est plus autorisé.
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 n'est pas 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 assurez que la version utilisée correspond au serveur respectif. En pratique, cette complication supplémentaire n'est pas nécessaire.

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 "ma_table"
 Attribute |  Type   |      Modifier
-----------+---------+--------------------
 premier   | integer | not null default 0
 second    | text    |

Maintenant, changeons l'invite par quelque chose de plus intéressant :

basetest=> \set PROMPT1 '%n@%m %~%R%# '
peter@localhost basetest=>

Supposons que nous avons rempli la table de données et que nous voulons les regarder :

peter@localhost basetest=> SELECT * FROM ma_table;
 premier | second
---------+--------
       1 | one
       2 | two
       3 | three
       4 | four
(4 rows)

Vous pouvez afficher cette table de façon différente en utilisant la commande \pset :

peter@localhost basetest=> \pset border 2
Border style is 2.
peter@localhost basetest=> SELECT * FROM ma_table;
+---------+--------+
| premier | second |
+---------+--------+
|       1 | one    |
|       2 | two    |
|       3 | three  |
|       4 | four   |
+---------+--------+
(4 rows)

peter@localhost basetest=> \pset border 0
Border style is 0.
peter@localhost basetest=> SELECT * FROM ma_table;
premier second
------- ------
      1 one
      2 two
      3 three
      4 four
(4 rows)

peter@localhost basetest=> \pset border 1
Border style is 1.
peter@localhost basetest=> \pset format unaligned
Output format is unaligned.
peter@localhost basetest=> \pset fieldsep ","
Field separator is ",".
peter@localhost basetest=> \pset tuples_only
Showing only tuples.
peter@localhost basetest=> SELECT second, first FROM
ma_table;
one,1
two,2
three,3
four,4

Vous pouvez aussi utiliser les commandes courtes :

peter@localhost basetest=> \a \t \x
Output format is aligned.
Tuples only is off.
Expanded display is on.
peter@localhost basetest=> SELECT * FROM ma_table;
-[ RECORD 1 ]-
first  | 1
second | one
-[ RECORD 2 ]-
first  | 2
second | two
-[ RECORD 3 ]-
first  | 3
second | three
-[ RECORD 4 ]-
first  | 4
second | four

Documentation PostgreSQL 9.5.4 -

Applications client de PostgreSQL

psql

Synopsis

Description

Options

Note

Code de sortie

Usage

Se connecter à une base de données

Saisir des commandes SQL

Meta-commandes

Astuce

Astuce

Note

Attention

Astuce

Astuce

Astuce

Astuce

Note

Note

Astuce

Astuce

Astuce

Astuce

Note

motifs

Fonctionnalités avancées

Variables

Note

Note

Note

Astuce

Note

Note

Note

Note

Interpolation SQL

Invite

Note

Édition de la ligne de commande

Environnement

Fichiers

Notes

Notes pour les utilisateurs sous Windows

Exemples