agent-database-cli

CLI 기반의 다중 데이터베이스 운영 도구로, 일반적인 데이터베이스 연결, 쿼리, 메타데이터 읽기 및 연결 재사용 기능을 Agent가 호출할 수 있는 로컬 명령으로 패키징합니다.

MySQL · PostgreSQL · Redis · Oracle · MongoDB · 읽기 전용 모드 · 명령어 블랙리스트 · SQLcl Oracle · 로컬 데몬

AI 원클릭 설치 · 설치 · 설정 · 권한 설정 · 페이지 편집 · Oracle SQLcl · 라이선스 · 친구 링크

중국어 | English

</div>

개요 (简介)

agent-database-cli는 Agent를 위한 로컬 다중 데이터베이스 CLI 도구로, Rust로 구현되어 MySQL, PostgreSQL, Redis, Oracle, MongoDB의 연결, 쿼리, 메타데이터 읽기, 읽기 전용 제어, 명령어 블랙리스트 및 비밀번호 암호화 기능을 패키징합니다.

이 도구가 할 수 있는 일:

현재 지원되는 데이터베이스 유형과 로컬에 설정된 연결 목록을 나열합니다.
지정된 데이터베이스에 SQL, Redis 명령어 또는 MongoDB JSON 명령을 실행합니다.
테이블, 컬럼, 컬렉션, Redis keys 등 데이터베이스 메타데이터를 조회합니다. (Redis keys의 메타데이터는 블로킹 방식의 KEYS 대신 SCAN으로 배치 읽기를 수행하여 방지합니다.)
단일 데이터베이스 설정별로 읽기 전용 모드와 명령어 블랙리스트를 활성화할 수 있습니다.
Oracle은 기본적으로 SQLcl을 사용하며, Oracle Instant Client가 필요한 경우 oracle/oracledb 네이티브 드라이버로 명시적으로 전환할 수 있습니다.
로컬 페이지에서 설정 파일을 시각적으로 편집하고, 수정 후 즉시 검증 및 저장합니다.
비밀번호, token, secret을 비식별화(de-sensitize)하기 전에는 저장하거나 출력하지 않습니다.

드라이버 설정표:

데이터베이스	`type`	기본 드라이버	드라이버 전환 설정
MySQL	`mysql`	Rust 네이티브 드라이버 `mysql_async`	현재 지원하지 않음
...

설치 (安装)

환경 요구 사항

Node.js >= 20
npm >= 10
시스템 지원: Windows / macOS / Linux
설치 시 해당 플랫폼의 Rust 바이너리 서브 패키지를 자동으로 다운로드합니다. 현재 지원하는 OS는 macOS x64/arm64, Linux x64/arm64, Windows x64입니다.
로컬 네트워크에서 대상 데이터베이스에 접근 가능해야 합니다.
Docker 통합 테스트를 사용하는 경우, Docker와 Docker Compose가 필요합니다.
Oracle을 SQLcl로 사용할 경우, 로컬 환경에서 SQLcl과 Java21이 실행 가능해야 합니다.

AI 원클릭 설치 (AI 一键安装)

설치는 https://github.com/sleepinginsummer/agent-database-cli/blob/main/AI_INSTALL.md를 읽고, 설명에 따라 CLI를 설치하고 `SKILL.md` 파일을 추가하세요.

수동 전역 설치 (手动全局安装)

npm 패키지 설치 및 사용법:

npm install -g agent-database-cli
agent-database-cli --help

만약 npm 패키지 설치가 제한된 경우, 다음 등가적인 소스 코드 설치 방식을 사용하세요:

git clone https://github.com/sleepinginsummer/agent-database-cli.git
cd agent-database-cli
npm install
...

Agent 스킬(skill) 설치 및 업데이트:

agent-database-cli install-skill --dry-run
agent-database-cli install-skill

설정 (Configuration)

기본 설정 파일 위치:

~/.agent-database-cli/config.json

환경 변수를 통해 설정 위치를 수정할 수 있습니다:

AGENT_DATABASE_CLI_CONFIG=/path/to/config.json agent-database-cli list

설정 파일은 객체(object) 형태이며, databases 내의 각 key는 데이터베이스 연결 이름입니다.

연결 목록은 그룹화 및 태그 필터링을 지원하며, 대소문자를 구분하고 동시에 지정할 경우 교집합(intersection)을 가져옵니다:

agent-database-cli list --group "운영 환경"
agent-database-cli list --tag 앱
agent-database-cli list --group "운영 환경" --tag 앱

반환 결과는 configured 연결 이름 배열을 유지하며, 새로운 connections 배열을 추가합니다. 이 배열에는 name, type, group, tags가 포함됩니다. 분류되지 않은 연결의 경우 group은 null이고 tags는 []입니다. 일치하는 항목이 없을 경우 두 배열 모두 비어 있습니다.

편집 페이지 좌측에서는 '전체 / 그룹별 / 태그별'을 전환할 수 있으며, 분류는 접기(fold)를 지원합니다. 검색 기능은 연결 이름, 유형, URL, 그룹 및 태그를 매칭할 수 있습니다. 폼(Form)은 그룹과 태그를 입력하거나 선택하는 것을 지원하며, 태그는 Enter 키로 추가하고 × 버튼을 클릭하여 제거합니다. 다중 태그가 지정된 연결은 각 태그 분류 아래에 나타나며, 편집되는 것은 동일한 하나의 연결입니다.

연결 설정 (Connection Configuration):

필드	적용 범위	기본값	설명
`type`	모든 데이터베이스	없음	데이터베이스 유형. `mysql`, `postgres`, `redis`, `oracle`, `mongodb`를 지원합니다.
...

PostgreSQL URL은 sslmode 파라미터를 지원하며, 값으로는 disable, prefer, require, verify-ca, verify-full이 있습니다. 예를 들어 클라우드 데이터베이스에서는 postgres://user:password@host:5432/app?sslmode=require가 자주 사용되며, 운영 환경에서 인증서 검증이 필요한 경우 verify-full을 우선적으로 사용하는 것이 좋습니다.

Redis 클러스터 설정 (Redis Cluster Configuration):

필드	기본값	설명
`nodes`	없음	Redis 클러스터 노드 URL 배열. 최소 1개를 구성해야 하며, `redis://`와 `rediss://`를 지원합니다.

Redis 클러스터 사용 규칙:

시나리오	요구 사항
클러스터 모드 활성화	반드시 `url`과 `redisCluster.nodes`를 동시에 구성해야 합니다.
...

SSH 터널 설정은 비밀번호, 개인 키(private key), 비밀번호와 개인 키 조합, 통과 구문(passphrase)이 포함된 개인 키 인증을 지원합니다.

필드	기본값	설명
`host`	없음	SSH 점프 서버 주소입니다.
...

민감 정보는 해당 연결을 처음 사용할 때 수동으로 암호화되어 저장됩니다. 데이터베이스 URL의 평문 비밀번호, sshTunnel.password, 그리고 sshTunnel.passphrase는 설정 디렉터리의 secrets.json에 기록되며, 로컬 키는 secret.key에 기록되고, 설정 파일 내의 평문 필드는 비워지거나 암호화된 내용으로 대체되어 저장됩니다. 이후 실행 시에는 참조(reference)를 통해 메모리에서 복호화하여 사용합니다. 비밀번호를 수정하려면 해당 평문 필드를 새 값으로 다시 채우고 다음 번에 사용하면 기존 암호문을 덮어씁니다.

보안 정책 (Security Policy):

정책	설명
검사 우선순위	먼저 블랙리스트를 확인하고, 일치하는 경우 즉시 거부합니다. 일치하지 않은 경우에만 읽기 전용 모드를 확인합니다.
...

참고 설정 (Reference Configuration):

{
  "databases": {
    "local-mysql": {
...

권한 설정

권한 제어는 readonly와 blacklist를 동시에 사용하는 것이 좋으며, 둘 중 하나에만 의존해서는 안 됩니다.

읽기 전용 모드 (Read-Only Mode)

기본값은 true입니다.
readonly 설정을 하지 않아도 여전히 읽기 전용 모드로 처리됩니다.
읽기 전용 모드는 쓰기 의미를 가진 쿼리(예: PostgreSQL의 SELECT INTO, MongoDB aggregate 내의 $out, $merge)를 추가적으로 거부합니다.
일상적인 모든 쿼리 연결은 기본 읽기 전용 상태를 유지하는 것이 권장됩니다.
데이터 수정이 필요할 경우, AI가 해당 SQL 또는 명령을 먼저 생성하도록 하고, 사용자가 확인한 후에 실행하는 것을 권장합니다.
명시적으로 쓰기가 필요한 전용 연결에 한해서만 readonly: false로 별도 설정해야 합니다.

명령어 블랙리스트 (Command Blacklist)

블랙리스트의 우선순위가 읽기 전용 모드보다 높습니다.
블랙리스트에 해당하면 즉시 거부되며, 더 이상 읽기 전용 여부를 판단하지 않습니다.
데이터베이스 삭제, 테이블 삭제, 구조 변경, 대량 쓰기, 캐시 비우기 등 고위험 명령을 차단하는 데 적합합니다.
운영(Production) 데이터베이스, 공유 테스트 데이터베이스, 온라인 Redis 모두 블랙리스트를 설정할 것을 권장합니다.

실행 순서 (Execution Order)

먼저 blacklist를 확인합니다.
블랙리스트에 해당하면 즉시 거부됩니다.
해당하지 않으면 readonly를 확인합니다.
readonly가 적용되면 읽기 명령만 허용됩니다.

일반적인 고위험 명령어

MySQL / PostgreSQL / Oracle의 일반적인 고위험 SQL:

["drop", "truncate", "delete", "update", "insert", "merge", "alter", "create", "replace", "grant", "revoke", "call", "copy", "load", "vacuum", "analyze"]

Redis의 일반적인 고위험 명령어:

["flushall", "flushdb", "del", "unlink", "set", "mset", "expire", "rename", "hset", "lpush", "rpush", "sadd", "zadd", "keys"]

MongoDB의 일반적인 고위험 명령어:

["insertOne", "insertMany", "updateOne", "updateMany", "replaceOne", "deleteOne", "deleteMany", "findAndModify", "findOneAndUpdate", "findOneAndDelete", "drop", "dropDatabase", "createIndex", "dropIndex", "$out", "$merge"]

권장 설정 예시

운영 데이터베이스 추천:

{
  "type": "mysql",
  "url": "mysql://user:password@prod-db:3306/app",
...
}

쓰기를 허용하는 전용 연결 추천:

{
  "type": "postgres",
  "url": "postgres://user:password@write-db:5432/app",
...
}

Oracle은 이중 드라이버 설계를 유지합니다.

oracleDriver 미설정 시: 기본 SQLcl을 사용합니다.
oracleDriver: "sqlcl": 명시적으로 SQLcl을 사용하여, Oracle 11과 같은 구형 데이터베이스나 Instant Client 또는 네이티브 드라이버 호환성이 불안정한 환경에 적합합니다.
oracleDriver: "oracle": Rust Oracle 네이티브 드라이버를 명시적으로 사용하며, Oracle Instant Client / ODPI-C에 의존합니다.
oracleDriver: "oracledb": Node.js 버전의 네이티브 드라이버 호환 값입니다. Rust 버전은 oracle 네이티브 진입점을 통해 처리됩니다.

현재 기본 진입점은 Rust 네이티브 CLI로 전환되었으며, npm 플랫폼 패키지 형태로 Windows, Linux, macOS 바이너리를 배포합니다. Oracle의 기본값은 SQLcl이며, 네이티브 Oracle 드라이버는 명시적으로 설정해야 합니다.

편집 페이지 (Editor Page)

editor 명령어를 사용하면 로컬에서 편집 서비스를 시작하고, 웹페이지를 통해 설정을 직접 수정할 수 있습니다:

agent-database-cli editor start              # 서비스 시작 및 브라우저 열기
agent-database-cli editor start --no-open    # 서비스만 시작 (브라우저 미열기)
agent-database-cli editor start --port 4599  # 포트 지정 (기본값은 임의로 사용 가능한 포트)
...

명령을 실행하면 페이지 주소 http://127.0.0.1:<포트>/#t=<접근 토큰>이 출력됩니다.

항목	설명
수신 주소	오직 `127.0.0.1`만 수신하며, 로컬 네트워크에 노출되지 않습니다.
...
페이지는 `type`에 따라 현재 데이터베이스에서 사용 가능한 필드만 표시하며, 연결 URL은 사용자 이름, 비밀번호, 호스트, 포트, 라이브러리 이름을 자동으로 분해하고 로컬 컴퓨터 → SSH 점프보드 → 데이터베이스로의 접근 경로를 그립니다.

오른쪽 JSON 패널에는 디스크에 기록될 전체 내용이 표시되며, 텍스트를 직접 편집할 수도 있습니다. 편집 결과는 실시간으로 검증되어 양식(form)에 동기화됩니다:

패널 기능	설명
범위 전환	`현재 연결`은 선택된 연결만 표시합니다 (키 이름이 연결 이름이며, 다른 구성에 직접 복사 가능). `전역`은 전체 파일을 표시합니다.
...
민감 필드 처리 방식:

| 상태 | 페이지 표현 |
| :--- |
| passwordRef / passphraseRef가 있는 경우 | 기본적으로 암호화된 상태로 표시됩니다. 해당 필드의 눈 아이콘을 클릭해야 필요한 시점에만 복호화됩니다 (현재 구성에서 참조되는 ref만 허용). 복호화 결과는 입력 상자에 표시될 뿐, 양식 데이터나 구성 파일에 다시 쓰이지 않습니다. |
| ... |
페이지는 오직 구성 파일을 작성하는 역할만 하며, 실제 권한 제어는 여전히 CLI가 명령을 실행할 때 블랙리스트 및 읽기 전용 모드를 기준으로 판단합니다.

쿼리 시간 초과 및 연결 재사용 (Query Timeout and Connection Reuse)

AGENT_DB_QUERY_TIMEOUT_SECS: 단일 daemon 데이터베이스 요청의 응답 기한입니다. 기본값은 60초이며, 초기화, 대기열 처리 및 쿼리 읽기를 모두 포함합니다. 양의 정수만 허용하며, 유효하지 않은 값은 기본값을 사용합니다.
AGENT_DB_DAEMON_IDLE_SECS: daemon에 활성 요청이 없을 때 종료 기한입니다. 기본값은 1800초이며, 5초마다 확인됩니다. 요청을 수신하는 시점부터 응답 쓰기가 완료될 때까지 모두 활동 시간으로 계산됩니다. 양의 정수만 허용하며, 유효하지 않은 값은 기본값을 사용합니다. 단일 라이브러리 연결의 keepAliveSeconds는 여전히 기본값 180초입니다.
환경 변수를 수정한 후에는 먼저 agent-database-cli daemon stop을 실행해야 하며, 다음 명령에서 새로운 값으로 daemon이 시작됩니다.
MySQL의 동일 라이브러리 쿼리는 연결 풀(connection pool)을 통해 병렬로 실행됩니다. URL에 pool_max가 생략된 경우 max(4, 명시적 pool_min)을 사용합니다. 명시적인 최소값, 최대값 및 기타 풀 설정은 유효하게 유지되며, 충돌 제약 조건 오류가 발생할 수 있습니다. 시간 초과는 현재 쿼리 연결만 종료합니다. 다른 명령은 서로 다른 세션을 사용할 수 있으므로, 명령 간의 트랜잭션이나 세션 변수에 의존해서는 안 됩니다.
SQLcl의 시간 초과는 자식 프로세스를 종료시킵니다. Oracle 네이티브 드라이버가 OCI(Oracle Call Interface) 요청을 취소할 때는, 오직 Oracle Client ≥ 18.1에서만 남은 기한에 따라 왕복 시간 초과를 설정합니다. Client 11.2/12.1/12.2는 외부 응답 기한 및 OCI 취소 메커니즘을 유지합니다. 연결이 설정되는 동안에는 OCI 연결 핸들(connection handle)이 없으므로, 이 취소 인터페이스로는 로그인을 중단시킬 수 없습니다. 다른 드라이버들은 클라이언트 응답 기한을 제공하지만, 서버 측 명령이 즉시 중지됨을 보장하지는 않습니다. 시간 초과는 쓰기 작업이 실행되지 않았음을 의미하지 않으며, 재시도하기 전에 데이터베이스 상태를 확인해야 합니다.
daemon status의 busy, inFlight에는 실행 중이고 대기열에 있는 요청이 모두 포함됩니다. 유휴 회수는 활성 요청이 있는 연결을 제거하지 않습니다.

Oracle SQLcl

공식 링크: https://www.oracle.com/database/sqldeveloper/technologies/sqlcl/

Oracle은 기본적으로 SQLcl을 사용하며, 기본 의존성을 Oracle Instant Client에 두는 것을 방지하고 Oracle 11과 같은 구형 라이브러리에 더 적합합니다. oracleDriver를 구성하지 않거나 명시적으로 SQLcl로 구성할 수 있습니다:

{
  "type": "oracle",
  "url": "oracle://USER:[email protected]:1521/qftest201",
...
}

SQLcl 모드는 임시 스크립트 파일을 통해 연결 정보를 전달하여 비밀번호가 명령줄 인자 목록에 나타나는 것을 방지합니다. 실행 종료, 실패 또는 취소 후 스크립트를 삭제합니다. 보안 검사는 여전히 실행 전에 완료되며, 블랙리스트와 읽기 전용 모드가 모두 적용됩니다.

업데이트

npm install -g agent-database-cli@latest

제거 및 정리 (Uninstall and Cleanup)

npm uninstall -g agent-database-cli
npm cache clean --force
rm -rf ~/.agent-database-cli

라이선스

MIT

agent-database-cli

요약

핵심 포인트

agent-database-cli

개요 (简介)

설치 (安装)

환경 요구 사항

AI 원클릭 설치 (AI 一键安装)

수동 전역 설치 (手动全局安装)

설정 (Configuration)

권한 설정

읽기 전용 모드 (Read-Only Mode)

명령어 블랙리스트 (Command Blacklist)

실행 순서 (Execution Order)

일반적인 고위험 명령어

권장 설정 예시

편집 페이지 (Editor Page)

쿼리 시간 초과 및 연결 재사용 (Query Timeout and Connection Reuse)

Oracle SQLcl

업데이트

제거 및 정리 (Uninstall and Cleanup)

라이선스

관련 링크

댓글

agent-database-cli

개요 (简介)

설치 (安装)

환경 요구 사항

AI 원클릭 설치 (AI 一键安装)

수동 전역 설치 (手动全局安装)

설정 (Configuration)

권한 설정

읽기 전용 모드 (Read-Only Mode)

명령어 블랙리스트 (Command Blacklist)

실행 순서 (Execution Order)

일반적인 고위험 명령어

권장 설정 예시

편집 페이지 (Editor Page)

쿼리 시간 초과 및 연결 재사용 (Query Timeout and Connection Reuse)

Oracle SQLcl

업데이트

제거 및 정리 (Uninstall and Cleanup)

라이선스

관련 링크