점(dot) 명령

점(dot) 명령 (Dot Commands)

점(dot) 명령은 DuckDB CLI 클라이언트에서 사용할 수 있는 특별한 명령이에요. 줄을 마침표(.)로 시작하고 그 뒤에 실행할 명령 이름을 붙이면 돼요. CLI를 다룰 때 빠질 수 없는 편의 기능이죠.

출처: 문서

본문

점(dot) 명령은 DuckDB CLI 클라이언트에서 사용할 수 있어요. 이 명령 중 하나를 쓰려면 그 줄을 마침표(.)로 시작하고, 그 직후에 실행할 명령의 이름을 붙이면 돼요. 명령에 추가 인자를 넣을 때는 공백으로 구분해서 명령 뒤에 입력해요. 인자에 공백이 포함되어야 한다면 그 파라미터를 작은따옴표나 큰따옴표로 감쌀 수 있어요. 점 명령은 한 줄에 입력해야 하고, 마침표 앞에는 공백이 있으면 안 돼요. 줄 끝에 세미콜론은 필요 없어요. 사용 가능한 명령을 보려면 .help 명령을 사용해요.

점 명령 목록 (List of Dot Commands)

명령	설명
`.bail ⟨on/off⟩`{:.language-sql .highlight}	에러를 만나면 중단. 기본값: `off`
`.binary ⟨on/off⟩`{:.language-sql .highlight}	바이너리 출력을 `on`/`off`로 설정. 기본값: `off`
`.cd ⟨DIRECTORY⟩`{:.language-sql .highlight}	작업 디렉토리를 `DIRECTORY`로 변경
`.changes ⟨on/off⟩`{:.language-sql .highlight}	SQL로 변경된 행 수 표시
`.columns`{:.language-sql .highlight}	쿼리 결과를 컬럼 단위로 렌더링
`.constant ⟨COLOR⟩`{:.language-sql .highlight}	상수 값에 사용할 구문 하이라이트 색상 설정
`.constantcode ⟨CODE⟩`{:.language-sql .highlight}	상수 값에 사용할 구문 하이라이트 터미널 코드 설정
`.databases`{:.language-sql .highlight}	연결된 데이터베이스의 이름과 파일 나열
`.dump ⟨TABLE⟩`{:.language-sql .highlight}	데이터베이스 내용을 SQL로 렌더링. `TABLE`은 덤프할 테이블의 `LIKE` 패턴
`.echo ⟨on/off⟩`{:.language-sql .highlight}	명령 에코를 `on`/`off`로 설정
`.exit ⟨CODE⟩`{:.language-sql .highlight}	반환 코드 `CODE`로 이 프로그램 종료
`.headers ⟨on/off⟩`{:.language-sql .highlight}	헤더 표시를 `on`/`off`로 설정. duckbox 모드에는 적용되지 않음
`.help ⟨-all⟩ ⟨PATTERN⟩`{:.language-sql .highlight}	`PATTERN`에 대한 도움말 텍스트 표시. `.help shortcuts`로 키보드 단축키 표시
`.highlight ⟨on/off⟩`{:.language-sql .highlight}	셸에서 구문 하이라이트를 `on`/`off`로 전환. 쿼리 구문 하이라이터 섹션 참조
`.highlight_colors ⟨COMPONENT⟩ ⟨COLOR⟩`{:.language-sql .highlight}	각 컴포넌트의 색상 구성(duckbox 전용). 결과 구문 하이라이터 섹션 참조
`.highlight_mode ⟨mixed/dark/light⟩`{:.language-sql .highlight}	하이라이트 모드 전환. 다크/라이트 모드 섹션 참조
`.highlight_results ⟨on/off⟩`{:.language-sql .highlight}	결과 테이블의 하이라이팅을 `on`/`off`로 전환(duckbox 전용). 결과 구문 하이라이터 섹션 참조
`.import ⟨FILE⟩ ⟨TABLE⟩`{:.language-sql .highlight}	`FILE`에서 `TABLE`로 데이터 가져오기. `--csv`, `--json`, `--parquet` 옵션 지원
`.indexes ⟨TABLE⟩`{:.language-sql .highlight}	인덱스 이름 표시
`.keyword ⟨COLOR⟩`{:.language-sql .highlight}	키워드에 사용할 구문 하이라이트 색상 설정
`.keywordcode ⟨CODE⟩`{:.language-sql .highlight}	키워드에 사용할 구문 하이라이트 터미널 코드 설정
`.large_number_rendering ⟨all/footer/off⟩`{:.language-sql .highlight}	큰 수의 읽기 쉬운 렌더링 전환(duckbox 전용, 기본값: `footer`)
`.last`{:.language-sql .highlight}	마지막 결과를 잘림 없이 렌더링. 페이저(pager)로 탐색할 때 유용
`.log ⟨FILE/off⟩`{:.language-sql .highlight}	로깅을 `on`/`off`로 설정. `FILE`은 `stderr`/`stdout` 가능
`.maxrows ⟨COUNT⟩`{:.language-sql .highlight}	표시할 최대 행 수 설정. duckbox 모드 전용
`.maxwidth ⟨COUNT⟩`{:.language-sql .highlight}	최대 문자 폭 설정. 0은 터미널 폭 기본값. duckbox 모드 전용
`.mode ⟨MODE⟩ ⟨TABLE⟩`{:.language-sql .highlight}	출력 모드 설정
`.multiline`{:.language-sql .highlight}	멀티라인 모드 설정(기본)
`.nullvalue ⟨STRING⟩`{:.language-sql .highlight}	`NULL` 값 대신 `STRING` 사용. 기본값: `NULL`
`.once ⟨OPTIONS⟩ ⟨FILE⟩`{:.language-sql .highlight}	다음 SQL 명령의 출력만 `FILE`로
`.open ⟨OPTIONS⟩ ⟨FILE⟩`{:.language-sql .highlight}	기존 데이터베이스 닫고 `FILE` 다시 열기. 옵션: `--new`, `--nofollow`, `--readonly`, `--sql`
`.output ⟨FILE⟩`{:.language-sql .highlight}	출력을 `FILE`로 보내거나, `FILE` 생략 시 `stdout`으로
`.pager ⟨OPTIONS⟩`{:.language-sql .highlight}	출력에 대한 페이저 사용 제어. 페이징 섹션 참조
`.print ⟨STRING...⟩`{:.language-sql .highlight}	리터럴 `STRING` 출력
`.progress_bar ⟨COMPONENT⟩` {:.language-sql .highlight}	진행률 표시줄 컴포넌트 스타일 설정
`.prompt ⟨OPTIONS⟩ ⟨CONTINUE⟩`{:.language-sql .highlight}	표준 프롬프트 교체
`.quit`{:.language-sql .highlight}	이 프로그램 종료
`.read ⟨FILE⟩`{:.language-sql .highlight}	`FILE`에서 입력 읽기
`.rows`{:.language-sql .highlight}	쿼리 결과를 행 단위로 렌더링(기본)
`.safe_mode`{:.language-sql .highlight}	안전 모드 활성화
`.schema ⟨PATTERN⟩`{:.language-sql .highlight}	`PATTERN`과 일치하는 `CREATE` 문 표시
`.separator ⟨COL⟩ ⟨ROW⟩`{:.language-sql .highlight}	컬럼/행 구분자 변경
`.shell ⟨CMD⟩ ⟨ARGS...⟩`{:.language-sql .highlight}	시스템 셸에서 `ARGS...`와 함께 `CMD` 실행
`.show`{:.language-sql .highlight}	다양한 설정의 현재 값 표시
`.singleline`{:.language-sql .highlight}	싱글라인 모드 설정
`.startup_text ⟨none/version/all⟩`{:.language-sql .highlight}	CLI 실행 시 표시되는 시작 텍스트 제어. `~/.duckdbrc`의 첫 줄로 설정
`.system ⟨CMD⟩ ⟨ARGS...⟩`{:.language-sql .highlight}	시스템 셸에서 `ARGS...`와 함께 `CMD` 실행
`.tables ⟨TABLE⟩`{:.language-sql .highlight}	`LIKE` 패턴 `TABLE`에 일치하는 테이블을 컬럼명·타입·행 수와 함께 데이터베이스·스키마별로 그룹 지어 나열
`.timer ⟨on/off⟩`{:.language-sql .highlight}	SQL 타이머를 `on`/`off`로 설정. `;`로 구분되지만 줄바꿈으로 구분되지 않는 SQL 문은 함께 측정
`.width ⟨NUM1⟩ ⟨NUM2⟩ ...`{:.language-sql .highlight}	컬럼형 출력의 최소 컬럼 폭 설정

`.help` 명령 사용하기 (Using the `.help` Command)

.help 텍스트는 첫 번째 인자로 텍스트 문자열을 넘기면 필터링할 수 있어요.

.help m

.maxrows COUNT           Sets the maximum number of rows for display (default: 40). Only for duckbox mode.
.maxwidth COUNT          Sets the maximum width in characters. 0 defaults to terminal width. Only for duckbox mode.
.mode MODE ?TABLE?       Set output mode

`.output`: 결과를 파일로 쓰기 (Writing Results to a File)

기본적으로 DuckDB CLI는 결과를 터미널의 표준 출력으로 보내요. 하지만 .output이나 .once 명령으로 이를 바꿀 수 있어요. 원하는 출력 파일 위치를 파라미터로 넘기면 돼요. .once 명령은 다음 한 번의 결과만 출력하고 표준 출력으로 되돌아가지만, .output은 이후의 모든 출력을 그 파일 위치로 리다이렉트해요. 각 결과는 그 위치의 전체 파일을 덮어쓴다는 점을 기억하세요. 표준 출력으로 되돌아가려면 파일 파라미터 없이 .output을 입력하면 돼요.

이 예시에서는 출력 형식을 markdown으로 바꾸고 대상을 Markdown 파일로 지정한 뒤, DuckDB가 그 SQL 문의 출력을 그 파일로 씁니다. 그다음 파라미터 없이 .output을 써서 표준 출력으로 되돌아가요.

.mode markdown
.output my_results.md
SELECT 'taking flight' AS output_column;
.output
SELECT 'back to the terminal' AS displayed_column;

그러면 my_results.md 파일에는 다음이 들어 있어요:

| output_column |
| ------------- |
| taking flight |

터미널에는 다음이 표시돼요:

| displayed_column     |
| -------------------- |
| back to the terminal |

흔한 출력 형식은 CSV(콤마로 구분된 값)예요. DuckDB는 데이터를 CSV나 Parquet으로 내보내는 SQL 문법을 지원하지만, 원한다면 CLI 전용 명령으로 CSV를 쓸 수도 있어요.

.mode csv
.once my_output_file.csv
SELECT 1 AS col_1, 2 AS col_2
UNION ALL
SELECT 10 AS col1, 20 AS col_2;

그러면 my_output_file.csv 파일에는 다음이 들어 있어요:

col_1,col_2
1,2
10,20

.once 명령에 특별 옵션(플래그)을 넘기면 쿼리 결과를 임시 파일로 보내고 사용자의 기본 프로그램에서 자동으로 열 수 있어요. 텍스트 파일에는 -e 플래그(기본 텍스트 편집기에서 열림), CSV 파일에는 -x 플래그(기본 스프레드시트 편집기에서 열림)를 사용해요. 이는 특히 비교적 큰 결과 집합이 있을 때 쿼리 결과를 더 자세히 검사하는 데 유용해요. .excel 명령은 .once -x와 동일해요.

.once -e
SELECT 'quack' AS hello;

그러면 결과가 시스템의 기본 텍스트 파일 편집기에서 열려요. 예를 들면:

팁 (Tip) macOS 사용자는 .once로 파이프를 통해 pbcopy에 출력하면(.once |pbcopy) 결과를 클립보드에 복사할 수 있어요: .once |pbcopy

이를 .headers off와 .mode lines 옵션과 함께 쓰면 특히 효과적이에요.

데이터베이스 스키마 쿼리하기 (Querying the Database Schema)

모든 DuckDB 클라이언트는 SQL로 데이터베이스 스키마를 쿼리하는 것을 지원해요. 하지만 CLI에는 데이터베이스 내용을 이해하기 쉽게 해주는 추가 점 명령이 있어요. .tables 명령은 데이터베이스의 테이블 목록을 반환해요. LIKE 패턴에 따라 결과를 필터링하는 선택적 인자가 있어요.

CREATE TABLE swimmers AS SELECT 'duck' AS animal;
CREATE TABLE fliers AS SELECT 'duck' AS animal;
CREATE TABLE walkers AS SELECT 'duck' AS animal;
.tables

fliers    swimmers  walkers

예를 들어 l을 포함하는 테이블만 필터링하려면 LIKE 패턴 %l%을 사용해요.

.tables %l%

fliers   walkers

.schema 명령은 데이터베이스의 스키마를 정의하는 데 사용된 모든 SQL 문을 보여줘요.

.schema

CREATE TABLE fliers (animal VARCHAR);
CREATE TABLE swimmers (animal VARCHAR);
CREATE TABLE walkers (animal VARCHAR);

데이터베이스 내용을 SQL로 덤프하기 (Dumping Database Content as SQL)

.dump 명령은 데이터베이스 내용을 스키마 정의와 데이터를 포함한 SQL 문으로 렌더링해요. 백업을 만들거나 데이터를 마이그레이션할 때 유용해요.

.dump

선택적 TABLE 인자는 LIKE 패턴으로 출력을 필터링해요. 추가 인자로 여러 패턴을 제공할 수 있어요.

.dump %swim%

--newlines 옵션은 출력에 이스케이프되지 않은 줄바꿈 문자를 허용해요:

.dump --newlines

진행률 표시줄 (Progress Bar)

DuckDB CLI 클라이언트의 진행률 표시줄은 컴포넌트를 통해 커스터마이징을 지원해요.

.progress_bar 명령은 컴포넌트 추가/제거를 위한 --add와 --clear 파라미터를 지원해요.

구체적인 사용법은 아래 예시를 참고해요.

진행률 표시줄 표시 구성하기 (Configuring the Progress Bar Display)

진행률 표시줄이 활성화되어 있는지 확인하려면:

SELECT * FROM duckdb_settings() WHERE name = 'enable_progress_bar';

쿼리가 진행률 표시줄을 표시하기 전에 걸리는 최소 시간(밀리초)을 확인하려면:

SELECT * FROM duckdb_settings() WHERE name = 'progress_bar_time';

진행률 표시줄이 표시되는 최소 시간을 100밀리초로 설정하려면:

SET progress_bar_time = 100;

진행률 표시줄 컴포넌트를 진행률 표시줄에 현재 시간을 표시하는 빨간 텍스트로 설정하려면:

.progress_bar --add "{align:right}{min_size:20}{color:red}Time: {sql:select (current_time::varchar).split('.')[1]}{color:reset} "

DuckDB progress bar with current time stamp

.progress_bar --add 명령은 누적적이에요. 여러 --add 호출을 하면 진행률 표시줄에 추가 컴포넌트가 쌓여요.

진행률 표시줄 컴포넌트를 진행률 표시줄에 파일 캐시 RAM 사용량을 표시하는 파란 텍스트로 설정하려면:

.progress_bar --add "{align:right}{min_size:20}{color:blue}External Cache Usage: {sql:select format_bytes(memory_usage_bytes) from duckdb_memory() where tag='EXTERNAL_FILE_CACHE'}{color:reset};

DuckDB progress bar with cache usage

모든 기존 진행률 표시줄 컴포넌트를 초기화하려면:

.progress_bar --clear

구문 하이라이터 (Syntax Highlighters)

DuckDB CLI 클라이언트에는 SQL 쿼리용 구문 하이라이터와 duckbox 형식 결과 테이블용 하이라이터가 있어요.

쿼리 구문 하이라이터 구성하기 (Configuring the Query Syntax Highlighter)

기본적으로 셸은 구문 하이라이팅을 지원해요. CLI의 구문 하이라이터는 다음 명령으로 구성할 수 있어요.

하이라이터를 끄려면:

.highlight off

하이라이터를 켜려면:

.highlight on

상수 하이라이팅에 사용할 색상을 구성하려면:

.constant [red|green|yellow|blue|magenta|cyan|white|brightblack|brightred|brightgreen|brightyellow|brightblue|brightmagenta|brightcyan|brightwhite]

.constantcode ⟨terminal_code⟩

예를 들어:

.constantcode 033[31m

키워드 하이라이팅에 사용할 색상을 구성하려면:

.keyword [red|green|yellow|blue|magenta|cyan|white|brightblack|brightred|brightgreen|brightyellow|brightblue|brightmagenta|brightcyan|brightwhite]

.keywordcode ⟨terminal_code⟩

예를 들어:

.keywordcode 033[31m

결과 구문 하이라이터 구성하기 (Configuring the Result Syntax Highlighter)

기본적으로 결과 하이라이팅은 몇 가지 작은 수정을 수행해요:

컬럼 이름을 굵게.
NULL 값을 회색 처리.
레이아웃 요소를 회색 처리.

각 컴포넌트의 하이라이팅은 .highlight_colors 명령으로 커스터마이징할 수 있어요. 예를 들어:

.highlight_colors layout red
.highlight_colors column_type yellow
.highlight_colors column_name yellow bold_underline
.highlight_colors numeric_value cyan underline
.highlight_colors temporal_value red bold
.highlight_colors string_value green bold
.highlight_colors footer gray

결과 하이라이팅은 .highlight_results off로 비활성화할 수 있어요.

단축 표기 (Shorthands)

DuckDB CLI는 점 명령의 단축 표기를 허용해요. 문자 시퀀스가 점 명령이나 인자로 모호함 없이 완성될 수 있으면, CLI가 (조용히) 자동 완성해요. 예를 들어:

.mo ma

는 다음과 동일해요:

.mode markdown

팁 (Tip) 가독성을 높이고 스크립트가 미래에도 대비되도록 SQL 스크립트에서는 단축 표기 사용을 피하는 게 좋아요.

데이터 가져오기 (Importing Data)

.import 명령은 파일에서 DuckDB 테이블로 데이터를 가져와요. DuckDB의 리더 함수(read_csv, read_json, read_parquet)를 사용하고 자동 스키마 감지를 지원해요. 대상 테이블이 없으면 자동으로 생성돼요.

파일 형식은 --csv, --json, --parquet로 명시적으로 지정할 수 있어요. 형식을 지정하지 않으면 파일 확장자에서 형식을 추론해요.

.import data.csv my_table

추가 파라미터는 --⟨parameter⟩ ⟨value⟩{:.language-sql .highlight} 문법으로 기본 리더 함수에 전달할 수 있어요:

.import data.csv my_table --delimiter "|" --header false

JSON 파일을 가져오려면:

.import data.json my_table --json

Parquet 파일을 가져오려면:

.import data.parquet my_table

더 알아보기 (Learn more)

출력 형식 — 모드·페이징·duckbox 렌더링.
Safe mode — 안전 모드 활성화.