psql

Guide de l'utilisateur PostgreSQL
Prev		Next

Entrées

psql accepte un grand nombre d'arguments en ligne de commane, un riche ensemble de meta-commandes, et la totalité du langage SQL supporté par Postgres. Les arguments en ligne de commande les plus courants sont :

dbname: Le nom d'une base existante a accéder. dbname a par défaut la valeur de la variable d'environnement USER ou, si elle n'est pas placée, le nom du compte Unix de l'utilisateur.
-c query: Une requête unique a lancer. psql will exit on completion.

L'ensemble complet des arguments en ligne de commande et les meta-commandes sont décrits dans la section suivante.

Il existe certaines variables d'environnement qui peuvent être utilisées à la place des arguments en ligne de commande. De plus, la bibliothèque du client Postgres utilisée par l'application psql recherche d'autres variables d'environnement optionnelles à configurer, par exemple, le style de représentation date/time et la zone horaire locale. Voir le chapitre sur libpq dans le Programmer's Guide pour plus de détails.

Vous pouvez placer certaines des variables d'environnement suivantes pour éviter de spécifier les options en ligne de commande :

PGHOST: Le nom d'hôte DNS du serveur. Le placement de PGHOST comme chaîne de longueur non-zero fait que la communication TCP/IP sera utilisée, d'avantage que le default local Unix domain sockets.
PGPORT: Le numéro de port sur lequel un serveur Postgres est en écoute. Par défaut 5432.
PGTTY: La cible pour l'affichage des messages de la bibliothèque client. Pas nécessaire.
PGOPTION: Si PGOPTION est spécifié, les options qu'il contient sont analysées avant les options en ligne de commande.
PGREALM: PGREALM s'applique seulement si une authentification Kerberos est utilisée. Si cette variable d'environnement est placée, Postgres tentera l'authentification avec les serveurs de ce domaine et utilisera des separate ticket files pour éviter les conflits avec local ticket files. Voir le PostgreSQL Administrator's Guide pour plus d'information sur Kerberos.

Description

psql est un client en mode texte de Postgres. Il vous permet de taper des requêtes interactives, envoyées à Postgres et de voir les résultats de ces requêtes.

psql est une application cliente Postgres. Désormais, un processus postmaster doit être lancé sur le serveur hôte avant que psql soit exécuté. De plus, les paramètres corrects pour identifier le serveur, comme le nom d'hôte du postmaster doivent être spécifié, comme décrit ci-dessus.

Quand psql démarre, il lit les commandes depuis /etc/psqlrc et depuis $(HOME)/.psqlrc. Ceci permet que les commandes SQL comme SET puissent être utilisée pour que le style date soit lancé au démarrage de chaque session.

Connection à une base

psql tente de se connecter à la base sur le nom d'hôte et le port spécifiés sur le ligne de commande. Si la connection ne peut pas être faite pour diverses raisons (ex. droits insuffisants, postmaster non lancé sur le serveur, etc.) psql renverra une erreur disant
Connection to database failed.
La raison pour laquelle la connection a échoué n'est pas donnée.

Entrée de requêtes

Dans les opérations normales, psql présente un prompt avec le nom de la base sur laquelle psql est connecté, suivi de la chaîne "=>". Par exemple,
$ psql testdb Welcome to the POSTGRESQL interactive sql monitor: Please read the file COPYRIGHT for copyright terms of POSTGRESQL [PostgreSQL 6.5.0 on i686-pc-linux-gnu, compiled by gcc 2.7.2.3] type \? for help on slash commands type \q to quit type \g or terminate with semicolon to execute query You are currently connected to the database: testdb testdb=>

Au prompt, l'utilisateur peut taper des requêtes SQL. À moins que l'option -S soit placée, les lignes entrées sont envoyées au serveur lorsqu'elles sont terminées par un point-virgule (";").

A chaque exécution d'une requête psql recherche également si des événements de notification asynchrones générés par LISTEN et NOTIFY ont été détectés.

psql peut être utilisé dans une séquence pipe, et détecte automatiquement quand il n'est pas en train d'écouter ou de dialoguer avec un real tty.

Pagination de l'écran

	Auteur
	Brett McCormick sur la mailing list le 04-04-1998.

Pour modifier le comportement de la pagination de vos sorties psql, placez ou enlevez votre variable d'environnement PAGER. Et, bien sûr, vous devez le faire avant de démarrer le programme.

En csh/tcsh ou d'autres shells C :
% unsetenv PAGER
tandis qu'en sh/bash ou d'autres Bourne shells :
% unset PAGER

Options de la ligne de commande

psql comprend les options de ligne de commande suivantes :

-A: Désactive la justification de paragraphe quand il renvoie des éléments d'une table.
-c query: Spécifie que psql exécute une chaîne de requête, query, et s'arrête. C'est pratique pour les scripts shell, typiquement en conjonction avec l'option -q dans les scripts shells.
-d dbname: Spécifie le nom d'une base à laquelle se connecter. C'est équivalent à spécifier dbname comme dernier champ de la ligne de commande.
-e: Répète la requête envoyée au serveur.
-E: Répète la requête générée par \d et les autres commandes \.
-f filename: Utilise le fichier filename comme la source des requêtes au lieu de lire les requêtes interactivement. Ce fichier doit être spécifié et visible par le client.
-F separator: Utilise separator comme champ séparateur. Par défaut c'est une barre verticale ASCII ("|").
-h hostname: Spécifie le nom d'hôte de la machine sur laquelle le postmaster tourne. Sans cette option, la communication est établie en utilisant local Unix domain sockets.
-H: Active les sorties table en HTML 3.0.
-l: Liste toutes les tables disponibles et quitte. Les autres options non-connection sont ignorées.
-n: N'utilise pas la readline library pour l'édition des entrées ligne et l'historique des commandes.
-o filename: Place toutes les sorties dans un fichier filename. The path must be writable by the client.
-p port: Spécifie le port TCP/IP ou, si omission, the local Unix domain socket file extension sur lequel le postmaster est en attente de connections. Par défaut c'est la valeur de la variable d'environnement PGPORT si elle est placée, ou 5432.
-q: Spécifie que psql travaillera silencieusement. Par défaut il envoie des messages de bienvenue et de sortie et le prompt pour chaque requête, et imprime le nombre de lignes renvoyées par une requête. Si cette option st utilisée, rien n'apparaîtra. C'est très pratique avec l'option -c.
-s: Lance le mode étape par étape où il questionne l'utilisateur avant d'envoyer au serveur.
-S: Lance le mode ligne unique où chaque requête est terminée par un saut de ligne, au lieu d'un point-virgule.
-t: Désactive l'impression des noms de colonnes.. C'est très pratique avec l'option -c dans les scripts shells.
-T table_options: Vous permet de spécifier des options à placer dans les balises table ... pour les sorties HTML 3.0. Par exemple, border vous donnera des tables avec des marges. Doit être utilisé avec l'option -H.
-u: Demande à l'utilisateur son nom et son mot de passe avant de le connecter à la base. Si la base ne nécessite pas d'authentification par mot de passe, ils sont ignorés. Si l'option n'est pas utilisée (et la variable d'environnement PGPASSWORD pas placée) et que la base nécessite une authentification par mot de passe, la connection échouera. Le nom d'utilisateur est ignoré de toutes façons.
-x: Active le mode format de ligne étendue. Quand il est activé chaque ligne aura ses noms de colonnes imprimé sur la gauche et les valeurs de colonnes imprimées sur la droite. C'est très pratique pour les lignes qui sont trop longues pour tenir sur une seule ligne à l'écran. Les sorties lignes en HTML supportent aussi ce mode.

Vous pouvez placer les variables d'environnement pour éviter de taper certaines des options ci-dessus. Voir la section sur les variables d'environnement.

Meta-commandes psql

Quoique vous entriez dans psql ça commence par un backslash qui est une meta-commande psql. Tout le reste est du SQL et vient dans le tampon de requête courant (et une fois que vous avez au moins une requête complète, elle sera automatiquement soumise au serveur). Les meta-commandes psql sont aussi appelées commandes-slash.

Le format d'une commande psql est le backslash ("\"), immédiatement suivi des lettres et chaque autre par des nombres ou des espaces blancs..

With single caracters command verb, vous n'avez, actuellement, pas besoin de séparer la commande verb de l'argument avec un espace blanc, pour des raisons historiques.

Les meta-commandes suivantes sont définies :

\a

Toggle field alignment when printing out table elements.

\C caption

Set the HTML3.0 table caption to "caption".

\connect meter"ceable> [ username ]

Établit une connection à une nouvelle base, utilisant par défaut username s'il n'est pas spécifié. La connection précédente est fermée.

\copy meter"ceable> { FROM | TO } filename

Exécute une copie. Cette opération lance une commande SQL COPY, mais au lieu que le serveur lise ou écrive le fichier spécifié, et par conséquent nécessite un accès serveur et un privilège utilisateur spécial, psql lit ou écrit le fichier et envoie les données vers ou depuis le serveur. Le délimiteur par défaut tab est utilisé.

Cette opération n'est pas aussi efficace que la commande SQL COPY parce que toutes les données doivent passer à travers la connection client/serveur IP ou socket. Pour de grosses quantités de données cette autre technique sera préférable.

\d [ table ]

Liste les tables d'une base, ou si table est spécifié, liste les colonnes de cette table. Si le nom de table est spécifié comme astérisque ("*"), liste l'information de toutes les tables et colonnes de chaque table.

\da

Liste tous les agrégats disponibles.

\dd object

Liste la description depuis pg_description d'un objet spécifié, qui peut être une table, colonne, type, opérateur, ou agrégat.

Tous les objets n'ont pas de description dans pg_description. Cette meta-commande peut être pratique pour obtenir une rapide description des fonctionnalités natives de Postgres.

\df

Liste les fonctions.

\di

Liste seulement les index.

\do

Liste seulement les opérateurs.

\ds

Liste seulement les séquences.

\dS

Liste les tables système et les index.

\dt

Liste seulement les tables non système.

\dT

Liste les types.

\e [ filename ]

Édite le tampon de requête courant ou le contenu du fichier filename.

\E [ filename ]

Édite le tampon de requête courant ou le contenu du fichier filename et l'exécute sur la sortie éditeur.

\f [ separator ]

Place le séparateur de champ. Par défaut un simple espace blanc..

\g [ { filename | |command } ]

Envoie le tampon entrée de la requête courante et optionnellement enregistre la sortie dans un fichier filename ou pipe la sortie dans un shell Unix séparé pour exécuter command.

\h [ command ]

Fournit une aide sur la syntaxe de la commande SQL spécifiée. Si command n'est pas une commande SQL définie (ou n'est pas documentée dans psql), ou si command n'est pas spécifiée, alors psql listera toutes les commandes pour lesquelles l'aide sur la syntaxe est disponible. Si command est un astérisque ("*"), donne l'aide sur la syntaxe de toutes les commandes SQL.

\H

Bascule les sorties en HTML3. Équivalent à l'option -H en ligne de commande.

\i filename

Lit les requêtes depuis un fichier filename dans l'entrée du tampon de requête.

\l

Liste toutes les bases sur le serveur.

\m

Toggle the old monitor-like table display, which includes border characters surrounding the table. C'est la sortie standard SQL. Par défaut, psql inclut seulement les séparateurs de champ entre les colonnes.

\o [ { filename | |command } ]

Enregistre les résultats de la future requête dans le fichier filename ou pipe les résultats futurs dans un shell Unix séparé pour exécuter command. Si aucun argument n'est spécifié, envoie les résultats de la requête vers stdout.

\p

Imprime le tampon de requête courant.

\q

Quitte le programme psql.

\r

Réinitialise (clear) le tampon de requête.

\s [ filename ]

Imprime ou enregistre l'historique de la ligne de commande vers filename. Si filename est omis, n'enregistre pas les commandes dans un fichier historique. Cette option est disponible seulement si psql est configuré pour utiliser readline.

\t

Toggle display of output column name headings and row count footer (defaults to on).

\T table_options

Permet de spécifier des options à placer dans les balises table ... pour les sorties HTML 3.0 Par exemple, border vous donne des tables avec des marges. Doit être utilisé avec la meta-commande \H.

\x

Bascule en format de ligne étendue. Quand cette option est activée chaque ligne a ses noms de colonnes imprimés sur la gauche et les valeurs imprimées sur la droite. C'est très pratique pour les lignes qui sont trop longues pour tenir sur une seule ligne d'écran. Le mode sortie HTML le supporte aussi.

\w filename

Envoi du tampon de requête courant vers filename.

\z

Produit une liste de toutes les tables de la base avec leurs ACL appropriés (permissions grant/revoke).

\! [ command ]

Escape vers un shell Unix séparé, ou exécute le commande command.

\?

Fournit l'aide sur les commandes slash ("\").