명령줄 클라이언트

명령줄 클라이언트 (Command Line Client)

DuckDB CLI(Command Line Interface)는 의존성이 없는 단일 실행 파일이에요. Windows, Mac, Linux용으로 안정 버전과 GitHub Actions가 만든 야간 빌드 모두가 사전 컴파일되어 제공된답니다. 함께 살펴볼까요?

출처: 문서

본문

설치: DuckDB CLI 클라이언트를 사용하려면 [CLI 설치 페이지]({% link install/index.html %}?environment=cli)를 방문하세요.

DuckDB 명령줄 클라이언트의 최신 안정 버전은 {{ site.current_duckdb_version }}이에요.

설치 (Installation)

DuckDB CLI (Command Line Interface)는 의존성이 없는 단일 실행 파일이에요. 안정 버전과 GitHub Actions가 만든 야간 빌드 모두 Windows, Mac, Linux용으로 사전 컴파일되어 있어요. 다운로드 링크는 [설치 페이지]({% link install/index.html %})의 CLI 탭을 참고하세요.

DuckDB CLI는 SQLite 명령줄 셸을 기반으로 하므로, CLI-클라이언트 특화 기능은 SQLite 문서에 설명된 것과 유사해요 (단, DuckDB의 SQL 구문은 [몇 가지 예외]({% link docs/current/sql/dialect/postgresql_compatibility.md %})로 PostgreSQL 관례를 따르지만).

DuckDB에는 CLI 클라이언트의 가장 흔한 용도를 요약한 tldr 페이지가 있어요. tldr이 설치되어 있다면 tldr duckdb를 실행해서 표시할 수 있어요.

시작하기 (Getting Started)

CLI 실행 파일을 다운로드한 뒤 압축을 풀고 아무 디렉토리에 저장하세요. 터미널에서 그 디렉토리로 이동해 duckdb 명령을 입력해서 실행 파일을 실행하세요. PowerShell이나 POSIX 셸 환경이라면 대신 ./duckdb 명령을 사용하세요.

사용법 (Usage)

duckdb 명령의 일반적인 사용법은 다음과 같아요:

duckdb ⟨OPTIONS⟩ ⟨FILENAME⟩

옵션 (Options)

⟨OPTIONS⟩{:.language-sql .highlight} 부분은 [CLI 클라이언트용 인자]({% link docs/current/clients/cli/arguments.md %})를 인코딩해요. 흔한 옵션은:

• -csv: 출력 모드를 CSV로 설정
• -json: 출력 모드를 JSON으로 설정
• -readonly: 읽기 전용 모드로 데이터베이스 열기 ([DuckDB의 동시성]({% link docs/current/connect/concurrency.md %}#handling-concurrency) 참고)

전체 옵션 목록은 [command line arguments 페이지]({% link docs/current/clients/cli/arguments.md %})를 참고하세요.

인메모리 vs. 영속 데이터베이스 (In-Memory vs. Persistent Database)

⟨FILENAME⟩{:.language-sql .highlight} 인자가 제공되지 않으면 DuckDB CLI는 임시 [인메모리 데이터베이스]({% link docs/current/connect/overview.md %}#in-memory-database)를 열어요. DuckDB의 버전 번호, 연결 정보, D로 시작하는 프롬프트가 보일 거예요.

duckdb

DuckDB v{{ site.current_duckdb_version }} ({{ site.current_duckdb_codename }}) {{ site.current_duckdb_hash }}
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
D

[영속 데이터베이스]({% link docs/current/connect/overview.md %}#persistent-database)를 열거나 만들려면 단순히 경로를 명령줄 인자로 포함하세요:

duckdb my_database.duckdb

CLI에서 SQL 문장 실행 (Running SQL Statements in the CLI)

CLI가 열리면 SQL 문장을 입력하고 세미콜론을 붙인 뒤 엔터를 누르면 실행돼요. 결과는 터미널의 테이블에 표시돼요. 세미콜론을 생략하면 엔터로 여러 줄 SQL 문장을 입력할 수 있어요.

SELECT 'quack' AS my_column;

my_column
quack

CLI는 SELECT, CREATE, ALTER 문장을 포함한 DuckDB의 풍부한 [SQL 구문]({% link docs/current/sql/introduction.md %}) 전체를 지원해요.

편집기 기능 (Editor Features)

CLI는 [자동 완성]({% link docs/current/clients/cli/autocomplete.md %})을 지원하고, macOS, Linux, Windows에서 정교한 [편집기 기능]({% link docs/current/clients/cli/editing.md %})과 [구문 강조]({% link docs/current/clients/cli/syntax_highlighting.md %})를 갖고 있어요.

CLI 종료 (Exiting the CLI)

CLI를 종료하려면 플랫폼이 지원하면 Ctrl+D를 누르세요. 그렇지 않으면 Ctrl+C를 누르거나 .exit 명령을 사용하세요. 영속 데이터베이스를 사용했다면 DuckDB가 자동으로 체크포인트(최신 편집을 디스크에 저장)하고 닫아요. 이렇게 하면 .wal 파일(write-ahead log)이 제거되고 모든 데이터가 단일 파일 데이터베이스로 통합돼요.

Dot 명령 (Dot Commands)

SQL 구문 외에도 특별한 [dot 명령]({% link docs/current/clients/cli/dot_commands.md %})을 CLI 클라이언트에 입력할 수 있어요. 이 명령 중 하나를 사용하려면 줄을 마침표(.)로 시작하고 바로 뒤에 실행하려는 명령 이름을 입력하세요. 명령의 추가 인자는 명령 뒤에 공백으로 구분해 입력해요. 인자에 공백이 포함되어야 한다면 단일 또는 이중 따옴표로 그 파라미터를 감쌀 수 있어요. Dot 명령은 한 줄에 입력해야 하고, 마침표 앞에 공백이 있어서는 안 돼요. 줄 끝에 세미콜론은 필요 없어요.

자주 사용되는 구성은 ~/.duckdbrc 파일에 저장할 수 있으며, CLI 클라이언트가 시작될 때 로드돼요. 이 옵션에 대한 자세한 내용은 아래 Configuring the CLI 섹션을 참고하세요.

팁 DuckDB CLI 클라이언트가 ~/.duckdbrc 파일을 읽지 못하게 하려면 다음과 같이 시작하세요:

duckdb -init /dev/null

아래에서 몇 가지 중요한 dot 명령을 요약해요. 사용 가능한 모든 명령을 보려면 [dot commands 페이지]({% link docs/current/clients/cli/dot_commands.md %})를 참고하거나 .help 명령을 사용하세요.

데이터베이스 파일 열기 (Opening Database Files)

CLI를 열 때 데이터베이스에 연결하는 것 외에도 .open 명령으로 새 데이터베이스 연결을 만들 수 있어요. 추가 파라미터가 제공되지 않으면 새 인메모리 데이터베이스 연결이 생성돼요. 이 데이터베이스는 CLI 연결이 닫힐 때 저장되지 않아요.

.open

.open 명령은 선택적으로 여러 옵션을 받지만, 마지막 파라미터는 영속 데이터베이스의 경로(또는 생성되어야 하는 위치)를 나타내는 데 사용할 수 있어요. 특별 문자열 :memory:는 임시 인메모리 데이터베이스를 여는 데도 사용할 수 있어요.

.open persistent.duckdb

경고 .open은 현재 데이터베이스를 닫아요. 새 데이터베이스를 추가하면서 현재 데이터베이스를 유지하려면 [ATTACH 문]({% link docs/current/sql/statements/attach.md %})을 사용하세요.

.open이 받는 중요한 옵션 중 하나는 --readonly 플래그예요. 이것은 데이터베이스 편집을 허용하지 않아요. 읽기 전용 모드로 열려면 데이터베이스가 이미 존재해야 해요. 이는 또한 인메모리 데이터베이스는 연결 시 만들어지기 때문에 읽기 전용 모드로 새 인메모리 데이터베이스를 열 수 없다는 뜻이에요.

.open --readonly preexisting.duckdb

--sql 옵션은 SQL 표현식으로 데이터베이스 경로를 설정할 수 있게 해줘요:

.open --sql "getenv('MY_DB_PATH')"

출력 형식 (Output Formats)

.mode [dot 명령]({% link docs/current/clients/cli/dot_commands.md %}#mode)을 사용해 터미널 출력에서 반환되는 테이블의 모양을 바꿀 수 있어요. 여기에는 기본 duckbox 모드, 다른 도구가 받아들이는 csv와 json 모드, 문서용 markdown과 latex, SQL 문장 생성을 위한 insert 모드가 포함돼요.

결과를 파일로 쓰기 (Writing Results to a File)

기본적으로 DuckDB CLI는 결과를 터미널의 표준 출력으로 보내요. 그러나 이것은 .output 또는 .once 명령으로 수정할 수 있어요. 자세한 내용은 [output dot command]({% link docs/current/clients/cli/dot_commands.md %}#output-writing-results-to-a-file) 문서를 참고하세요.

파일에서 SQL 읽기 (Reading SQL from a File)

DuckDB CLI는 .read 명령을 사용해 터미널 대신 외부 파일에서 SQL 명령과 dot 명령을 모두 읽을 수 있어요. 이를 통해 여러 명령을 순서대로 실행할 수 있고, 명령 시퀀스를 저장하고 재사용할 수 있어요.

.read 명령은 실행할 SQL 및/또는 명령을 포함한 파일의 경로라는 하나의 인자만 필요해요. 파일의 명령을 실행한 후 제어는 터미널로 돌아가요. 그 파일 실행의 출력은 앞서 논의한 것과 동일한 .output과 .once 명령으로 제어돼요. 이를 통해 아래 첫 예시처럼 출력을 터미널로 다시 표시하거나, 두 번째 예시처럼 다른 파일로 내보낼 수 있어요.

이 예시에서 select_example.sql 파일은 duckdb.exe와 같은 디렉토리에 있고 다음 SQL 문장을 포함해요:

SELECT *
FROM generate_series(5);

CLI에서 실행하려면 .read 명령을 사용해요.

.read select_example.sql

아래 출력은 기본적으로 터미널로 반환돼요. 테이블의 형식은 .output이나 .once 명령으로 조정할 수 있어요.

| generate_series |
|----------------:|
| 0               |
| 1               |
| 2               |
| 3               |
| 4               |
| 5               |

SQL과 dot 명령을 포함한 여러 명령도 단일 .read 명령으로 실행할 수 있어요. 이 예시에서 write_markdown_to_file.sql 파일은 duckdb.exe와 같은 디렉토리에 있고 다음 명령을 포함해요:

.mode markdown
.output series.md
SELECT *
FROM generate_series(5);

CLI에서 실행하려면 이전과 같이 .read 명령을 사용해요.

.read write_markdown_to_file.sql

이 경우 어떤 출력도 터미널로 반환되지 않아요. 대신 series.md 파일이 (이미 존재하면 대체되어) 여기에 표시된 markdown 형식의 결과로 생성돼요:

| generate_series |
|----------------:|
| 0               |
| 1               |
| 2               |
| 3               |
| 4               |
| 5               |

CLI 구성 (Configuring the CLI)

CLI를 구성하는 데 여러 dot 명령을 사용할 수 있어요. 시작 시 CLI는 ~/.duckdbrc 파일의 모든 명령(dot 명령과 SQL 문장 포함)을 읽고 실행해요. 이를 통해 CLI의 구성 상태를 저장할 수 있어요. -init 플래그로 다른 초기화 파일을 가리킬 수도 있어요.

커스텀 프롬프트 설정 (Setting a Custom Prompt)

예를 들어, DuckDB CLI와 같은 디렉토리에 있는 prompt.sql이라는 파일이 DuckDB 프롬프트를 오리 머리로 바꾸고 SQL 문장을 실행할 거예요. 오리 머리는 Unicode 문자로 만들어져서 모든 터미널 환경에서 동작하지는 않아요 (예: WSL과 Windows Terminal을 사용하지 않는 Windows에서는 안 됨).

.prompt "{color:yellow1}{sql:select current_database()} ⚫◗ "

또는 색상이 없는 더 단순한 버전:

.prompt "{sql:select current_database()} ⚫◗ "

초기화 시 그 파일을 호출하려면 이 명령을 사용하세요:

duckdb -init prompt.sql

이것은 다음을 출력해요:

-- Loading resources from prompt.sql
v⟨version⟩ ⟨git_hash⟩
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
⚫◗

비대화형 사용법 (Non-Interactive Usage)

파일을 읽고/처리하고 즉시 종료하려면 파일 내용을 duckdb로 리다이렉트하세요:

duckdb < select_example.sql

명령줄에서 SQL 텍스트를 직접 전달해 명령을 실행하려면 duckdb를 두 개의 인자(데이터베이스 위치 또는 :memory:, 그리고 실행할 SQL 문장 문자열)로 호출하세요.

duckdb :memory: "SELECT 42 AS the_answer"

확장 로드 (Loading Extensions)

확장을 로드하려면 다른 SQL 문장처럼 DuckDB의 SQL INSTALL과 LOAD 명령을 사용하세요.

INSTALL fts;
LOAD fts;

자세한 내용은 [Extension 문서]({% link docs/current/extensions/overview.md %})를 참고하세요.

stdin에서 읽고 stdout에 쓰기 (Reading from stdin and Writing to stdout)

Unix 환경에서는 여러 명령 사이에 데이터를 파이프하는 것이 유용할 수 있어요. DuckDB는 SQL 명령 안에서 stdin(/dev/stdin)과 stdout(/dev/stdout)의 파일 위치를 사용해 stdin에서 데이터를 읽고 stdout에 쓸 수 있는데, 파이프가 파일 핸들과 매우 유사하게 동작하기 때문이에요.

이 명령은 예시 CSV를 만들어요:

COPY (SELECT 42 AS woot UNION ALL SELECT 43 AS woot) TO 'test.csv' (HEADER);

먼저, 파일을 읽어 duckdb CLI 실행 파일로 파이프하세요. DuckDB CLI의 인자로는 열 데이터베이스의 위치(이 경우 인메모리 데이터베이스)와 /dev/stdin을 파일 위치로 활용하는 SQL 명령을 전달하세요.

cat test.csv | duckdb -c "SELECT * FROM read_csv('/dev/stdin')"

woot
42
43

stdout에 다시 쓰려면 /dev/stdout 파일 위치와 함께 copy 명령을 사용할 수 있어요.

cat test.csv | \
    duckdb -c "COPY (SELECT * FROM read_csv('/dev/stdin')) TO '/dev/stdout' WITH (FORMAT csv, HEADER)"

woot
42
43

환경 변수 읽기 (Reading Environment Variables)

getenv 함수는 환경 변수를 읽을 수 있어요.

예시 (Examples)

HOME 환경 변수에서 홈 디렉토리의 경로를 얻으려면:

SELECT getenv('HOME') AS home;

home
/Users/user_name

getenv 함수의 출력을 [구성 옵션]({% link docs/current/configuration/overview.md %})을 설정하는 데 사용할 수 있어요. 예를 들어 환경 변수 DEFAULT_NULL_ORDER에 따라 NULL 순서를 설정하려면:

SET default_null_order = getenv('DEFAULT_NULL_ORDER');

환경 변수 읽기의 제한 (Restrictions for Reading Environment Variables)

getenv 함수는 [enable_external_access]({% link docs/current/configuration/overview.md %}#configuration-reference) 옵션이 true(기본 설정)일 때만 실행할 수 있어요. CLI 클라이언트에서만 사용할 수 있고 다른 DuckDB 클라이언트에서는 지원되지 않아요.

준비된 문장 (Prepared Statements)

DuckDB CLI는 일반 SELECT 문장 외에도 [준비된 문장]({% link docs/current/sql/query_syntax/prepared_statements.md %}) 실행을 지원해요. CLI 클라이언트에서 준비된 문장을 만들고 실행하려면 PREPARE 절과 EXECUTE 문장을 사용하세요.

쿼리 완료 ETA (Query Completion ETA)

DuckDB의 CLI는 이제 실행 중인 쿼리에 대한 지능적인 완료 예상 시간을 제공하고, 완료 시 총 실행 시간을 표시해요.

DuckDB CLI에서 쿼리를 실행할 때 진행률 막대는 완료까지 남은 예상 시간을 표시해요. 이 기능은 단순한 선형 외삽보다 더 정확한 예측을 제공하기 위해 고급 통계 모델링(Kalman filtering)을 사용해요.

동작 방식 (How It Works)

DuckDB는 다음 과정으로 완료 예상 시간을 계산해요:

1. 진행률 모니터링: DuckDB의 내부 진행률 API가 실행 중인 쿼리의 예상 완료 비율을 보고해요
2. 통계 필터링: Kalman filter가 잡음 있는 진행률 측정을 평활화하고 실행 변동성을 고려해요
3. 지속적 개선: 시스템은 새 진행률 데이터가 생길 때마다 예상 완료 시간을 지속적으로 업데이트해서 실행 내내 정확도를 높여요

Kalman filter는 메모리 압박, I/O 병목, 네트워크 지연 같은 변화하는 실행 조건에 적응해요. 이 적응적 접근 방식은 예상 완료 시간이 항상 선형적으로 줄어들지 않을 수 있다는 것을 의미해요—쿼리 실행이 덜 예측 가능해지면 예측이 증가할 수도 있어요.

쿼리 완료 ETA 정확도에 영향을 주는 요소 (Factors Affecting The Accuracy of Query Completion ETA)

다음 조건에서 완료 시간 예측이 덜 신뢰할 수 있을 수 있어요:

시스템 리소스 제약:

• 디스크 스와핑을 일으키는 메모리 압박
• 경쟁 프로세스의 높은 CPU 부하
• 디스크 I/O 병목

쿼리 실행 특성:

• 가변 실행 단계 (초기 설정 대비 주요 처리)
• 일관되지 않은 레이턴시를 가진 네트워크 의존 연산
• 예측할 수 없는 분기 로직을 가진 쿼리
• 원격 데이터 소스에 대한 연산
• 외부 함수 호출
• 매우 편향된 데이터 분포

더 알아보기 (Learn more)