Outil de ligne de commande psql

psql est l'interface de ligne de commande de PostgreSQL. Cette page décrit les commandes psql compatibles avec l'interface PostgreSQL pour Spanner. Pour savoir comment vous connecter à psql, consultez Connecter psql à une base de données en dialecte PostgreSQL.

Commandes Meta

L'interface PostgreSQL accepte les catégories de métacommandes psql suivantes:

  • Général
  • Aide
  • Tampon de requête
  • Input/Output
  • Conditionnel
  • À titre informatif (certaines commandes \d uniquement)
  • Mise en forme
  • Système d'exploitation
  • Variables

Les catégories suivantes ne sont pas acceptées:

  • Connexion
  • Objets volumineux

Les commandes informatives suivantes sont acceptées:

Commande Description
\d Répertorier les tables (à l'exclusion des tables système)
\d table Répertorier les colonnes d'une table
\dt Répertorier les tables de tous les schémas (en détail)
\dt table Répertorier les tables (en détail)
\dn Lister les schémas

Instructions de gestion de session

psql communique avec Spanner via PGAdapter, qui utilise le moteur principal du pilote JDBC Spanner. Le pilote est compatible avec les instructions de gestion de session décrites dans la section Instructions de gestion de session. Vous pouvez donc utiliser ces instructions avec psql.

Traitement par lot des instructions SQL

psql et PGAdapter acceptent les lots SQL multi-instructions. Pour regrouper des instructions, vous devez utiliser l'option psql -c. Cette option permet de transmettre une ou plusieurs instructions SQL ou de gestion de session, séparées par des points-virgules (;), en tant que requête d'exécution unique. Un lot peut inclure n'importe quelle instruction compatible et peut mélanger des instructions LDD, LMD et DQL.

Un lot multi-instruction est exécuté dans un seul bloc de transaction implicite. Les blocs de transactions implicites sont automatiquement fermés à la fin du lot. Si des erreurs se produisent dans un bloc de transaction implicite, l'intégralité de la transaction est annulée.

Les commandes de transaction BEGIN et COMMIT explicites sont acceptées, mais un bloc de transaction explicite ne peut pas contenir d'instructions DDL.

Examples

LMD

L'exemple suivant montre comment envoyer un lot d'instructions INSERT.

psql -h localhost -p 5432 -c "INSERT INTO users (id, age, firstname) VALUES (1, 25, 'Alex'); \
 INSERT INTO users (id, age, firstname) VALUES (2, 31, 'Dana'); \
 INSERT INTO users (id, age, firstname) VALUES (3, 54, 'Izumi');"

L'exemple suivant montre comment exécuter les instructions SQL du fichier insert_contacts.sql.

psql -h localhost -c "$(cat contacts_insert.sql)"

LDD

Cet exemple envoie un lot d'instructions ALTER TABLE.

psql -h localhost -p 5432 test-db -c "ALTER TABLE users ADD col1 integer; \
 ALTER TABLE users ADD col2 text; ALTER TABLE users ADD col3 float8;"

Commande COPY pour importer des données

Utilisez la commande COPY FROM STDIN pour importer des données à partir d'un fichier texte ou CSV dans une base de données en dialecte PostgreSQL. Bien que seule l'entrée standard STDIN soit prise en charge, vous pouvez importer à l'aide de COPY en transmettant des fichiers dans psql.

Il existe deux façons d'exécuter la commande COPY:

  • COPY atomique

    Les données sont copiées en une seule transaction. Il s'agit de la valeur par défaut. Les limites de transaction standards de Spanner s'appliquent à la transaction. Cela signifie qu'au maximum 80 000 mutations ou 100 Mo de données peuvent être inclus dans une seule opération COPY.

  • COPY non atomique

    COPY répartit automatiquement les données sur plusieurs transactions si le fichier contient plus de 80 000 mutations ou plus de 100 Mo.

    Si une erreur se produit pendant l'exécution de COPY et que l'opération est interrompue, certaines lignes peuvent déjà être conservées dans la base de données. Aucun rollback n'est effectué. Les transactions sont exécutées en parallèle. Par conséquent, les données situées après la ligne du fichier d'importation à l'origine de l'erreur peuvent être importées dans la base de données avant l'arrêt de l'opération COPY.

Activer COPY non atomique

Pour activer COPY non atomique, envoyez la commande suivante avant d'exécuter l'opération de copie.

SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'

Syntaxe

COPY table_name [ ( column_name [, ...] ) ]
    FROM STDIN
    [ [ WITH ] ( option [, ...] ) ]

where option is one of:

    FORMAT format_name
    DELIMITER 'delimiter_character'
    NULL 'null_string'
    QUOTE 'quote_character'
    ESCAPE 'escape_character'
    HEADER [boolean]

and format_name is:
    {text|csv}

and delimiter_character is:
    [!-~] except ' " \

and null_string is:
    {a—z|A—Z|0—9|_}+

and quote_character is:
    [!-~] except ' " \

and escape_character is:
    [!-~] except ' " \

and boolean is:
    {TRUE|ON|1|FALSE|OFF|0}

Le tableau doit déjà exister. Si aucune liste de colonnes n'est spécifiée, toutes les colonnes du tableau sont copiées.

La valeur par défaut de FORMAT est text.

caractère_délimiteur doit être un caractère de 1 octet. Par défaut, le délimiteur est la tabulation pour le format texte et une virgule pour le format CSV.

NULL spécifie la chaîne représentant une valeur nulle. La valeur par défaut est \N (backslash+N) au format texte et une chaîne vide sans guillemets au format CSV. Vous pouvez préférer une chaîne vide, même au format texte, lorsque vous ne souhaitez pas distinguer les valeurs nulles des chaînes vides.

QUOTE spécifie le guillemet à utiliser lorsqu'une valeur de données est mise entre guillemets. La valeur par défaut est le guillemet double. Il doit s'agir d'un seul caractère d'un octet. Cette option n'est autorisée que lorsque vous utilisez le format CSV.

ESCAPE spécifie le caractère à afficher avant un caractère de données correspondant à la valeur QUOTE. La valeur par défaut est identique à celle de QUOTE (de sorte que le caractère de guillemet soit doublé s'il apparaît dans les données). Il doit s'agir d'un seul caractère d'un octet. Cette option n'est autorisée que lorsque vous utilisez le format CSV.

HEADER indique si le premier enregistrement du fichier d'entrée est un en-tête (contient les noms des colonnes). La valeur par défaut est "TRUE".

Examples

Cet exemple importe les données du fichier au format texte nommé mydata.txt dans la table mytable. PGAdapter doit être en cours d'exécution. Pour en savoir plus, consultez la section Démarrer PGAdapter.

cat mydata.txt | psql -h localhost -c "COPY mytable FROM STDIN;"

Dans cet exemple, mydata.csv est au format CSV et sa première ligne est un en-tête avec des noms de colonnes séparés par une virgule.

cat mydata.csv | psql -h localhost \
  -c "COPY mytable FROM STDIN WITH (FORMAT csv, ESCAPE '~', HEADER TRUE);"

L'exemple suivant montre comment démarrer une opération COPY non atomique.

cat mydata.txt | psql -h localhost \ 
  -c "SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'" -c "COPY mytable FROM STDIN;"

Dépannage

Voici quelques erreurs courantes.

Syntaxe d'entrée non valide

L'erreur suivante se produit :

Invalid input syntax for type <type>:"<table_name>"

Cette erreur peut se produire lorsque le fichier d'entrée comporte une ligne d'en-tête avec des noms de colonnes et que l'option HEADER n'a pas été spécifiée.

Données COPY non valides

L'erreur suivante se produit :

Invalid COPY data: Row length mismatched. Expected <number> columns, but only found <number>

Cette erreur se produit lorsqu'une ligne du fichier d'entrée n'inclut pas de valeur (ou de valeur nulle) pour chaque colonne du tableau. Cela peut être dû à un fichier CSV mal formé ou à une incompatibilité entre l'option de séparateur spécifiée (ou séparateur par défaut) et le séparateur réel du fichier.

Étape suivante