| > > > | |
 pg_restore
|
reindexdb
|
psql [option...] [nombase [nomutilisateur]]
psql est une interface en mode texte pour PostgreSQL™. Il vous permet de saisir des requêtes de façon interactive, de les exécuter sur PostgreSQL™ et de voir les résultats de ces requêtes. Alternativement, les entrées peuvent ê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.
Affiche toutes les lignes en entrée sur la sortie standard lorsqu'elles sont lues. Ceci est plus utile dans le traitement de scripts que dans le mode interactif. C'est équivalent à initialiser la variable ECHO à all.
Bascule dans le mode d'affichage non aligné. (Le mode d'affichage par défaut est aligné.)
Indique que psql doit exécuter une chaîne de commande, commande, puis s'arrêter. Cette option est utile dans les scripts shell.
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. Pour réussir ceci, vous pouvez envoyer la chaîne dans un tube vers psql comme ceci : echo "\x \\ select * from foo;" | psql.
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.
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.
Copie toutes les commandes qui sont envoyées au serveur sur la sortie standard. Ceci est équivalent à initialiser la variable ECHO à queries.
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 dans psql.
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 commande interne \i.
Si nomfichier est un - (tiret), alors l'entrée standard est lue.
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.
Utilisez séparateur comme champ séparateur pour un affichage non aligné. Ceci est équivalent à \pset fieldsep ou \f.
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.
Active l'affichage en tableau HTML. Ceci est équivalent à \pset format html ou à la commande \H.
Liste toutes les bases de données disponibles puis quitte. Les autres option non relatives à la connexion sont ignorées. Ceci est similaire à la commande interne \list.
Écrit tous les résultats des requêtes dans le fichier nomfichier en plus de la destination habituelle.
Dirige tous les affichages de requêtes dans le fichier nomfichier. Ceci est équivalent à la commande \o.
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.
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.
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. À l'intérieur de psql, vous pouvez aussi initialiser la variable QUIET pour arriver au même effet.
Utilisez séparateur comme séparateur d'enregistrement pour un affichage non aligné. Ceci est équivalent à la commande \pset recordsep.
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'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]](images/note.png)
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é.
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.
Permet d'indiquer les options à placer à l'intérieur
d'une balise table
en HTML. Voir
\pset
pour plus de détails.
Force psql à demander le nom et le mot de passe de l'utilisateur avant de se connecter à la base de données.
Cette option est obsolète, car elle est conceptuellement mauvaise. (Demander un nom d'utilisateur autre que celui par défaut et demander un mot de passe parce que le serveur l'exige sont deux choses tout à fait différentes.) Il est conseillé d'utiliser les options -U et -W à la place.
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.)
Réalise une affectation de variable comme la commande interne \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.
Affiche la version de psql et quitte.
Force psql à demander un mot de passe avant de se connecter à une base de données.
psql devrait automatiquement demander un mot de passe chaque fois que le serveur réclame une authentification par mot de passe. Néanmoins, la détection de demande de mot de passe n'est actuellement pas totalement fiable, d'où cette option pour forcer une demande. Si aucune demande de mot de passe n'est effectuée et que le serveur requiert une authentification par mot de passe, la tentative de connexion échoue.
Cette option reste configurée pour la session complète, même si vous modifiez la connexion de la base de données avec la méta-commande \connect.
Active le mode de formatage de table étendu. Ceci est équivalent à la commande \x.
Ne lit pas le fichier de démarrage (ni le fichier système psqlrc ni celui de l'utilisateur ~/.psqlrc).
Affiche de l'aide sur les arguments en ligne de commande de psql et quitte.
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.
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 Unix, 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 28.11, « 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 28.12, « Fichier de mots de passe » pour plus d'informations.
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.
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 testdb
Welcome to psql 8.1.15, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help with psql commands
\g or terminate with semicolon to execute query
\q to quit
testdb=>
À 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 et NOTIFY.
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 devez l'envelopper dans des guillemets simples. Pour inclure un guillemet simple dans un argument, précédez-le d'un antislash. Tout ce qui est contenu entre des guillemets simples est de plus sujet à des substitutions style C pour \n (nouvelle ligne), \t (tabulation), \chiffres (octal) et \xchiffres (hexadécimal).
Si un argument sans guillemets commence avec un caractère :, il est pris pour une variable psql et la valeur de la variable est utilisée à la place de l'argument.
Les arguments placés entre guillemets arrières (`) sont pris comme une ligne de commande passée au shell. L'affichage de la commande (sans l'éventuel saut de ligne à la fin) est pris comme valeur de l'argument. Cela s'applique aussi aux séquences d'échappement ci-dessus.
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 :
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.
Modifie le répertoire courant par répertoire. Sans argument, le répertoire personnel de l'utilisateur devient le répertoire courant.
![[Astuce]](images/tip.png)
Pour afficher votre répertoire courant, utilisez \!pwd.
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.)
Établit une connexion à une nouvelle base de données et/ou sous un nom d'utilisateur. La connexion précédente est fermée. Si nomdb est -, le nom de la base de données actuelle est supposé.
Si nomutilisateur est omis, le nom de l'utilisateur courant est supposé.
Comme règle spéciale, \connect sans autre argument se connecte à la base de données par défaut en tant que l' utilisateur par défaut (comme ce que vous auriez obtenu en lançant psql sans arguments).
Si la tentative de connexion échoue (mauvais nom utilisateur, accès interdit, etc.), la connexion précédente est conservée si et seulement si psql est en mode interactif. Lorsqu'il exécute un script non interactif, le traitement s'arrête immédiatement avec une erreur. Cette distinction a été choisie pour empêcher les problèmes de typographie et comme un mécanisme de sécurité pour que les scripts n'agissent pas sur la mauvaise base de données.
Réalise une opération de copy côté client. C'est une opération qui exécute une commande SQL, COPY, mais au lieu que le serveur lise ou écrive le fichier spécifié, psql lit ou écrit le fichier en faisant le routage des données entre le serveur et le système de fichiers local. Ceci signifie que l'accès et les droits du fichier sont ceux de l'utilisateur local, pas celui du serveur, et qu'aucun droit de superutilisateur n'est requis.
La syntaxe de la commande est similaire à celle de la commande COPY SQL. Notez que, à cause de cela, des règles spéciales d'analyse s'appliquent à la commande \copy. En particulier, les règles de substitution de variable et d'échappement antislash ne s'appliquent pas.
\copy table from stdin | stdout lit/écrit basé sur l'entrée standard de la commande ou sa sortie standard respectivement. Toutes les lignes sont lues à partir de la même source qui a lancé la commande, en continuant jusqu'à ce que \. soit lu ou que le flux parvienne à EOF. La sortie est envoyée au même endroit que la sortie de la commande. Pour lire/écrire à partir de l'entrée et de la sortie standard de psql, utilisez pstdin ou pstdout. Cette option est utile pour peupler des tables en ligne à l'intérieur d'un fichier script SQL.
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.
Affiche le copyright et les termes de distribution de PostgreSQL™.
Pour chaque relation (table, vue, index ou séquence) correspondant au modèle, 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. (Ce qui « Correspond au modèle » est défini ci-dessous.)
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.
Si \d est utilisé sans argument modèle, c'est équivalent en plus commode à \dtvs qui affiche une liste de toutes les tables, vues et séquence.
Liste toutes les fonctions d'agrégat disponibles, avec les types de données sur lesquels elles opèrent. Si modèle est spécifié, seuls les agrégats dont les noms commencent par le modèle sont affichés.
Liste tous les tablespaces disponibles. Si modèle est spécifié, seuls les tablespaces dont le nom correspond au modèle sont affichés. Si + est ajouté au nom de la commande, chaque objet est listé avec les droits associés.
Liste toutes les conversions disponibles entre les encodages de jeux de caractères. Si modèle est spécifié, seules les conversions dont le nom correspond au modèle sont listées.
Liste toutes les conversions de types disponibles.
Affiche les descriptions des objets correspondant au modèle ou de tous les objets si aucun argument n'est donné. Mais dans tous les cas, seuls les objets qui ont une description sont listés. (Le terme « objet » couvre les agrégats, les fonctions, les opérateurs, les types, les relations (tables, vues, index, séquences, objets larges), les règles et les déclencheurs.) Par exemple, :
=> \dd version
Object descriptions
Schema | Name | Object | Description
------------+---------+----------+---------------------------
pg_catalog | version | function | PostgreSQL version string
(1 row)
Les descriptions des objets peuvent être ajoutées avec la commande SQL COMMENT.
Liste tous les domaines disponibles. Si modèle est spécifié, seuls les domaines correspondant sont affichés.
Liste toutes les fonctions disponibles avec leurs arguments et les types en retour. Si modèle est spécifié, seules les fonctions dont le nom correspond au modèle sont affichées. Si la forme \df+ est utilisée, des informations supplémentaires sur chaque fonction, dont le langage et la description, sont proposées.
Pour rechercher des fonctions prenant un argument ou des valeurs de retour d'un type spécifique, utilisez les capacités de recherche du paginateur pour parcourir \df output.
Pour réduire les redondances, \df n'affiche pas les fonctions d'entrées/sorties des types de données. Ceci est implémenté en ignorant les fonctions qui acceptent ou renvoient cstring.
Liste tous les rôles des bases de données. Si modèle est spécifié, seuls les rôles dont le nom correspond au modèle sont listés. (Cette commande est maintenant réellement identique à \du.)
Ceci n'est pas le nom réel de la commande : les lettres i, s, t, v, S correspondent respectivement à index, séquence, table, vue et table système. Vous pouvez spécifier une ou toutes ces lettres, dans n'importe quel ordre, pour obtenir une liste de tous les objets correspondants. La lettre S restreint la liste aux objets système ; sans S, seuls les objets non système sont affichés. Si + est ajouté au nom de la commande, chaque objet est listé avec sa description associée, si celle-ci est disponible.
Si modèle est spécifié, seuls les objets dont les noms correspondent au modèle sont listés.
Ceci est un alias pour \lo_list, qui affiche une liste des objets larges.
Liste tous les schémas disponibles (espace logiques). Si modèle (une expression régulière) est spécifiée, seuls les schémas dont le nom correspond au modèle sont listés. Tout schéma temporaire non local est supprimé. Si + est ajoutée au nom de la commande, chaque objet est listé avec ses droits et description associés.
Liste tous les opérateurs disponibles avec leur opérande et type en retour. Si modèle est spécifié, seuls les opérateurs dont le nom correspond au modèle sont listés.
Produit une liste de toutes les tables, vues et séquences disponibles avec leur droits d'accès associés. Si modèle est spécifié, seules les tables, vues et séquences dont le nom correspond au modèle sont listées.
Les commandes GRANT et REVOKE sont utilisées pour configurer les droits d'accès. Voir GRANT pour plus d'informations.
Liste tous les types de données ou seulement ceux dont le nom correspond à modèle. La commande \dT+ affiche des informations supplémentaires.
Liste tous les rôles de la base de données ou seulement ceux dont le nom correspond au modèle.
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 argument n'est fourni, le tampon de requête actuel est copié dans un fichier temporaire qui est ensuite édité de la même façon.
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 aussi que si la requête se termine avec (ou plutôt contient) un point-virgule, elle est immédiatement exécutée. Dans les autres cas, elle attend simplement dans le tampon de requête.
psql recherche les variables d'environnement PSQL_EDITOR, EDITOR et VISUAL (dans cet ordre) pour connaître l'éditeur à utiliser. Si aucun n'est initialisé, vi est utilisé sur les systèmes Unix, notepad.exe sur les systèmes Windows.
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.
Si vous utilisez la commande \o pour rediriger la sortie de la requête, vous pourriez souhaiter utiliser \qecho au lieu de cette commande.
Initialise l'encodage du jeu de caractères du client. Sans argument, cette commande affiche l'encodage actuel.
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.
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 Unix exécutant commande. Un simple \g est virtuellement équivalent à un point-virgule. Un \g avec argument est une alternative en « un coup » à la commande \o.
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.
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.
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.
Lit l'entrée à partir du fichier nomfichier et l'exécute comme si elle avait été saisie sur le clavier.
Si vous voulez voir les lignes sur l'écran au moment de leur lecture, vous devez initialiser la variable ECHO à all.
Liste les noms, propriétaires et codages des ensembles de caractères de toutes les bases de données du serveur. Si + est ajouté au nom de la commande, les descriptions des bases de données sont aussi affichées.
Lit l'objet large d'OID loid à partir de la base de données et l'écrit dans nomfichier. Notez que ceci est subtilement différent de la fonction serveur lo_export, qui agit avec les droits de l'utilisateur avec lequel est exécuté le serveur de base de données et sur le système de fichiers du serveur.
Utilisez \lo_list pour trouver l'OID de l'objet large.
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, dont vous devez vous rappeler si vous souhaitez accéder de nouveau à l'objet. Pour cette raison, il est recommandé de toujours associer un commentaire lisible par un humain avec chaque objet. Ils sont ensuite 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.
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.
Supprime l'objet large d'OID loid de la base de données.
Utilisez \lo_list pour trouver l'OID d'un objet large.
Sauvegarde les résultats des requête suivantes dans le fichier nomfichier ou envoie via un tube les résultats à venir dans un shell Unix séparé pour exécuter command. Si aucun argument n'est spécifié, l'affichage de la requête est redirigé vers 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 messages d'erreur.
Pour intégrer du texte entre les résultats de requête, utilisez \qecho.
Affiche le tampon de requête actuel sur la sortie standard.
Cette commande initialise les options affectant l'affichage des tables résultat de la requête. paramètre décrit l'option à initialiser. La sémantique de valeur en dépend.
Les options ajustables d'affichage sont :
Initialise le format d'affichage parmi unaligned, aligned, html, latex ou troff-ms. Les abréviations uniques sont autorisées. (ce qui signifie qu'une lettre est suffisante.)
« Unaligned » écrit toutes les colonnes d'une ligne sur une seule ligne séparées par le séparateur de champ actif. Ceci a pour but de créer un affichage lisible par d'autres programmes (séparé par des tabulations, séparé par des virgules). Le mode « Aligned » est l'affichage texte standard, lisible par un humain, proprement formaté. C'est aussi la valeur par défaut. Les modes « HTML » et « LaTeX » 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 dramatique en HTML mais en LaTeX vous devez avoir une structure de document complet.)
Le second argument 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 mode HTML, ceci sera traduit directement avec l'attribut border=.... Avec les autres, seules les valeurs 0 (sans bordure), 1 (lignes internes de division) et 2 (forme de table) ont un sens.
Bascule entre le format standard et étendu. Lorsque le format étendu est activé, les résultats de la requête sont affichés sur deux colonnes avec le nom de colonne sur la gauche et la donnée sur la droite. Ce mode est utile dans le cas où la donnée est trop grosse pour être contenue dans l'écran (mode « horizontal » habituel).
Le mode étendu est supporté par les quatre formats d'affichage.
Le second argument est une chaîne qui est affichée quand une colonne est NULL. La valeur par défaut est de ne rien afficher, ce qui peut être facilement pris pour, disons, une chaîne vide. Du coup, vous pouvez choisir d'écrire \pset NULL '(NULL)'.
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).
Bascule l'affichage du bas de page par défaut (x lignes).
Bascule l'affichage d'un caractère montrant la prise en compte de la locale pour séparer les groupes de chiffres à gauche de la marque des décimales. Il active aussi une marque décimale prenant en compte la locale.
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.
Bascule entre les lignes seules et l'affichage complet. Ce dernier peut afficher des informations supplémentaires telles que les en-têtes de colonnes, les titres et différents bas de page. Dans le mode lignes seules, seules les données réelles de la table sont affichées.
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 argument n'est donné, le titre n'est pas initialisé.
Vous permet de spécifier tout attribut à placer
à l'intérieur de la balise table en
HTML. Ceci
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.
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.
Lorsque le paginateur est désactivé, il n'est pas utilisé. Quand le paginateur est activé, il est utilisé seulement si nécessaire, c'est-à-dire si l'affichage se fait sur un terminal et qu'il ne tient pas sur l'écran. (psql ne fait pas un boulot parfait pour savoir quand utiliser le paginateur.) \pset pager active et désactive le paginateur. Ce dernier peut aussi être configuré à always, ce qui fait qu'il est utilisé en permanence.
Des exemples d'utilisation de ces différents formats sont disponibles dans la section Exemples.
Il existe plusieurs raccourcis de commandes pour \pset. Voir \a, \C, \H, \t, \T et \x.
C'est une erreur d'appeler \pset sans argument. Dans le futur, cet appel pourrait afficher le statut actuel de toutes les options d'affichage.
Quitte le programme psql.
Cette commande est identique à \echo sauf que les affichages sont écrits dans le canal d'affichage des requêtes, configuré par \o.
Réinitialise (efface) le tampon de requêtes.
Affiche ou sauvegarde l'historique des lignes de commandes dans nomfichier. Si nomfichier est omis, l'historique est écrit sur la sortie standard. Cette option est seulement disponible si psql est configuré pour utiliser la bibliothèque GNU Readline.
Initialise la variable interne nom à valeur ou, si plus d'une valeur est donnée, à la concaténation de toutes les valeurs. Si aucun second argument n'est donné, la variable est simplement initialisée sans valeur. Pour désinitialiser une variable, utilisez la commande \unset.
Les noms de variables valides peuvent contenir des caractères, 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.
Cette commande est totalement séparée de la commande SQL SET.
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.
Vous permet de spécifier les attributs à placer à
l'intérieur de la balise table dans le mode
d'affichage en tableau HTML. Cette commande est
équivalente à \pset tableattr
options_table.
Affiche le temps pris par chaque instruction SQL, en millisecondes, ou arrête cet affichage.
Place le tampon de requête en cours dans le fichier nomfichier ou l'envoie via un tube à la commande Unix commande.
Bascule le mode étendu de formatage en table. C'est équivalent à \pset expanded.
Produit une liste de toutes les tables, vues et séquences disponibles avec leur droit d'accès associé. Si un modèle est spécifié, seules les tables, vues et séquences dont le nom correspond au modèle sont listées.
Les commandes GRANT et SQL-REVOKE sont utilisées pour configurer les droits d'accès. Voir GRANT pour plus d'informations.
Ceci est un alias pour \dp (« affichage des droits »).
Lance un shell Unix séparé ou exécute la commande Unix commande. Les arguments ne sont pas interprétés, le shell les voit tel quel.
Affiche l'aide sur les commandes antislash.
Les différentes commandes \d acceptent un paramètre modèle pour spécifier le(s) nom(s) d'objet à afficher. * signifie « toute séquence de caractères » et ? signifie « tout caractère simple ». (Cette notation est comparable aux modèles du shell pour les noms de fichier Unix.) Les utilisateurs avancés peuvent aussi utiliser des notations d'expressions régulières telles que les classes de caractères, par exemple [0-9] pour correspondre à « tout chiffre ». Pour faire que tous ces caractères de correspondance de modèles soient interprétés de façon littérale, englobez-les dans des guillemets doubles.
Un modèle contenant un point (sans guillemet) est interprété comme un modèle de nom de schéma suivi par un modèle de nom d'objet. Par exemple, \dt foo*.bar* affiche toutes les tables dont le nom du schéma commence avec foo et dont le nom de table commence avec bar. Si aucun point n'apparaît, alors le modèle correspond seulement aux objets visibles dans le chemin actuel de recherche de schéma.
Lorsque modèle est complètement omis, les commandes \d affichent tous les objets visibles dans le chemin de recherche actuel du schéma. Pour voir tous les objets dans la base de données, utilisez le modèle *.*.
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. Pour initialiser des variables, utilisez la méta-commande psql \set :
testdb=> \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. Vous pouvez l'utiliser comme argument de toute commande slash :
testdb=> \echo :foo bar
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.
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.
Les noms de variables internes de psql peuvent être constitués de lettres, nombres et tirets bas dans n'importe quel ordre et autant de fois que vous le voulez. Un certain nombre de ces variables sont traitées spécialement par psql. Elles indiquent certaines options qui peuvent changer au moment de l'exécution en modifiant la valeur de la variable ou représentent un certain état de l'application. Bien que vous puissiez utiliser ces variables dans n'importe quel but, ce n'est pas recommandé car le comportement du programme pourrait devenir très rapidement vraiment étrange. Par convention, toutes les variables traitées spécialement sont uniquement composées de lettres majuscules (et peut-être aussi de chiffres et de tirets bas). Pour s'assurer d'un compatibilité maximum dans le futur, évitez l'utilisation de tels noms de variables pour vos propres besoins. Une liste de toutes les variables traitées spécialement suit.
Si actif (on, valeur par défaut), chaque commande SQL est automatiquement validée si elle se termine avec succès. Pour suspendre la validation dans ce mode, vous devez saisir une commande SQL BEGIN ou START TRANSACTION. Lorsqu'elle est désactivée (off) ou non initialisée, les commandes SQL ne sont plus validées tant que vous ne lancez pas explicitement COMMIT ou END. Le mode sans autocommit fonctionne en lançant implicitement un BEGIN, juste avant toute commande qui n'est pas déjà dans un bloc de transaction et qui n'est pas elle-même un BEGIN ou une autre commande de contrôle de transaction, ou une commande qui ne peut pas être exécutée à l'intérieur d'un bloc de transaction (comme VACUUM).
Dans le mode sans autocommit, vous devez annuler explicitement toute transaction échouée en saisissant ABORT ou ROLLBACK. Gardez aussi en tête que si vous sortez d'une session sans validation, votre travail est perdu.
Le mode auto-commit est le comportement traditionnel de PostgreSQL™ alors que le mode sans autocommit est plus proche des spécifications SQL. Si vous préférez sans autocommit, vous pouvez le configurer dans le fichier psqlrc global du système ou dans votre fichier ~/.psqlrc.
Le nom de la base de données à laquelle vous êtes