psql 명령줄 도구

psql은 PostreSQL의 명령줄 프런트엔드입니다. 이 페이지에서는 Spanner용 PostgreSQL 인터페이스에서 지원하는 psql 명령어를 설명합니다. psql로 연결하는 방법은 PostgreSQL 언어 데이터베이스에 psql 연결을 참조하세요.

메타 명령어

PostgreSQL 인터페이스에서는 다음과 같은 psql 메타 명령어 카테고리를 지원합니다.

참고: 각 카테고리 아래에 있는 명령어를 보려면 \? 명령어를 입력합니다.

• 일반
• 도움말
• 쿼리 버퍼
• 입력/출력
• 조건부
• 정보 제공(일부 \d 명령어에만 해당)
• 서식 지정
• 운영체제
• 변수

다음과 같은 카테고리는 지원되지 않습니다.

• 연결
• 대형 객체

다음과 같은 정보 제공 명령어가 지원됩니다.

명령어	설명
\d	테이블 나열(시스템 테이블 제외)
\d table	테이블 열 나열
\dt	모든 스키마의 테이블 나열(세부정보)
\dt table	테이블 나열(세부정보)
\dn	스키마 나열

세션 관리 문

psql은 Spanner JDBC 드라이버의 코어 엔진을 사용하는 PGAdapter를 통해 Spanner와 통신합니다. 이 드라이버에서는 세션 관리 문에 설명된 세션 관리 문을 지원합니다. 따라서 이러한 문을 psql에서 사용할 수 있습니다.

SQL 문 일괄 처리

psql 및 PGAdapter에서는 멀티 문 SQL 배치를 지원합니다. 문을 일괄 처리하려면 psql -c 옵션을 사용합니다. 이 옵션을 사용하면 SQL 또는 세션 관리 문 하나 이상이 세미콜론(;)으로 구분되어 단일 실행 요청으로 전달될 수 있습니다. 배치에는 지원되는 모든 문이 포함될 수 있으며 DDL, DML, DQL이 혼합될 수 있습니다.

멀티 문 배치는 암시적 단일 트랜잭션 블록 내에서 실행됩니다. 암시적 트랜잭션 블록은 배치 끝에서 자동으로 닫힙니다. 암시적 트랜잭션 블록 내부에서 오류가 발생하면 전체 트랜잭션이 롤백됩니다.

명시적 BEGIN 및 COMMIT 트랜잭션 제어가 지원되지만 명시적 트랜잭션 블록에는 DDL 문이 포함될 수 없습니다.

예시

DML

다음 예시에서는 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');"

그 다음 예시에서는 insert_contacts.sql 파일에서 SQL 문을 실행하는 방법을 보여줍니다.

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

DDL

이 예시에서는 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;"

데이터 가져오기를 위한 COPY 명령어

COPY FROM STDIN 명령어를 사용하여 텍스트 또는 CSV 파일의 데이터를 PostgreSQL 언어 데이터베이스로 가져옵니다. STDIN만 지원되지만 파일을 psql로 파이핑하면 COPY를 사용하여 가져올 수 있습니다.

COPY 명령어를 실행하는 방법은 두 가지가 있습니다.

• 원자적 COPY

  데이터가 단일 트랜잭션으로 복사됩니다. 전역 window는 기본 설정이며, Spanner의 표준 트랜잭션 제한이 트랜잭션에 적용됩니다. 즉, COPY 작업 하나에 변형 최대 80,000개나 데이터 100MB가 포함될 수 있습니다.

• 비원자적 COPY

  파일에 변형이 80,000개 넘게 있거나 100MB를 초과하는 경우 COPY는 자동으로 데이터를 트랜잭션 여러 개로 분할합니다.

  COPY 중 오류가 발생하여 작업이 취소되면 일부 행이 아직 데이터베이스에 유지되어 있을 수 있습니다. 롤백이 발생하지 않습니다. 트랜잭션은 병렬로 실행되므로 COPY 작업이 중단되기 전에 오류를 유발한 가져오기 파일의 행 이후 데이터를 데이터베이스로 가져올 수 있습니다.

비원자적 COPY 사용 설정

비원자적 COPY를 사용 설정하려면 복사 작업을 실행하기 전에 다음 명령어를 제출합니다.

SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'

구문

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}

테이블이 이미 있어야 합니다. 열 목록을 지정하지 않으면 테이블의 모든 열이 복사됩니다.

FORMAT 기본값은 text입니다.

delimiter_character는 1바이트 문자여야 합니다. 기본값은 텍스트 형식의 탭 문자와 CSV 형식의 쉼표입니다.

NULL에서 null 값을 나타내는 문자열을 지정합니다. 기본값은 텍스트 형식의 \N(백슬래시+N)이며 CSV 형식의 따옴표가 없는 빈 문자열입니다. null을 빈 문자열과 구분하지 않으려는 경우 텍스트 형식에서도 빈 문자열을 사용하는 것이 좋습니다.

QUOTE는 데이터 값을 따옴표로 묶을 때 사용할 따옴표 문자를 지정합니다. 기본값은 큰따옴표입니다. 단일 1바이트 문자여야 합니다. 이 옵션은 CSV 형식을 사용하는 경우에만 허용됩니다.

ESCAPE는 QUOTE 값과 일치하는 데이터 문자 앞에 표시되는 문자를 지정합니다. 기본값은 QUOTE 값과 동일합니다. 따라서 따옴표 문자가 데이터에 나타나는 경우 두 배가 됩니다. 단일 1바이트 문자여야 합니다. 이 옵션은 CSV 형식을 사용하는 경우에만 허용됩니다.

HEADER는 입력 파일의 첫 번째 레코드가 헤더인지(열 이름 포함)를 나타냅니다. 기본값은 TRUE입니다.

예시

이 예시에서는 데이터를 mydata.txt라는 텍스트 형식의 파일에서 mytable 테이블로 가져옵니다. PGAdapter가 실행 중이어야 합니다. 자세한 내용은 PGAdapter 시작을 참조하세요.

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

다음 예시에서 mydata.csv는 CSV 형식이며 첫 번째 행은 쉼표로 구분된 열 이름이 있는 헤더입니다.

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

다음 예시에서는 비원자적 COPY 작업을 시작하는 방법을 보여줍니다.

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

문제 해결

다음은 몇 가지 일반적인 오류입니다.

잘못된 입력 구문

다음 오류가 발생합니다.

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

이 오류는 입력 파일에 열 이름이 있는 헤더 행이 있고 HEADER 옵션이 지정되지 않은 경우에 발생할 수 있습니다.

잘못된 복사 데이터

다음 오류가 발생합니다.

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

이 오류는 입력 파일의 행에 테이블의 모든 열에 대한 값(또는 null)이 포함되지 않은 경우에 발생합니다. 한 가지 원인은 잘못된 CSV 파일이거나 지정된 구분 기호 옵션(또는 기본 구분 기호)과 파일의 실제 구분 기호 간의 불일치일 수 있습니다.

다음 단계

• psql로 PostgreSQL 언어 데이터베이스에 연결하는 방법 알아보기
• PGAdapter 알아보기