UI 익스텐션

UI 익스텐션 (UI Extension)

ui 익스텐션은 로컬 DuckDB 인스턴스에 사용자 인터페이스를 더해 주는 기능이에요. 브라우저에서 바로 쿼리를 돌려 볼 수 있어서 편리해요. UI는 MotherDuck이 만들고 유지 관리해요. 기능 개요는 MotherDuck 문서에서 볼 수 있어요.

출처: 문서

본문

사용법 (Usage)

커맨드라인에서 UI를 시작하려면:

duckdb -ui

SQL에서 UI를 시작하려면:

CALL start_ui();

둘 중 하나를 실행하면 기본 브라우저에서 UI가 열려요.

UI는 시작된 DuckDB 인스턴스에 연결되므로, 이미 로드한 데이터를 모두 사용할 수 있어요. 이 인스턴스는 네이티브 프로세스(Wasm이 아님)이므로 로컬 환경의 모든 리소스(모든 코어, 메모리, 파일)를 활용할 수 있어요. 이 인스턴스를 닫으면 UI도 동작을 멈춰요.

UI는 DuckDB에 내장된 HTTP 서버에서 서빙돼요. 브라우저를 띄우지 않고 이 서버만 시작하려면:

CALL start_ui_server();

그런 다음 브라우저에서 http://localhost:4213으로 접속하면 UI를 볼 수 있어요.

HTTP 서버를 멈추려면:

CALL stop_ui_server();

로컬 쿼리 실행 (Local Query Execution)

기본적으로 DuckDB UI는 쿼리를 완전히 로컬에서 실행해요. 쿼리와 데이터가 컴퓨터 밖으로 나가지 않아요. UI를 통해 MotherDuck을 쓰고 싶다면 명시적으로 옵트인하고 MotherDuck에 로그인해야 해요.

설정 (Configuration)

로컬 포트 (Local Port)

HTTP 서버의 로컬 포트는 다음과 같은 SQL 명령으로 설정할 수 있어요:

SET ui_local_port = 4213;

환경 변수 ui_local_port도 사용할 수 있어요.

기본 포트는 4213이에요. (왜냐하면? 4 = D, 21 = U, 3 = C)

원격 URL (Remote URL)

로컬 HTTP 서버는 UI의 파일을 원격 HTTP 서버에서 가져와서 최신 상태로 유지해요.

원격 서버의 기본 URL은 https://ui.duckdb.org예요.

대체 원격 URL은 다음과 같은 SQL 명령으로 설정할 수 있어요:

SET ui_remote_url = 'https://ui.duckdb.org';

환경 변수 ui_remote_port도 사용할 수 있어요.

이 설정은 주로 테스트 목적이에요.

애플리케이션이 DuckDB에 로드한 데이터에 접근할 수 있으므로, 설정하는 URL은 반드시 신뢰할 수 있는지 확인해요.

이 위험 때문에, 이 설정은 allow_unsigned_extensions가 켜져 있을 때만 존중돼요.

폴링 간격 (Polling Interval)

UI 익스텐션은 백그라운드 스레드에서 일부 정보를 폴링해요. attach된 데이터베이스 목록의 변화를 감시하고, MotherDuck에 연결했는지 감지해요.

이 검사들은 완료에 아주 짧은 시간이 걸리므로 기본 폴링 간격이 짧아요(284밀리초). 다음과 같은 SQL 명령으로 설정할 수 있어요:

SET ui_polling_interval = 284;

환경 변수 ui_polling_interval도 사용할 수 있어요.

폴링 간격을 0으로 설정하면 폴링이 완전히 비활성화돼요. UI의 데이터베이스 목록이 오래될 수 있고, MotherDuck에 연결하는 일부 방식이 제대로 동작하지 않을 수 있으므로 권장하지 않아요.

팁 (Tips)

DuckDB UI로 CSV 파일 열기

DuckDB CLI 클라이언트를 쓰면 -cmd 인자로 CSV를 뷰로 만든 뒤 UI를 시작할 수 있어요:

duckdb -cmd "CREATE VIEW ⟨view_name⟩ AS FROM '⟨filename⟩.csv';" -ui

읽기 전용 모드에서 UI 실행

DuckDB UI는 내부적으로 DuckDB 테이블을 저장소로 사용해요(예: 노트북 저장). 따라서 읽기 전용 데이터베이스에서 UI를 직접 실행하는 것은 지원되지 않아요:

duckdb -ui -readonly read_only_test.db

UI에서는 이렇게 나타나요:

Catalog Error: SET schema: No catalog + schema named "memory.main" found.

이를 우회하려면 다른 데이터베이스 파일에서 UI를 실행해요:

duckdb -ui ui_catalog.db

그런 다음 노트북을 열고 데이터베이스에 attach 해요:

ATTACH 'test.db' (READ_ONLY) AS my_db;
USE my_db;

제한 사항 (Limitations)

UI는 현재 windows_arm64를 지원하지 않아요.