설정과 앱 데이터
DuckLocal은 디스크에 데이터베이스 파일 하나를 저장하고, 창이 실행되는 동안 작은 파일 하나와 로그 파일을 더 저장합니다. 온라인 기본 지도를 켜면 지도 타일도 캐시하고, 내려받은 업데이트도 캐시에서 기다립니다. 그 밖의 모든 것은 세션이 유지되는 동안 메모리에 있습니다. 대시보드 검토 주석은 예외로, 앱 데이터 폴더가 아니라 대시보드 파일 옆에 저장됩니다(주석으로 검토 참고).
저장 위치
| 플랫폼 | 경로 |
|---|---|
| macOS | ~/Library/Application Support/DuckLocal/history.duckdb |
| Windows | %APPDATA%\DuckLocal\data\history.duckdb |
| Linux | ~/.local/share/ducklocal/history.duckdb |
DuckDB 파일에는 네 개의 테이블이 있습니다: 쿼리 기록, 등록된 데이터 파일, 열려 있는 데이터베이스 옆에 연결한 데이터베이스, 그리고 작은 키/값 설정 테이블입니다. 설정에는 인터페이스 언어와 크기, 열려 있는 쿼리와 대시보드 탭, 최근 대시보드 목록, 기본 지도와 업데이트 확인 사용 여부가 포함됩니다. 앱이 실행되는 동안에는 함께 생기는 .wal 파일(DuckDB의 미리 쓰기 로그)이 옆에 있습니다.
데이터셋은 애플리케이션 데이터베이스에 절대 복사되지 않습니다. 등록된 파일은 파일 경로로 저장되며 DuckLocal이 시작할 때마다 자동으로 다시 연결됩니다.
창이 열려 있는 동안 옆의 gui-endpoint.json에는 ducklocal open이 창에 접근할 때 쓰는 루프백 포트와 임의 토큰이 들어 있습니다. 계정 본인만 읽을 수 있고, 창이 종료되면서 남은 오래된 gui-endpoint.json은 해가 없습니다.
옆의 logs 폴더에는 창의 로그 ducklocal.log(그리고 이전 실행의 ducklocal.previous.log)가 있습니다. DuckLocal이 충돌하면 먼저 crash-….log 보고서를 그곳에 쓰고, 다음 실행에서 보고서 표시와 함께 무슨 일이 있었는지 알려 줍니다. 최근 열 개 보고서가 보관됩니다. 이슈를 올릴 때 보고서를 첨부하세요. 로그 폴더 열기는 그 폴더를 엽니다: macOS에서는 DuckLocal 메뉴에 있고, 모든 플랫폼에서 상태 표시줄 오른쪽 끝 버전의 오른쪽 클릭 메뉴에 있습니다. ducklocal 명령은 로그 파일을 쓰지 않으며, 오류는 호출한 쪽으로 전달됩니다.
온라인 기본 지도의 지도 타일은 플랫폼 캐시 폴더로 갑니다 — macOS는 ~/Library/Caches/DuckLocal/tiles, Windows는 %LOCALAPPDATA%\DuckLocal\cache\tiles, Linux는 ~/.cache/ducklocal/tiles — 타일 서버마다 폴더 하나입니다. 삭제해도 해가 없으며, 타일은 다시 내려받을 뿐입니다. 내려받은 업데이트는 설치될 때까지 같은 캐시 폴더의 updates에서 기다립니다.
다시 시작해도 유지되는 것
| 기억하는 항목 | 위치 |
|---|---|
| 등록된 데이터 파일 — 경로, 뷰 이름, 종류 | 앱 데이터 파일 |
| 쿼리 기록, 실패 포함 | 앱 데이터 파일 |
| 인터페이스 언어 | 앱 데이터 파일 |
| 인터페이스 크기 | 앱 데이터 파일 |
| 첫 실행 안내를 본 적이 있는지 | 앱 데이터 파일 |
| 사이드바를 숨겼는지 | 앱 데이터 파일 |
| 열려 있는 데이터베이스 옆에 연결한 데이터베이스와 각각의 읽기 전용 여부 | 앱 데이터 파일 |
| 마지막으로 연 데이터베이스 파일 | 앱 데이터 파일 — 존재하는 동안 시작할 때 다시 열림 |
| 열려 있는 쿼리 탭과 그 제목, SQL | 앱 데이터 파일 |
| 열려 있는 대시보드 탭과 그 제목 | 앱 데이터 파일 |
| 온라인 기본 지도가 켜져 있는지 | 앱 데이터 파일 |
| 시작할 때 업데이트를 확인하는지 | 앱 데이터 파일 |
| 최근에 연 대시보드(사이드바의 대시보드) | 앱 데이터 파일 |
| 기억하지 않는 항목 | 비고 |
|---|---|
| 결과 패널 내용 | 메모리에만 — 쿼리를 다시 실행 |
| 인메모리 데이터베이스에서 만든 테이블과 뷰 | 유지되지 않지만, 종료하거나 다른 데이터베이스를 열 때 저장하도록 안내받습니다. **데이터베이스로 저장…**은 그것들을 .duckdb 파일에 씁니다 |
| 그사이 옮겨졌거나 삭제된 데이터베이스 파일 | 다음 실행은 메모리에서 시작 |
| 창 크기와 위치 | 1440×900 고정, 최소 960×600 |
| 사이드바와 결과 패널 크기 | 실행할 때마다 고정 |
| 결과 필터 | 메모리에만 |
| 대시보드 필터가 고른 값 | 메모리에만; 탭을 다시 불러오는 동안에는 유지 |
| 테마 | 항상 밝게 시작 — 아래 참고 |
| S3 자격 증명 | 설계상 세션 동안만 |
테마만 예외입니다. 언어 토글은 유지되지만 테마 토글은 유지되지 않고, 모든 실행이 밝은 모드로 시작합니다.
일반 실행은 메모리에서 동작하므로 거기서 만든 테이블과 뷰는 창과 함께 끝납니다. DuckLocal은 그 전에 묻습니다. 종료하거나, 창을 닫거나, 그런 테이블이 있는 상태에서 다른 데이터베이스를 열면 데이터베이스로 저장…, 저장하지 않고 종료, 취소를 제시합니다. 데이터베이스로 저장…(⌘⇧S, 또는 파일 → 데이터베이스로 저장…)은 스키마, 테이블과 행, 뷰, 매크로, 시퀀스를 .duckdb 파일로 복사하고 창을 그 파일로 옮기므로 이후 변경은 파일에 기록되고, 다음 실행은 그 파일을 다시 엽니다. 등록된 파일로 DuckLocal이 만든 뷰는 세지 않습니다. 실행할 때마다 파일에서 다시 만들기 때문입니다.
네트워크
DuckLocal은 직접 켜기 전까지 스스로 네트워크 요청을 하지 않습니다. 스위치는 두 개이고 둘 다 처음에는 꺼져 있으며, 여기에 직접 요청하는 것들이 더해집니다:
| 요청 | 시점 | 기기 밖으로 나가는 것 |
|---|---|---|
| 온라인 기본 지도 | 켠 뒤 지도를 그릴 때마다 | 어떤 타일이 필요한지: 대략 보고 있는 지역과 줌 |
| 업데이트 확인 | 버전을 클릭할 때, 또는 켠 뒤에는 시작할 때 | 최신 릴리스의 버전을 묻는 dl.ducklocal.app으로의 요청 하나; 더 새 버전이 있으면 그 패키지의 다운로드 |
| S3 | S3를 설정하고 쿼리할 때 | 설정한 스토리지로 보내는 요청 |
| 확장 기능 | 설치나 업데이트를 클릭하거나 INSTALL을 실행할 때 | DuckDB 확장 기능 저장소에서의 다운로드 |
| SQL의 원격 데이터 | SQL에 https://, s3://, 원격 데이터베이스가 나올 때, 대시보드가 열릴 때 그 SQL 포함. 확장 기능이 이미 설치되어 있어야 함 | SQL이 요청하는 것, 주소에 적힌 내용 포함 |
텔레메트리는 없으며, 실행하는 SQL을 제외하면 이 중 어느 것도 행 데이터를 보내지 않습니다. SQL은 시키는 대로 합니다: 주소에 테이블의 값을 실을 수 있습니다. 그래서 httpfs가 설치된 상태에서는 신뢰하지 않는 사람의 .dash 파일을 열 때 데이터가 나갈 수 있습니다. 네트워크와 개인정보에 모든 경로와 직접 확인하는 방법이 정리되어 있습니다.
온라인 기본 지도
지도 차트는 대시보드에서든 결과의 차트 탭에서든 점 아래에 OpenStreetMap 타일을 그릴 수 있습니다. 보기 → 온라인 기본 지도 (OpenStreetMap) 로 켜고 끄며, 선택은 기억됩니다(map_tiles 설정, on 또는 off). 기본은 꺼짐입니다. 요청한 타일만 기기 밖으로 나가며 — 대략 보고 있는 지역과 줌 — 행 데이터는 나가지 않습니다.
가져오기는 OpenStreetMap Foundation의 타일 정책을 따릅니다: 식별 가능한 User-Agent, 동시 요청 최대 두 개, 타일은 일주일 동안 캐시에서 재사용, 대량 사전 가져오기 없음, 지도에 저작자 표시. 더 많이 쓸 때는 설정 테이블의 map_tile_url을 다른 서버의 {z}/{x}/{y} URL 템플릿으로 지정하세요.
업데이트 확인
상태 표시줄은 DuckLocal의 버전으로 끝납니다 — DuckLocal 0.3.0. 클릭하면 dl.ducklocal.app에서 최신 릴리스를 확인합니다:
- 최신 상태 — 실행 중인 버전이 최신입니다.
- v0.3.1 내려받는 중… — 더 새로운 릴리스가 있어 DuckLocal이 내려받고 있습니다. 패키지는 압축을 풀기 전에 릴리스에 공개된 크기와 SHA-256으로 검증하고, macOS에서는 실행 중인 앱의 서명으로도 검증합니다.
- 다시 시작하여 v0.3.1로 업데이트 — 새 버전이 준비되었습니다. 클릭하면 종료하고, 설치하고, 다시 엽니다. 그렇지 않으면 다음에 DuckLocal을 종료할 때 설치됩니다.
- 업데이트 있음: v0.3.1 — 이 복사본이 스스로 설치할 수 없는 새 릴리스입니다. 직접 컴파일한 빌드이거나, 쓰기 권한이 없을 수 있는 폴더에 있는 앱입니다. 클릭하면 패키지를 내려받으며, 지금 버전을 설치한 방식으로 설치하세요.
- 업데이트 확인 실패 — 마우스를 올리면 이유(오프라인, 프록시, 체크섬과 맞지 않는 다운로드)가 표시됩니다. 클릭하면 다시 시도합니다.
업데이트는 dl.ducklocal.app에서 오며, GitHub 릴리스와 같은 패키지를 중국 본토에서도 빠른 미러로 제공합니다.
macOS에서는 DuckLocal 메뉴에 같은 확인이 **업데이트 확인…**으로 있고, 시작할 때 업데이트 확인은 앱이 시작할 때마다 한 번 확인합니다. 켜기 전까지는 꺼져 있습니다(update_check 설정, on 또는 off). 그전까지 DuckLocal은 클릭할 때만 확인합니다.
언어
제목 표시줄의 EN / 中 버튼은 인터페이스 언어를 즉시 바꾸고 선택을 기록합니다.
처음 실행할 때 — 어떤 설정도 저장되기 전 — 언어는 시스템 로캘에서 가져옵니다: LC_ALL이나 LANG에 zh가 있으면 중국어, 그 밖의 경우 영어입니다. 알 수 없는 저장 값은 중국어로 대체됩니다.
일부 문자열은 의도적으로 번역하지 않습니다: DuckLocal, S3와 EXPLAIN 버튼 레이블, EN / 中 토글, 자격 증명 자리 표시자입니다. 엔진과 네트워크 오류 메시지는 그대로 표시되며 인터페이스 언어와 관계없이 항상 영어입니다.
테마
해/달 버튼은 밝은 테마와 어두운 테마를 전환합니다. 테마 선택기도 편집할 테마 파일도 없습니다. 두 가지 모드가 전부입니다.
인터페이스 크기
텍스트, 아이콘, 컨트롤이 네 단계로 함께 조정됩니다:
| 크기 | 기본 텍스트 | 편집기 텍스트 |
|---|---|---|
| 작게 | 13px | 12px |
| 기본 | 14px | 13px |
| 크게 | 16px | 15px |
| 아주 크게 | 18px | 17px |
제목 표시줄의 Aa 버튼에서 고르거나, ⌘+(크게), ⌘−(작게), ⌘0(기본으로)으로 단계를 바꿀 수 있습니다. 이 단축키는 포커스가 어디에 있든, SQL 편집기에서도 동작합니다. 선택은 기억되며 밝은 테마와 어두운 테마를 오가도 유지됩니다.
직접 끌어서 바꾼 패널 크기와 대시보드 그래프 높이는 픽셀 단위로 남습니다. 그것은 인터페이스가 아니라 직접 조정하는 값이기 때문입니다.
초기화
처음부터 시작하려면 — 기록, 등록된 파일, 연결된 데이터베이스, 기억된 탭, 모든 설정을 지우려면 — DuckLocal을 종료하고 앱 데이터 폴더를 삭제합니다:
rm -rf ~/Library/Application\ Support/DuckLocal # macOS
rm -rf ~/.local/share/ducklocal # LinuxWindows에서는 %APPDATA%\DuckLocal을 삭제하세요.
다음 실행에서 새로 만듭니다. 데이터 파일은 이 작업에 영향받지 않으며, DuckLocal 자체 기록만 지워집니다.
문제 해결
증상, 원인, 해결 방법은 문제 해결 페이지에 모아 두었습니다.
