dbview가 Claude Code에 읽기 전용 PostgreSQL 탐색 창을 추가한다

dbview는 Claude Code 대화 옆에 데이터베이스를 살펴보는 창을 띄우는 플러그인이다. PostgreSQL 데이터베이스와 실행 중인 Postgres 컨테이너를 트리로 보여주며, 테이블의 열·제약조건·행·DDL을 확인할 수 있다. 모든 요청은 읽기 전용 세션에서 실행되고 문장 제한 시간은 10초다.

설치와 시작

사용자 범위에서 프로젝트마다 한 번 설치한다.

claude plugin install dbview --marketplace agntflw/claude-dbview --config psql_path=psql

설치 뒤 새 Claude Code 세션을 시작하고 /db를 입력한다. 이미 열린 세션에서는 /reload-plugins를 실행해야 플러그인이 보인다. 플러그인은 DATABASE_URL 또는 PG* 환경 변수에 지정된 데이터베이스와 실행 중인 모든 Postgres 컨테이너를 찾는다. 다른 데이터베이스는 /db connect postgres://user:password@host:5432/database [name]으로 추가한다. 데이터베이스를 선택한 뒤 테이블을 누르면 열, 행, DDL 화면을 전환할 수 있다. 행 화면은 50·100·500·1000개 단위로 볼 수 있다.

Claude Code에 설치를 맡기려면 아무 폴더에서 다음 지시문을 붙여 넣는다.

Install the dbview plugin for Claude Code globally for me (user scope), from github.com/agntflw/claude-dbview. 1. Run: claude plugin install dbview --marketplace agntflw/claude-dbview --scope user --config psql_path=psql If this Claude Code is too old for --marketplace, run instead: claude plugin marketplace add agntflw/claude-dbview, then claude plugin install dbview@claude-dbview --scope user 2. Run: claude plugin list, and check dbview is installed and enabled. 3. Check what it needs: psql --version, and docker --version if I use Postgres in Docker. Tell me what is missing and how to install it on this machine, but do not install it. 4. Tell me to start a new Claude Code session and type /db.

설치 후 claude plugin list에서 dbview가 설치 및 활성화됐는지 확인하고, psql --version을 실행한다. Docker에서 Postgres를 사용한다면 docker --version도 확인한다. 안내문은 필요한 항목이 빠졌는지 알려주되 직접 설치하지 말라고 Claude Code에 요청한다.

데이터베이스 탐색

트리의 최상위에는 데이터베이스가 놓이고, 그 아래에 스키마, Tables·Views·Materialized views·Sequences·Functions 폴더와 데이터베이스 객체 및 열이 표시된다. 테이블이나 뷰를 열면 열 이름과 자료형, NULL 허용 여부, 기본 키 또는 → schema.table(column) 참조, 기본값을 확인할 수 있다. 이어 키·외래 키·검사·NOT NULL 제약조건, 인덱스, 해당 객체를 참조하는 외래 키도 나온다.

행 화면은 키 순서로 첫 50·100·500·1000개 행을 보여주고 실행한 쿼리도 표시한다. DDL 화면에는 테이블 생성 마이그레이션에 해당하는 문장이 나온다. 시퀀스, 기본값과 이름이 지정된 제약조건이 있는 테이블, 인덱스, OWNED BY가 번호와 함께 표시되며 복사할 수 있다.

외래 키는 일반 텍스트처럼 보이는 링크로 표시된다. → schema.table(column) 참조, 외래 키 제약조건, Referenced by 아래의 ← schema.table(column) 항목, 또는 트리의 키 열을 누르면 연결된 테이블이 같은 탭에서 열린다. 트리에서 해당 테이블이 펼쳐지고 화면에 보이도록 이동한다. 오른쪽 위의 ← name을 누르면 한 번에 한 단계씩 돌아간다.

실행 중인 Postgres 컨테이너는 각각 트리에 나타난다. 마이그레이션 테스트가 남긴 mig_before, mig_after 같은 데이터베이스도 나란히 비교할 수 있다.

명령과 표시 방식

/db는 찾은 데이터베이스를 모두 표시한다. /db connect postgres://u:p@host:5432/db [name]은 데이터베이스를 이름으로 저장하며, 이름을 생략하면 데이터베이스 이름을 쓴다. /db forget <name>은 저장된 데이터베이스를 잊고, /db refresh는 목록을 다시 불러와 열린 데이터베이스를 새로 고친다. /db theme [system|light|dark]는 데스크톱 앱 창의 색상을 설정하며 기본값은 system이다.

목록 순서는 /db connect로 저장한 데이터베이스, DATABASE_URL 또는 PG* 변수가 가리키는 데이터베이스(저장 항목과 같으면 중복 생략), 실행 중인 각 Postgres 컨테이너다. 데이터베이스를 누르면 트리가 펼쳐지고 카탈로그는 처음 열 때 불러온다. 스키마나 폴더를 누르면 접히며, 테이블을 누르면 열린다. 열린 테이블을 다시 누르면 열 목록이 접힌다. 트리는 테이블명이나 열 이름으로 필터링할 수 있다.

터미널에서 창에 포커스가 있을 때 c, w, d는 각각 열·행·DDL 화면으로 전환한다. r은 새로 고침, y는 DDL 복사, b는 이동 뒤 돌아가기다. 창이 넓으면 트리와 열린 객체가 나란히 놓이고, 좁으면 객체가 트리 아래에 표시된다. 넓은 창에서 트리는 대략 3분의 1을 차지한다.

Claude 데스크톱 앱에서는 마우스 휠이나 트랙패드로 창 전체를 스크롤한다. 표를 선택하면 그 옆에, 창이 좁으면 선택한 행 바로 아래에 열린다. 스크롤을 멈추면 열린 표가 창 위쪽으로 돌아온다. 표 위에서 스크롤하면 표 위치가 유지돼 행을 읽을 수 있다. 터미널에서는 각 패널이 따로 스크롤된다. 포인터가 있는 부분에서 휠을 움직이고, 열린 객체 아래 막대 위에서는 열을 좌우로 이동한다. 막대 끝의 ▴ ▾ ◂ ▸를 누르면 같은 방향으로 이동하며, 넓은 그리드 위의 좌우 막대는 데스크톱 앱에서도 작동한다.

Claude 데스크톱 앱과 VS Code에서는 기본 system 설정이 앱의 밝고 어두운 테마를 따른다. 패널·알약 모양 요소·선은 옅고 투명하게 표시된다. /db theme light와 /db theme dark는 각각 고정된 따뜻한 회백색과 회색으로 패널을 표시한다. 버튼 글자색은 앱의 글자색을 그대로 사용하므로 앱 테마에 맞는 설정을 고르면 된다. /db theme system으로 기본 설정을 되돌릴 수 있고, 선택은 세션 사이에도 유지된다. 터미널은 설정과 관계없이 자체 색상을 사용한다.

설치 조건과 업데이트

터미널 세션에서는 /plugin install dbview --marketplace agntflw/claude-dbview를 입력하고 마켓플레이스 추가에 y로 답한 뒤 설치 범위를 고른다. 사용자 범위가 첫 번째 선택지다. 셸에서는 claude plugin install dbview --marketplace agntflw/claude-dbview를 실행할 수 있다. /plugin이 작동하지 않는 데스크톱 앱에서는 입력창 옆 +를 누르고 Plugins, Add marketplace에서 agntflw/claude-dbview를 추가한 다음 플러그인을 추가한다.

Claude Code가 v2.1.292보다 오래됐다면 마켓플레이스를 먼저 추가한 뒤 설치한다.

claude plugin marketplace add agntflw/claude-dbview claude plugin install dbview@claude-dbview

업데이트는 claude plugin update dbview@claude-dbview로 하거나 /plugin의 Marketplaces에서 claude-dbview 자동 업데이트를 켠다. claude.ai Team 또는 Enterprise 플랜에서는 Owner가 Organization settings의 Plugins & skills에서 조직 전체에 dbview를 추가할 수 있다. 그러면 각 구성원의 Claude Code에 dbview@synced로 전달된다.

플러그인을 업데이트하려면 claude plugin marketplace update claude-dbview claude plugin update dbview@claude-dbview 를 실행한다. 열린 세션에서 /reload-plugins를 실행하거나 새 세션을 시작한다. 로컬 폴더에서 설치했다면 해당 폴더에서 git pull을 실행한 뒤 플러그인을 다시 불러온다.

저장된 데이터베이스와 DATABASE_URL 데이터베이스에는 Claude Code가 실행되는 컴퓨터의 psql이 필요하다. 엔진은 PATH와 일반적인 Homebrew, Postgres.app, Linux 경로에서 이를 찾으며, /config의 psql_path 옵션으로 다른 경로를 지정할 수 있다. 컨테이너를 사용하려면 같은 컴퓨터에 docker가 있어야 한다. 엔진은 컨테이너 안에서 POSTGRES_USER 계정으로 POSTGRES_DB에 접속해 docker exec … psql을 실행하므로 공개 포트, 비밀번호, 호스트의 psql은 필요하지 않다.

/db가 나타나지 않으면 새 세션을 시작하거나 열린 세션에서 /reload-plugins를 실행한다. 셸에서 설치한 플러그인은 설치 뒤 시작한 세션에서 불러온다. claude --version으로 버전을 확인한다. hooks 모듈을 쓰는 플러그인인 mods에는 최신 Claude Code가 필요하며, 버전이 오래됐다면 claude update를 실행한다. claude plugin list에서 dbview가 활성화됐는지 확인하고, 세션의 /plugin에서 로드 오류를 확인할 수 있다. 설치 뒤 표시되는 userConfig option not yet set 안내는 무해하며 psql_path는 기본적으로 psql을 사용한다.

MySQL 추가 안내와 개발

dbview는 현재 PostgreSQL만 읽는다. 저장소는 Claude Code에 MySQL을 PostgreSQL 옆에 추가하도록 요청하는 지시문도 제공한다. 지시문은 MySQL 8.4 LTS 또는 버전을 고정한 MySQL 8.4.5를 대상으로 하며, PostgreSQL 동작을 바꾸지 않도록 요구한다. claude plugin list에서 확인한 플러그인 폴더를 우선 사용하고, 없으면 로컬 폴더를 찾고, 그것도 없으면 저장소를 ~/.claude/plugins-src/claude-dbview에 복제해 작업하도록 지정한다.

지시문에 포함된 테스트 데이터베이스 실행 명령은 다음과 같다.

docker run -d --name mysql84 -e MYSQL_ROOT_PASSWORD=dev -e MYSQL_DATABASE=shop -p 33306:3306 mysql:8.4

버전을 고정하려면 명령의 mysql:8.4를 mysql:8.4.5로 바꾼다. 연결을 받을 때까지 기다린 뒤 dev/seed.sql을 MySQL용으로 옮겨 불러오도록 한다. 스키마는 데이터베이스로, serial은 AUTO_INCREMENT로 바꾸고 같은 테이블·키·행을 유지하도록 요구한다.

저장소 구조를 따라 먼저 타입, 다음 엔진, 마지막으로 창을 확장하도록 제시한다. types/index.d.ts의 DbSource에 'postgres' | 'mysql' 엔진 필드를 추가하되 모든 요청 형태를 유지한다. hooks/engine/에는 psql.ts 옆에 MySQL 드라이버를 추가한다. 드라이버는 컨테이너 안에서 docker exec -i <container> mysql -N -B ...를 실행하거나 mysql:// URL에 대해 호스트의 MySQL 클라이언트를 사용한다. 비밀번호는 명령줄이 아니라 MYSQL_PWD로 전달한다. 모든 세션에 SET SESSION TRANSACTION READ ONLY와 max_execution_time=10000을 적용하도록 한다.

각 응답은 information_schema의 카탈로그·열·제약조건·인덱스를 JSON_OBJECT와 JSON_ARRAYAGG로 구성한 단일 JSON 문서로 만들고, DDL에는 SHOW CREATE TABLE / VIEW를 사용하도록 지시한다. hooks/engine/docker.ts는 MySQL과 MariaDB 컨테이너도 찾도록 확장한다. 계정은 MYSQL_ROOT_PASSWORD를 사용하는 root 또는 MYSQL_USER와 MYSQL_PASSWORD를 사용하며, 데이터베이스는 MYSQL_DATABASE에서 가져온다. /db connect는 postgres:// 외에 mysql:// URL도 받도록 한다.

창에는 각 데이터베이스 행과 전환기에 엔진과 버전을 표시한다. 예시는 MySQL 8.4 · docker다. MySQL에는 데이터베이스 안의 스키마 단계가 없으므로 해당 단계를 생략하고, 시퀀스와 구체화된 뷰도 표시하지 않는다. 지시문은 dev/engine-e2e.ts에 mysql84 대상 카탈로그·열·외래 키·인덱스·키 순서의 50개 행·DDL 검사를 추가하고 tests/fixtures.ts를 다시 기록하도록 요구한다. MySQL 소스의 창 테스트도 추가한 뒤 claude plugin validate .와 claude plugin test .를 실행한다. 마지막으로 .claude-plugin/plugin.json의 버전을 올리고 해당 폴더에서 플러그인을 다시 설치한다.

claude plugin install dbview --marketplace <folder> --scope user

작업이 끝나면 새 세션을 시작해 /db를 입력하고 PostgreSQL과 MySQL 데이터베이스가 나란히 표시되는지 확인하도록 안내한다. 이는 저장소가 제공하는 작업 지시문이며, 자료는 MySQL 지원이 이미 구현됐다고 말하지 않는다.

구현 구조에서 types/index.d.ts는 소스·카탈로그·관계 상세·미리보기·DDL과 창 상태를 양쪽 구성요소 사이에서 정의한다. hooks/engine/은 Claude Code CLI 안에서 작동하는 서버 측 코드로, SQL을 사용해 psql 또는 docker exec … psql을 통해 요청마다 JSON 문서 하나를 만든다. 비밀번호는 명령줄이 아니라 PGPASSWORD로 전달한다. hooks/client/는 표면별 요소를 사용해 하나의 뷰 상태에서 창을 그리므로 터미널·데스크톱·VS Code·모바일에서 같은 트리를 쓴다. hooks/register.tsx는 /db 명령과 창을 등록한다.

개발 시 claude plugin validate .와 claude plugin test .는 각 표면의 창 테스트를 실행하며, 기록된 psql 및 Docker 응답을 재생한다. 샘플 데이터베이스는 psql -f dev/seed.sql <db>로 준비한다. 실제 Postgres와 Docker를 대상으로 엔진 종단 간 테스트를 실행하는 명령은 다음과 같다.

DATABASE_URL=postgres://... bun dev/engine-e2e.ts

--record 옵션은 tests/fixtures.ts를 새로 기록한다. 종단 간 테스트 스크립트는 마이그레이션 테스트를 위해 dev/seed.sql로 초기화된 컨테이너 두 개도 기대한다.

docker run -d --name mig_before -e POSTGRES_PASSWORD=dev -e POSTGRES_DB=shop -p 55431:5432 postgres:16 docker run -d --name mig_after -e POSTGRES_PASSWORD=dev -e POSTGRES_DB=shop -p 55432:5432 postgres:16 # seed both, then on mig_after: # alter table sales.orders add column shipped_at timestamptz; # create index orders_status_idx on sales.orders (status); # alter table sales.orders add constraint total_positive check (total >= 0);

라이선스는 MIT이며, 저작권 표기는 2026년 AGENTFLOW다. 자세한 내용은 저장소의 LICENSE를 참조하면 된다.