PostgreSQL : console (client psql)

Le client psql est la console de PostgreSQL. Les exemples utilisent la base boutique et le rôle app.

Se connecter

sudo -u postgres psql                         # administrateur local (compte système postgres)
psql -h 127.0.0.1 -U app -d boutique          # par TCP, mot de passe demandé
psql -h serveur.exemple.com -p 5432 -U app boutique
psql "postgresql://app@serveur.exemple.com:5432/boutique?sslmode=require"   # URI de connexion

Options : -h hôte, -p port, -U utilisateur, -d base (ou dernier argument), -W force la demande du mot de passe.

Méta-commandes

Les méta-commandes commencent par \ et ne se terminent pas par ;. Les instructions SQL se terminent par ;.

Commande	Rôle
`\l`	Liste les bases
`\c boutique`	Se connecte à une autre base
`\dt`	Liste les tables (`\dt+` : avec tailles)
`\d clients`	Structure d’une table (`\d+` : détaillée)
`\dn`	Liste les schémas
`\du`	Liste les rôles
`\dx`	Extensions installées
`\di`, `\dv`, `\ds`	Index, vues, séquences
`\df`	Fonctions
`\dp clients`	Droits sur une table
`\conninfo`	Informations sur la connexion en cours
`\x`	Bascule l’affichage vertical (étendu)
`\timing`	Affiche la durée de chaque requête
`\e`	Édite la requête dans l’éditeur (`$EDITOR`)
`\i fichier.sql`	Exécute un fichier SQL
`\o fichier`	Écrit les résultats dans un fichier (`\o` seul : retour à l’écran)
`\g`	Exécute la dernière requête (comme `;`)
`\password`	Change son mot de passe sans l’afficher
`\?`	Aide des méta-commandes
`\h CREATE TABLE`	Aide sur une instruction SQL
`\q` ou `Ctrl+d`	Quitte

Exécuter du SQL sans ouvrir la console

psql -h 127.0.0.1 -U app -d boutique -c "SELECT COUNT(*) FROM clients;"
psql -h 127.0.0.1 -U app -d boutique -f script.sql
psql -h 127.0.0.1 -U app -d boutique -1 -f migration.sql        # dans une seule transaction
sudo -u postgres psql -c "\l"                                   # méta-commande avec -c

-1 exécute le fichier dans une transaction unique : si une instruction échoue, tout est annulé. Ajouter -v ON_ERROR_STOP=1 pour s’arrêter à la première erreur.

Format de sortie

psql -d boutique -At -c "SELECT nom FROM clients"                # -A sans alignement, -t sans en-tête : pour un script
psql -d boutique --csv -c "SELECT * FROM clients" > clients.csv   # CSV
psql -d boutique -c "SELECT * FROM clients" -x                    # affichage vertical
psql -d boutique -P format=html -c "SELECT * FROM clients"        # HTML

Dans la console : \pset format aligned|csv|html|unaligned|wrapped, \pset null '(vide)', \pset border 2.

Éviter de saisir le mot de passe : `~/.pgpass`

echo "127.0.0.1:5432:boutique:app:<mot-de-passe>" >> ~/.pgpass
chmod 600 ~/.pgpass

Format : hôte:port:base:utilisateur:mot-de-passe (* accepté comme joker). PostgreSQL ignore le fichier si ses droits sont plus larges que 600.

Variables et personnalisation

-- ~/.psqlrc : exécuté à chaque ouverture de psql
\set QUIET 1
\pset null '(null)'
\timing on
\set HISTSIZE 5000
\set COMP_KEYWORD_CASE upper
\x auto
\set QUIET 0

\x auto : bascule en affichage vertical quand le résultat est trop large.
Variables : \set ville 'Lyon' puis SELECT * FROM clients WHERE ville = :'ville';.

Dépannage

Symptôme	Piste
`Peer authentication failed`	Connexion par socket : ajouter `-h 127.0.0.1` ou utiliser le compte système
`password authentication failed`	Mauvais mot de passe, ou ligne `pg_hba.conf` inadaptée
`database "boutique" does not exist`	Vérifier avec `\l`
`psql: error: connection refused`	Cluster arrêté (`pg_lsclusters`) ou mauvais port
Accents illisibles	`SHOW client_encoding;` et terminal en UTF-8

Pour aller plus loin

Manuel : psql