활성 데이터베이스의 모든 테이블과 뷰에서 컬럼을 찾아 주는 읽기 전용 Beekeeper Studio 플러그인이에요.
PostgreSQL, MySQL, MariaDB를 지원해요. 대소문자를 구분하지 않는 부분 검색으로 스키마, 테이블/뷰, 컬럼, 데이터 타입을 보여 줘요. Structure 바로가기는 Beekeeper에 로드된 엔티티 목록에 있는 경우 일치하는 테이블을 열어요. 결과는 최대 500개로 제한돼요. 텔레메트리, 추가 서버, 데이터베이스 자격 증명이 필요 없어요.
중요: 플러그인은 + 옆의 화살표를 통해 별도 탭에서 열려요. 공식 SDK에서는 플러그인이 기본 사이드바 필터를 수정할 수 없어요.
CI 아티팩트로 설치하기 (Node 불필요)
- Actions → CI를 열고 성공한 실행에서 beekeeper-column-finder 아티팩트를 다운로드하세요.
- 아티팩트의 manifest.json 및 dist/ 디렉터리를 Beekeeper 플러그인 디렉터리 안의 beekeeper-column-finder 폴더에 압축 해제하세요:
- Windows: %APPDATA%\beekeeper-studio\plugins\beekeeper-column-finder
- Linux: ~/.config/beekeeper-studio/plugins/beekeeper-column-finder
- macOS: ~/Library/Application Support/beekeeper-studio/plugins/beekeeper-column-finder
- Windows 포터블: {app-directory}\beekeeper-studio-data\plugins\beekeeper-column-finder
- 커뮤니티 플러그인을 활성화하고(아래 참고) Beekeeper를 완전히 재시작한 뒤 + 옆의 드롭다운에서 Column Finder를 여세요.
예상 구조: beekeeper-column-finder/manifest.json, beekeeper-column-finder/dist/index.html 및 dist/assets/.
CI는 Node.js 22 환경의 Windows와 Ubuntu에서 빌드하고 단위 테스트를 실행한 뒤 설치 가능한 플러그인 번들을 업로드해요(30일간 제공되며, GitHub 아티팩트를 다운로드하려면 로그인이 필요할 수 있어요).
소스에서 설치하기 (Windows PowerShell)
PowerShell에서 다음 명령을 실행하세요:
git clone https://github.com/hugoalves-dev/beekeeper-studio-column-finder.git
cd beekeeper-studio-column-finder
npm install
npm test
npm run build
$pluginDirectory = Join-Path $env:APPDATA 'beekeeper-studio\plugins'
New-Item -ItemType Directory -Force -Path $pluginDirectory | Out-Null
$link = Join-Path $pluginDirectory 'beekeeper-column-finder'
if (Test-Path $link) {
Write-Host "Already exists: $link. Check its target before changing it."
} else {
New-Item -ItemType Junction -Path $link -Target (Get-Location).Path | Out-Null
}
이전 버전을 이미 연결했다면 junction을 다시 만들지 마세요. 최신 소스를 pull한 뒤 npm install, npm test, npm run build를 실행하고 Beekeeper를 재시작하세요.
커뮤니티 플러그인 활성화 (Beekeeper 5.7+)
Windows에서는 설정 파일을 여세요:
notepad "$env:APPDATA\beekeeper-studio\user.config.ini"
다른 설정은 그대로 두고 pluginSystem 섹션 하나를 추가하거나 수정하세요:
[pluginSystem]
disabled = false
communityDisabled = false
allow[]에 Column Finder ID를 추가하지 마세요. 여기에는 번들 플러그인 ID만 허용돼요. 이 설정은 다른 서드파티 플러그인도 허용하므로 신뢰할 수 있는 플러그인만 설치하세요. 관리자의 system.config.ini가 사용자 설정을 덮어쓸 수 있어요.
Beekeeper에서 Tools → Manage Plugins를 열어 Column Finder가 활성화되어 있는지 확인하세요. 필요하면 재시작하세요. 그런 다음 + 옆의 탭 드롭다운을 사용하세요.
동작 및 제한 사항
| 데이터베이스 | 검색 범위 |
|---|---|
| PostgreSQL | 활성 데이터베이스에서 접근 가능한 모든 사용자 스키마 (pg_catalog, information_schema, pg_toast* 제외) |
| MySQL | DATABASE(), 선택된 데이터베이스 |
| MariaDB | DATABASE(), 선택된 데이터베이스 |
검색은 information_schema.columns만 읽으며 메타데이터 권한이 그대로 반영돼요. 입력을 16진수로 인코딩된 UTF-8로 처리해 SQL 인젝션을 막고 퍼센트/밑줄 문자를 문자 그대로 다뤄요. 쓰기 작업은 전혀 하지 않아요. 최대 500개의 결과를 보여 주며, 더 있으면 표시해 줘요.
Structure 바로가기는 Beekeeper에 이미 로드된 테이블 목록에 의존해요. 테이블은 찾았는데 이동이 안 되면 엔티티 목록을 새로고침하세요. MySQL과 MariaDB에서는 호스트의 내부 표현에 맞추기 위해 스키마 없이 이동해요. 일부 PostgreSQL 스키마도 호스트 캐시에 없을 수 있어요.
개발 및 테스트
npm install
npm test
npm run build
npm run dev
- Node 내장 테스트 러너로 SQL 생성, 인젝션 방어, 방언, 테이블 이동 옵션을 검사해요(단위 테스트 8개).
- TypeScript 컴파일러가 타입을 검사하고 Vite가 프로덕션용 플러그인을 빌드해요.
- GitHub Actions가 Windows와 Ubuntu에서 테스트와 빌드를 실행한 뒤 manifest.json + dist를 아티팩트로 업로드해요.
- 단위 테스트는 실제 데이터베이스에 쿼리를 실행하지 않아요. MySQL/PostgreSQL/MariaDB 연동은 직접 확인하세요.
프로젝트 구조: src/sql.ts (SQL), src/navigation.ts (호스트 탭 이동), src/main.ts (SDK 연동), src/style.css 및 index.html (UI), tests/*.test.mjs (단위 테스트), .github/workflows/ci.yml (자동화).
문제 해결
- 플러그인이 없거나 비활성화된 경우: Tools → Manage Plugins와 user.config.ini를 확인하세요.
- 이전 버전이 표시되는 경우: 실제 플러그인 디렉터리나 junction 대상의 manifest.json을 확인하세요.
- Structure에서 “Table not found”가 표시되는 경우: 엔티티를 새로고침하세요. 호스트는 캐시된 테이블만 열 수 있어요.
- Windows/Linux 전환 후 빌드가 실패하는 경우: 해당 플랫폼에서 npm install로 의존성을 다시 설치하세요.
- SDK 문제: Beekeeper에서 Help → Show Developer Tools로 확인하세요.
참고 자료 및 라이선스
MIT 라이선스. 독립적인 커뮤니티 프로젝트이며 Beekeeper Studio의 보증을 받지 않았어요.