Herramienta de línea de comandos psql

psql es la interfaz de línea de comandos de PostgreSQL. En esta página se describen los psqlcomandos que admite la interfaz de PostgreSQL para Spanner. Para saber cómo conectarte con psql, consulta Conectar psql a una base de datos con dialecto PostgreSQL.

Metacomandos

La interfaz de PostgreSQL admite las siguientes categorías de metacomandos psql:

  • General
  • Ayuda
  • Búfer de consulta
  • Entrada/Salida
  • Condicional
  • Informativa (solo algunos comandos \d)
  • Formato
  • Sistema operativo
  • Variables

No se admiten las siguientes categorías:

  • Conexión
  • Objetos grandes

Se admiten los siguientes comandos informativos:

Comando Descripción
\d Mostrar tablas (excepto las del sistema)
\d table Mostrar columnas de una tabla
\dt Mostrar las tablas de todos los esquemas (detalles)
\dt table Tabla de lista (detallada)
\dn Ver esquemas

Instrucciones de gestión de sesiones

psql se comunica con Spanner a través de PGAdapter, que usa el motor principal del controlador JDBC de Spanner. El controlador admite las instrucciones de gestión de sesiones descritas en Instrucciones de gestión de sesiones. Por lo tanto, puede usar estas instrucciones con psql.

Agrupación por lotes de instrucciones SQL

psql y PGAdapter admiten lotes de instrucciones SQL. Para agrupar las declaraciones, usa la opción psql -c. Esta opción permite enviar una o varias instrucciones de SQL o de gestión de sesiones, separadas por punto y coma (;), como una única solicitud de ejecución. Un lote puede incluir cualquier instrucción admitida y puede combinar DDL, DML y DQL.

Un lote de varias instrucciones se ejecuta en un solo bloque de transacciones implícito. Los bloques de transacciones implícitas se cierran automáticamente al final del lote. Si se produce algún error en un bloque de transacción implícita, se revierte toda la transacción.

Se admiten los controles de transacciones BEGIN y COMMIT explícitos, pero un bloque de transacciones explícito no puede contener instrucciones DDL.

Ejemplos

DML

En el siguiente ejemplo se muestra cómo enviar un lote de instrucciones 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');"

En el siguiente ejemplo se muestra cómo ejecutar las instrucciones SQL del archivo insert_contacts.sql.

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

DDL

En este ejemplo se envía un lote de ALTER TABLE instrucciones.

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;"

Comando COPY para importar datos

Usa el comando COPY FROM STDIN para importar datos de un archivo de texto o CSV a una base de datos con dialecto PostgreSQL. Aunque solo se admite STDIN, puedes importar datos usando COPY canalizando archivos en psql.

Hay dos formas de ejecutar el comando COPY:

  • Atómico COPY

    Los datos se copian en una sola transacción. Este es el valor predeterminado. Se aplican los límites de transacción estándar de Spanner a la transacción. Esto significa que se pueden incluir como máximo 80.000 mutaciones o 100 MB de datos en una operación COPY.

  • No atómico COPY

    COPY divide automáticamente los datos en varias transacciones si el archivo contiene más de 80.000 mutaciones o más de 100 MB.

    Si se produce un error durante la COPY y se cancela la operación, es posible que algunas filas ya se hayan conservado en la base de datos. No se realiza ninguna reversión. Las transacciones se ejecutan en paralelo, por lo que es posible que los datos posteriores a la fila del archivo de importación que ha provocado el error se importen a la base de datos antes de que se detenga la operación COPY.

Habilitar COPY no atómico

Para habilitar COPY no atómico, envía el siguiente comando antes de ejecutar la operación de copia.

SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'

Sintaxis

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}

La tabla ya debe existir. Si no se especifica ninguna lista de columnas, se copian todas las columnas de la tabla.

El valor predeterminado de FORMAT es text.

delimiter_character debe ser un carácter de un byte. El valor predeterminado es el carácter de tabulación para el formato de texto y una coma para el formato CSV.

NULL especifica la cadena que representa un valor nulo. El valor predeterminado es \N (barra invertida + N) en formato de texto y una cadena vacía sin comillas en formato CSV. Puede que prefieras una cadena vacía incluso en formato de texto en los casos en los que no quieras distinguir los valores nulos de las cadenas vacías.

QUOTE especifica el carácter de comillas que se debe usar cuando se cita un valor de datos. El valor predeterminado es comillas dobles. Debe ser un solo carácter de un byte. Esta opción solo se permite cuando se usa el formato CSV.

ESCAPE especifica el carácter que debe aparecer antes de un carácter de datos que coincida con el valor de QUOTE. El valor predeterminado es el mismo que el valor de QUOTE (de modo que el carácter de comillas se duplica si aparece en los datos). Debe ser un solo carácter de un byte. Esta opción solo se permite cuando se usa el formato CSV.

HEADER indica si el primer registro del archivo de entrada es un encabezado (contiene nombres de columna). El valor predeterminado es TRUE.

Ejemplos

En este ejemplo, se importan datos del archivo con formato de texto llamado mydata.txt a la tabla mytable. PGAdapter debe estar en ejecución. Para obtener más información, consulta Iniciar PGAdapter.

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

En este ejemplo, mydata.csv está en formato CSV y su primera fila es un encabezado con nombres de columna separados por comas.

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

En el siguiente ejemplo se muestra cómo iniciar una operación COPY no atómica.

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

Solución de problemas

A continuación, se indican algunos errores habituales.

Sintaxis de entrada no válida

Se produce el siguiente error:

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

Este error puede producirse cuando el archivo de entrada tiene una fila de encabezado con nombres de columna y no se ha especificado la opción HEADER.

Datos de COPY no válidos

Se produce el siguiente error:

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

Este error se produce cuando una fila del archivo de entrada no incluye un valor (o un valor nulo) para cada columna de la tabla. Una de las causas podría ser que el archivo CSV esté mal formado o que no coincida el delimitador especificado (o el delimitador predeterminado) con el delimitador real del archivo.

Siguientes pasos