@ecubelabs/mysql-mcp 1.1.0 → 2.0.0-next.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +245 -452
- package/dist/index.js +11 -11
- package/dist/src/config/index.js +265 -131
- package/dist/src/db/index.js +30 -13
- package/dist/src/db/permissions.js +4 -1
- package/dist/src/ssh/config.js +0 -135
- package/dist/src/ssh/known-hosts.js +1 -4
- package/dist/src/ssh/tunnel.js +26 -97
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
SSH bastion을 거쳐야만 닿을 수 있는 MySQL을 위한 읽기 전용 MCP 서버. 환경마다
|
|
4
4
|
이름 붙은 profile 하나씩을 둡니다.
|
|
5
5
|
|
|
6
|
-
Tunnel은 서버가 직접 엽니다.
|
|
7
|
-
|
|
6
|
+
Tunnel은 서버가 직접 엽니다. bastion과 DB 주소를 실행 인자로 넘기면 forwarding,
|
|
7
|
+
connection pool, teardown까지 알아서 처리합니다. `prod`로 시작하는 이름의 profile은
|
|
8
8
|
쓰기가 불가능하며, 이는 설정이 아니라 코드에서 결정됩니다.
|
|
9
9
|
|
|
10
10
|
## 제공하는 것
|
|
@@ -25,50 +25,42 @@ Tunnel은 서버가 직접 엽니다. 이미 쓰고 있는 `~/.ssh/config` alias
|
|
|
25
25
|
상한에 걸리면 실행 계획을 한 번 읽어, 플랜과 인덱스 목록과 선택지를 돌려줍니다.
|
|
26
26
|
판정은 서버가 하지 않고 모델이 합니다.
|
|
27
27
|
- **stdio에 안전한 로깅.** 모든 진단 출력이 stderr로 가므로
|
|
28
|
-
|
|
28
|
+
`--log`가 MCP 스트림을 망가뜨리는 일이 없습니다.
|
|
29
29
|
|
|
30
30
|
## 요구 사항
|
|
31
31
|
|
|
32
32
|
- Node.js 18.7 이상
|
|
33
|
-
- Bastion에 대한 SSH 접근 권한, 그리고 이미 동작하는 키(`ssh <
|
|
33
|
+
- Bastion에 대한 SSH 접근 권한, 그리고 이미 동작하는 키 파일(`ssh <user>@<bastion>`이 성공할 것)
|
|
34
34
|
- 대상 데이터베이스의 MySQL 사용자 계정
|
|
35
35
|
|
|
36
36
|
## 설치
|
|
37
37
|
|
|
38
|
-
### 1.
|
|
38
|
+
### 1. bastion에 한 번 접속하기
|
|
39
39
|
|
|
40
|
-
서버는
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
```sshconfig
|
|
44
|
-
Host ecubelabs2-stage-db
|
|
45
|
-
HostName <stage bastion 호스트명>
|
|
46
|
-
User dev
|
|
47
|
-
LocalForward 3307 <stage RDS reader 엔드포인트>:3306
|
|
48
|
-
Host ecubelabs2-prod-db
|
|
49
|
-
HostName <prod bastion 호스트명>
|
|
50
|
-
User dev
|
|
51
|
-
LocalForward 3308 <prod RDS reader 엔드포인트>:3306
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
`HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`,
|
|
55
|
-
그리고 첫 번째 `LocalForward`를 읽어갑니다. 다음 단계로 넘어가기 전에 alias로 한 번
|
|
56
|
-
접속하세요:
|
|
40
|
+
서버는 `~/.ssh/config`를 읽지 않습니다. bastion과 DB 주소는 다음 단계에서 실행 인자로
|
|
41
|
+
넘깁니다. 그 전에 같은 bastion에 `ssh`로 한 번 접속하세요:
|
|
57
42
|
|
|
58
43
|
```bash
|
|
59
|
-
ssh
|
|
60
|
-
ssh
|
|
44
|
+
ssh dev@<stage bastion 호스트명> "echo ok"
|
|
45
|
+
ssh dev@<prod bastion 호스트명> "echo ok"
|
|
61
46
|
```
|
|
62
47
|
|
|
63
|
-
-
|
|
48
|
+
- 키가 동작하는지 확인합니다.
|
|
64
49
|
- bastion 호스트 키를 `~/.ssh/known_hosts`에 기록합니다. 서버는 기록된 키만 받고
|
|
65
|
-
처음 보는 키는 거부합니다.
|
|
50
|
+
처음 보는 키는 거부합니다. 22번이 아닌 포트는 `ssh -p <port> ...`로 접속해야 서버가
|
|
51
|
+
찾는 이름으로 기록됩니다.
|
|
52
|
+
|
|
53
|
+
서버가 `~/.ssh`에서 쓰는 것은 아래뿐입니다.
|
|
54
|
+
|
|
55
|
+
- `~/.ssh/known_hosts`: 위 접속이 기록한 bastion 호스트 키.
|
|
56
|
+
- SSH 키: 기본값은 `~/.ssh/id_rsa`입니다. 다른 키를 쓰면 `--ssh-private-key-path`로 넘깁니다.
|
|
57
|
+
- ssh-agent는 쓰지 않습니다. 키 파일이 있어야 합니다. 암호화된 키라면
|
|
58
|
+
`MYSQL_SSH_PASSPHRASE`를 env로 넘깁니다.
|
|
66
59
|
|
|
67
60
|
### 2. MCP 클라이언트에 등록하기
|
|
68
61
|
|
|
69
62
|
- `--profile`은 빼지 마세요. prod 쓰기 금지를 이 값이 정합니다.
|
|
70
|
-
-
|
|
71
|
-
- 나머지 변수는 [환경 변수](#환경-변수) 절에 있습니다.
|
|
63
|
+
- credential은 [환경 변수](#환경-변수)로, 나머지 설정은 모두 [실행 인자](#실행-인자)로 넘깁니다.
|
|
72
64
|
|
|
73
65
|
#### Claude Code
|
|
74
66
|
|
|
@@ -76,12 +68,16 @@ ssh ecubelabs2-prod-db "echo ok"
|
|
|
76
68
|
claude mcp add mysql-stage -s user \
|
|
77
69
|
-e MYSQL_USER=<user> \
|
|
78
70
|
-e MYSQL_PASS=<password> \
|
|
79
|
-
-- npx -y @ecubelabs/mysql-mcp --profile stage
|
|
71
|
+
-- npx -y @ecubelabs/mysql-mcp --profile stage \
|
|
72
|
+
--ssh-host <stage bastion 호스트명> --ssh-user dev \
|
|
73
|
+
--host <stage RDS reader 엔드포인트> --port 3306
|
|
80
74
|
|
|
81
75
|
claude mcp add mysql-prod -s user \
|
|
82
76
|
-e MYSQL_USER=<user> \
|
|
83
77
|
-e MYSQL_PASS=<password> \
|
|
84
|
-
-- npx -y @ecubelabs/mysql-mcp --profile prod
|
|
78
|
+
-- npx -y @ecubelabs/mysql-mcp --profile prod \
|
|
79
|
+
--ssh-host <prod bastion 호스트명> --ssh-user dev \
|
|
80
|
+
--host <prod RDS reader 엔드포인트> --port 3306
|
|
85
81
|
```
|
|
86
82
|
|
|
87
83
|
#### Codex
|
|
@@ -90,12 +86,16 @@ claude mcp add mysql-prod -s user \
|
|
|
90
86
|
codex mcp add mysql-stage \
|
|
91
87
|
--env MYSQL_USER=<user> \
|
|
92
88
|
--env MYSQL_PASS=<password> \
|
|
93
|
-
-- npx -y @ecubelabs/mysql-mcp --profile stage
|
|
89
|
+
-- npx -y @ecubelabs/mysql-mcp --profile stage \
|
|
90
|
+
--ssh-host <stage bastion 호스트명> --ssh-user dev \
|
|
91
|
+
--host <stage RDS reader 엔드포인트> --port 3306
|
|
94
92
|
|
|
95
93
|
codex mcp add mysql-prod \
|
|
96
94
|
--env MYSQL_USER=<user> \
|
|
97
95
|
--env MYSQL_PASS=<password> \
|
|
98
|
-
-- npx -y @ecubelabs/mysql-mcp --profile prod
|
|
96
|
+
-- npx -y @ecubelabs/mysql-mcp --profile prod \
|
|
97
|
+
--ssh-host <prod bastion 호스트명> --ssh-user dev \
|
|
98
|
+
--host <prod RDS reader 엔드포인트> --port 3306
|
|
99
99
|
```
|
|
100
100
|
|
|
101
101
|
### 3. table과 문서 연결하기 (선택)
|
|
@@ -148,10 +148,8 @@ prod 응답의 banner:
|
|
|
148
148
|
[profile: PROD | READ-ONLY (enforced) | database: multi-db | code: Ecube-Labs/haulla@main | ssh tunnel: dev@<prod bastion 호스트명> -> <prod RDS reader 엔드포인트>:3306]
|
|
149
149
|
```
|
|
150
150
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
- `mysql_query` 툴 설명에도 환경 이름이 들어갑니다. 모델이 툴을 고르기 전에 읽는
|
|
154
|
-
것이 바로 툴 설명이기 때문입니다.
|
|
151
|
+
쓰기를 열면 `read-only` 자리에 열린 쓰기가 적힙니다. 예: `--schema-update haulla:true`이면
|
|
152
|
+
`writes: UPDATE (haulla only)`입니다.
|
|
155
153
|
|
|
156
154
|
## 모델에게 무엇이 어디 있는지 알려주기
|
|
157
155
|
|
|
@@ -165,8 +163,7 @@ prod 응답의 banner:
|
|
|
165
163
|
|
|
166
164
|
- 사용자가 확인한 값을
|
|
167
165
|
`mysql_catalog {action:"owner", target:"haulla", repo:"Ecube-Labs/haulla", app:"core-api"}`로
|
|
168
|
-
catalog에 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지
|
|
169
|
-
([이유](#schema-owner를-추론하지-않는-이유)).
|
|
166
|
+
catalog에 기록합니다. 서버는 문서 경로, 이름, 앱 설정으로 추측하지 않습니다.
|
|
170
167
|
- 모델이 묻는 자리는 `link` 응답 하나입니다. 연결한 table의 schema에 owner가 없으면
|
|
171
168
|
`guidance`가 묻게 합니다. 이미 기록된 schema는 묻지 않습니다.
|
|
172
169
|
|
|
@@ -183,12 +180,6 @@ prod 응답의 banner:
|
|
|
183
180
|
mysql-prod의 haulla schema는 Ecube-Labs/haulla의 core-api 것이야. owner로 기록해줘
|
|
184
181
|
```
|
|
185
182
|
|
|
186
|
-
- 기록된 owner는 `map`의 schema마다, `search` 결과의 table마다, `describe`,
|
|
187
|
-
`mysql://schemas`에 `{repo, app}`으로 나옵니다. 기록 전에는 그 키가 없습니다.
|
|
188
|
-
- Query 응답, banner, 툴 설명은 owner를 싣지도 묻지도 않습니다.
|
|
189
|
-
- 예전 버전이 env에서 옮겨 적은 앱 이름은 저장소가 없어 버립니다. 다음 `link` 때 다시
|
|
190
|
-
묻습니다.
|
|
191
|
-
|
|
192
183
|
### 코드 branch — 데이터가 어느 branch에 대응하는가
|
|
193
184
|
|
|
194
185
|
행과 코드를 대조하는 모델에게는 올바른 checkout이 필요한데, 틀렸을 때 조용히
|
|
@@ -201,34 +192,6 @@ migration이 빠진 것처럼 보이기 때문입니다.
|
|
|
201
192
|
`mysql_catalog {action:"branch", repo:"Ecube-Labs/haulla", branch:"develop"}`로
|
|
202
193
|
catalog에 기록합니다. 서버는 env나 profile로 정하지 않고, 세션이 어느 저장소에
|
|
203
194
|
있는지도 알아내지 않습니다.
|
|
204
|
-
- 기록된 branch는 아래에 나타납니다. 기록 전에는 어디에도 나오지 않습니다.
|
|
205
|
-
- `mysql_query` 툴 설명의 `CODE REVISION`, `mysql_catalog` 툴 설명의
|
|
206
|
-
`Recorded code branches:`, 응답 banner의 `code: Ecube-Labs/haulla@develop`.
|
|
207
|
-
셋 다 `owner/name@branch`로 쓰고, 여럿이면 쉼표로 잇습니다.
|
|
208
|
-
- `mysql://schemas`의 `codeBranches`(`owner/name` → branch)
|
|
209
|
-
- `describe`의 문서 읽기 명령
|
|
210
|
-
- `mysql_query` 툴 설명은 서버 시작 때 한 번 만들어집니다. 세션 중에 바꾸면 banner와
|
|
211
|
-
`branch` 응답이 새 값을 알립니다. `mysql_catalog` 툴 설명은 툴 목록을 받을 때마다
|
|
212
|
-
다시 만듭니다.
|
|
213
|
-
- Catalog가 꺼진 profile(`MYSQL_CATALOG_ENABLED=false`)은 branch를 기록할 곳이 없어
|
|
214
|
-
표시하지 않습니다.
|
|
215
|
-
- 예전 버전이 DB 하나에 기록한 branch(`codeBranch`)는 어느 저장소의 것인지 몰라
|
|
216
|
-
버립니다. 필요한 곳에서 다시 묻습니다.
|
|
217
|
-
- Branch는 실제로 쓰이는 곳에서만 묻습니다. profile별 제안은 질문 형태이고 저장되지
|
|
218
|
-
않습니다.
|
|
219
|
-
- `link`: 연결한 저장소 가운데 branch가 없는 저장소마다 `guidance`가 묻게 합니다.
|
|
220
|
-
- `describe`: 연결된 문서의 저장소에 branch가 없으면, 그 문서를 읽어야 할 때만
|
|
221
|
-
물으라고 안내합니다.
|
|
222
|
-
- `mysql_catalog` 툴 설명: 세션의 저장소에 branch가 없고 문서를 연결하거나 코드와
|
|
223
|
-
데이터를 대조할 때 먼저 물으라고 지시합니다. 세션이 어느 저장소인지는 모델이
|
|
224
|
-
판단합니다.
|
|
225
|
-
- Query 응답, banner, 연결 전인 table의 `describe`는 묻지 않습니다.
|
|
226
|
-
|
|
227
|
-
| Profile | 제안하는 branch |
|
|
228
|
-
| --------------------------------------- | --------------- |
|
|
229
|
-
| `stage` / `staging` / `dev` / `develop` | `develop` |
|
|
230
|
-
| `prod` / `production` | `main` |
|
|
231
|
-
| 그 밖 | 제안 없이 물음 |
|
|
232
195
|
|
|
233
196
|
## Schema catalog
|
|
234
197
|
|
|
@@ -239,7 +202,7 @@ catalog에 기록합니다. `information_schema`, `mysql`, `performance_schema`,
|
|
|
239
202
|
### 수집 시점
|
|
240
203
|
|
|
241
204
|
- **schema 목록과 table 이름·comment·예상 row 수**는 시작할 때 갱신합니다. catalog가
|
|
242
|
-
비어 있거나 `
|
|
205
|
+
비어 있거나 `--catalog-ttl`(기본 24시간)가 지났을 때만입니다. DB에서
|
|
243
206
|
사라진 schema는 그 owner와 함께 지웁니다.
|
|
244
207
|
- **column, primary key, index, foreign key**는 table이 실제 SQL에 처음 등장한 뒤
|
|
245
208
|
비동기로 수집합니다. 이 작업은 `mysql_query`의 실행 시간에 포함되지 않습니다.
|
|
@@ -266,36 +229,15 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
|
|
|
266
229
|
|
|
267
230
|
- `link`: 모델이 찾은 table↔문서 연결을 배열로 한꺼번에 저장합니다. 하나라도 틀리면
|
|
268
231
|
아무것도 저장하지 않습니다.
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
`owner/name`으로 저장하고, github.com이 아닌 host는 거절합니다. 모델은
|
|
273
|
-
`git remote get-url origin`으로 얻습니다.
|
|
274
|
-
- `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다. 툴 설명과
|
|
275
|
-
query 뒤 안내는 문서 저장소 안의 세션에서 찾아봤을 때만 기록하라고 지시합니다. 저장소
|
|
276
|
-
밖의 세션이 못 찾았다고 남긴 "문서 없음"은 이후 모든 세션이 그 table의 문서를 찾지
|
|
277
|
-
않게 만듭니다. 서버는 세션의 저장소를 모르므로 이 조건은 모델이 판단합니다.
|
|
278
|
-
- `branch`: 사용자가 확인한 저장소의 코드 branch를 기록합니다. `repo`와 `branch`가
|
|
279
|
-
모두 필요합니다. 처음 기록과 변경을 함께 받고, 응답이 저장소와 함께 무엇을
|
|
280
|
-
기록했는지 또는 `이전 → 새` 값을 알립니다.
|
|
281
|
-
- `repo`: `link`와 같은 형태를 받아 `owner/name`으로 저장합니다.
|
|
282
|
-
- `branch`: `origin/` 접두어는 떼고 저장합니다. git으로 확인하지 않는 대신
|
|
283
|
-
`git check-ref-format --branch`에 준하는 형식만 받습니다.
|
|
284
|
-
공백·제어문자·`~^:?*[\`·`..`·`@{`는 거절하고, 100자까지입니다.
|
|
285
|
-
- 둘 중 하나라도 틀리면 아무것도 기록하지 않습니다.
|
|
286
|
-
- `owner`: 사용자가 확인한 schema의 저장소와 앱을 기록합니다. `target`(schema 이름),
|
|
287
|
-
`repo`, `app`이 모두 필요합니다. 처음 기록과 변경을 함께 받고, 응답이 무엇을
|
|
288
|
-
기록했는지 또는 `이전 → 새` 값을 알립니다.
|
|
289
|
-
- `target`: 수집된 schema만 받습니다. 대소문자는 가리지 않고 DB의 철자로 저장합니다.
|
|
290
|
-
- `repo`: `link`와 같은 형태를 받아 `owner/name`으로 저장합니다.
|
|
291
|
-
- `app`: 그 저장소 안의 앱 이름. 빈 값·공백·제어문자는 거절하고, 100자까지입니다.
|
|
292
|
-
- 셋 중 하나라도 틀리면 아무것도 기록하지 않습니다.
|
|
232
|
+
- `unlink`: 연결을 지우거나 해당 table에 연결할 문서가 없음을 기록합니다.
|
|
233
|
+
- `branch`: 사용자가 확인한 저장소의 코드 branch를 기록합니다.
|
|
234
|
+
- `owner`: 사용자가 확인한 schema의 저장소와 앱을 기록합니다.
|
|
293
235
|
|
|
294
236
|
**기록 관리**
|
|
295
237
|
|
|
296
238
|
- `note`: `target` table에 memo 또는 alias 하나를 저장합니다. 둘 중 하나만 보냅니다.
|
|
297
|
-
Table당 memo 50개, alias 20개까지이며 한도에 닿으면 저장을 거절합니다.
|
|
298
|
-
|
|
239
|
+
Table당 memo 50개, alias 20개까지이며 한도에 닿으면 저장을 거절합니다. 정리는
|
|
240
|
+
`forget`으로 합니다.
|
|
299
241
|
- `forget`: `target` table의 `notes`, `aliases`, `usage`, `joins`, `metadata` 중 한
|
|
300
242
|
범위를 지웁니다. `metadata`는 다음 `describe` 또는 정상 query 뒤에 다시 수집됩니다.
|
|
301
243
|
문서 판단은 지우지 않으며, 그 작업에는 `unlink`를 사용합니다.
|
|
@@ -313,34 +255,19 @@ column·index·foreign key가 **추가**되면 오류가 나지 않으므로, ca
|
|
|
313
255
|
문서를 찾고 읽는 것은 모델이 세션의 저장소에서 합니다.
|
|
314
256
|
- 서버가 저장하는 것은 table별 문서 경로(저장소 기준 상대 경로), GitHub 저장소,
|
|
315
257
|
"문서 없음" 기록뿐입니다. 파일이 있는지, 옮겨졌는지는 확인하지 않습니다.
|
|
316
|
-
- `describe`의 `docs`는 `path`, `repo`, `branch`(그 저장소에 기록된 branch),
|
|
317
|
-
`command`, `remoteCommand`, `guidance`입니다.
|
|
318
|
-
- 두 명령 모두 working tree가 아니라 그 branch를 읽습니다. checkout된 branch가 이
|
|
319
|
-
DB와 다를 수 있어서입니다. 그 저장소에 branch가 기록되지 않았으면 두 명령은
|
|
320
|
-
`null`이고, 문서를 읽어야 할 때만 물어 기록하라는 안내가 붙습니다.
|
|
321
|
-
- `remoteCommand`는 경로를 세그먼트별로 URL 인코딩하므로 한글 경로도 읽습니다.
|
|
322
|
-
- 문서 판단이 없는 table을 읽으면 query 응답에 연결을 유도하는 안내가 한 번 붙습니다.
|
|
323
|
-
`link`나 `unlink`로 판단을 남기면 그 table에는 더 붙지 않습니다.
|
|
324
258
|
|
|
325
259
|
### 사용 기록과 hot table
|
|
326
260
|
|
|
327
|
-
Query 뒤에는 참조한 table의 호출 횟수와 최근 시각을 기록합니다.
|
|
328
|
-
|
|
261
|
+
Query 뒤에는 참조한 table의 호출 횟수와 최근 시각을 기록합니다. 사용 기록은 catalog
|
|
262
|
+
파일에 남아 다음 세션으로 이어집니다.
|
|
329
263
|
|
|
330
|
-
Hot table 순위는 **성공한 query
|
|
331
|
-
|
|
332
|
-
않습니다. 이 순위가 두 곳에 쓰입니다:
|
|
264
|
+
Hot table 순위는 **성공한 query 횟수**로 정하고 최근 시각으로 동률을 정합니다. 이
|
|
265
|
+
순위가 두 곳에 쓰입니다:
|
|
333
266
|
|
|
334
267
|
- **`map`**: schema마다 상위 10개를 보여줍니다. 관측이 없는 table은 예상 row 수로
|
|
335
268
|
이어 붙입니다.
|
|
336
|
-
- **`mysql_query` 도구 설명**:
|
|
337
|
-
table
|
|
338
|
-
빈자리를 채우면 가장 큰 event·log table이 열 칸을 차지해서, 모델을 시작하면 안
|
|
339
|
-
되는 곳으로 밀기 때문입니다.
|
|
340
|
-
|
|
341
|
-
사용 기록은 catalog 파일에 남아 다음 세션으로 이어집니다. 세션에서 첫 query가
|
|
342
|
-
성공하면 서버가 `tools/list_changed` 알림을 한 번 보내, 클라이언트가 갱신된 툴
|
|
343
|
-
설명을 다시 읽게 합니다.
|
|
269
|
+
- **`mysql_query` 도구 설명**: 한 번이라도 읽힌 table 중 상위 10개를 넣습니다. 읽힌
|
|
270
|
+
table이 없으면 목록을 넣지 않습니다.
|
|
344
271
|
|
|
345
272
|
### 관측한 join
|
|
346
273
|
|
|
@@ -349,8 +276,6 @@ Hot table 순위는 **성공한 query 횟수**를 기준으로 정하고 최근
|
|
|
349
276
|
- `describe`의 `observedJoins`에서 해당 table과 연결된 경로를 자주 관측한 순서로
|
|
350
277
|
20개까지 확인할 수 있습니다. 이는 DB의 foreign key와 별개인 관측 사실입니다.
|
|
351
278
|
- 간선은 500개까지 유지하고, 넘으면 가장 오래 관측되지 않은 것부터 버립니다.
|
|
352
|
-
횟수가 아니라 시각을 기준으로 버리는 이유는, 드문 간선을 먼저 버리면 나중에
|
|
353
|
-
발견한 join 경로가 한도를 넘어 들어올 수 없게 되기 때문입니다.
|
|
354
279
|
|
|
355
280
|
### 저장 위치와 저장하지 않는 것
|
|
356
281
|
|
|
@@ -360,7 +285,7 @@ Catalog는 기본적으로
|
|
|
360
285
|
|
|
361
286
|
- Hash에는 DB 대상과 MySQL user가 들어가므로, 서로 다른 환경이 같은 catalog를
|
|
362
287
|
읽지 않습니다.
|
|
363
|
-
- 위치는
|
|
288
|
+
- 위치는 `--catalog-path`로 바꿀 수 있습니다.
|
|
364
289
|
- 디스크에 쓸 수 없으면 catalog만 꺼지고 query는 계속 됩니다.
|
|
365
290
|
|
|
366
291
|
Catalog에는 schema metadata와 사용 기록만 들어갑니다.
|
|
@@ -372,14 +297,13 @@ Catalog에는 schema metadata와 사용 기록만 들어갑니다.
|
|
|
372
297
|
|
|
373
298
|
### Catalog를 끄면
|
|
374
299
|
|
|
375
|
-
|
|
300
|
+
`--no-catalog`로 끄거나 디스크에 쓸 수 없으면 `mysql_catalog` 툴과
|
|
376
301
|
`mysql://schemas` resource가 사라지고, 나머지 resource는 `information_schema`를 직접
|
|
377
302
|
읽습니다. Owner와 code branch는 기록할 곳이 없어 표시하지 않습니다.
|
|
378
303
|
|
|
379
304
|
## Resource
|
|
380
305
|
|
|
381
|
-
|
|
382
|
-
위해 세 가지를 제공합니다.
|
|
306
|
+
Resource를 읽는 클라이언트를 위해 세 가지를 제공합니다.
|
|
383
307
|
|
|
384
308
|
| URI | 내용 |
|
|
385
309
|
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -387,154 +311,187 @@ Catalog에는 schema metadata와 사용 기록만 들어갑니다.
|
|
|
387
311
|
| `mysql://tables/<schema>/<table>` | 한 table의 구조. catalog가 켜져 있으면 `mysql_catalog describe`와 같은 내용이고, 실패하면 `information_schema`의 column 목록으로 물러납니다. catalog가 꺼져 있으면 `information_schema`의 column 목록을 바로 돌려줍니다. |
|
|
388
312
|
| `mysql://schemas` | 사용자가 기록한 schema owner. `profile`, `schemas`(owner가 기록된 schema만, schema → `{repo, app}`), 그리고 branch가 기록돼 있으면 저장소별 `codeBranches`를 담은 JSON입니다. catalog가 꺼져 있으면 목록에 오르지 않습니다. |
|
|
389
313
|
|
|
390
|
-
##
|
|
391
|
-
|
|
392
|
-
경로를 담는 변수는 절대 경로로 쓰세요. npx는 클라이언트가 열어 둔 프로젝트를
|
|
393
|
-
작업 디렉터리로 서버를 띄우므로, 상대 경로는 프로젝트마다 다른 곳을 가리킵니다.
|
|
394
|
-
|
|
395
|
-
### 실행 인자
|
|
396
|
-
|
|
397
|
-
profile과 alias는 환경 변수가 아니라 서버 실행 인자로 받습니다.
|
|
314
|
+
## 실행 인자
|
|
398
315
|
|
|
399
|
-
|
|
400
|
-
| --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
401
|
-
| `--profile <label>` | _(미설정)_ | 환경 label. `prod`로 시작하는 label은 읽기 전용을 강제합니다. |
|
|
402
|
-
| `--ssh-config-host <alias>` | _(미설정)_ | `HostName`, `User`, `Port`, `IdentityFile`, `UserKnownHostsFile`, `HostKeyAlias`, 첫 `LocalForward`를 읽어올 `~/.ssh/config`의 Host alias. |
|
|
316
|
+
credential만 [환경 변수](#환경-변수)로 받고, 나머지 설정은 모두 실행 인자로 받습니다.
|
|
403
317
|
|
|
404
318
|
- `--name value`와 `--name=value`를 모두 받습니다. 빈 값은 주지 않은 것으로 봅니다.
|
|
405
|
-
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
|
420
|
-
|
|
|
421
|
-
| `
|
|
422
|
-
|
|
|
423
|
-
|
|
|
424
|
-
|
|
|
425
|
-
|
|
|
426
|
-
|
|
|
427
|
-
| `
|
|
428
|
-
| `
|
|
429
|
-
|
|
430
|
-
-
|
|
431
|
-
|
|
432
|
-
-
|
|
433
|
-
|
|
434
|
-
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
|
441
|
-
|
|
|
442
|
-
|
|
|
443
|
-
|
|
|
444
|
-
|
|
|
445
|
-
| `MYSQL_SOCKET_PATH` | _(미설정)_ | Unix socket으로 직접 접속합니다. host/port 대신 쓰이며, tunnel을 열면 무시합니다. |
|
|
446
|
-
| `MYSQL_POOL_SIZE` | `10` | 동시에 열어 두는 커넥션 수. tunnel을 쓰면 SSH 세션 하나 위의 채널이 그만큼 생깁니다. |
|
|
447
|
-
| `MYSQL_QUEUE_LIMIT` | `100` | pool이 꽉 찼을 때 대기열에 쌓아 둘 요청 수. |
|
|
448
|
-
| `MYSQL_CONNECT_TIMEOUT` | `10000` | 접속 timeout(ms). |
|
|
449
|
-
| `MYSQL_BIG_NUMBER_STRINGS` | `false` | BIGINT/DECIMAL을 문자열로 반환합니다. schema가 snowflake ID를 쓴다면 켜세요. |
|
|
450
|
-
| `MYSQL_DATE_STRINGS` | `false` | 날짜를 `Date`가 아닌 문자열로 반환합니다. |
|
|
451
|
-
| `MYSQL_TIMEZONE` | _(미설정)_ | mysql2에 넘기는 timezone. 날짜 값을 해석하는 기준입니다. |
|
|
452
|
-
| `MYSQL_SSL` | `false` | MySQL로의 TLS(SSH tunnel과는 별개). 아래 네 변수는 이 값이 `true`일 때만 적용됩니다. |
|
|
453
|
-
| `MYSQL_SSL_REJECT_UNAUTHORIZED` | `false` | 서버 인증서를 검증합니다. |
|
|
454
|
-
| `MYSQL_SSL_CA` | _(미설정)_ | CA 인증서 PEM 경로. |
|
|
455
|
-
| `MYSQL_SSL_CERT` / `MYSQL_SSL_KEY` | _(미설정)_ | mTLS용 클라이언트 인증서와 개인 키 PEM 경로. |
|
|
456
|
-
| `MYSQL_MAX_TIMEOUT_SECONDS` | `30` | `timeout_seconds` 인자의 상한. 기본 상한 10초도 이 값 아래로 함께 내려갑니다. |
|
|
457
|
-
| `MYSQL_MAX_RESPONSE_ROWS` | `5000` | 한 응답에 담기는 최대 행 수. 쿼리가 고르는 행이 아니라 **돌려주는** 행입니다. |
|
|
458
|
-
| `MYSQL_CATALOG_TIMEOUT_SECONDS` | `60` | catalog와 resource가 `information_schema`를 읽을 때 걸리는 시간 상한. |
|
|
319
|
+
- 값이 `-`로 시작하면 `--name=value`로만 받습니다. 예: `--timezone=-05:00`.
|
|
320
|
+
|
|
321
|
+
아래 경우와 각 표에 적은 제약을 어기면 서버가 시작하지 않습니다.
|
|
322
|
+
|
|
323
|
+
- 모르는 인자, 값 없는 인자, 같은 인자를 두 번 준 경우. 첫 위반 하나만 알립니다.
|
|
324
|
+
- 값과 조합의 위반. 아래 숫자 범위와 각 표의 제약이 해당하며, 한 줄에 모두 알립니다.
|
|
325
|
+
- 숫자 인자가 정수가 아니거나 범위 밖인 경우. 포트는 1–65535, 나머지는 1 이상입니다.
|
|
326
|
+
`--max-rows 0`과 `--catalog-ttl 1.5`도 거부합니다.
|
|
327
|
+
|
|
328
|
+
### 접속
|
|
329
|
+
|
|
330
|
+
| 인자 | 기본값 | 의미 |
|
|
331
|
+
| ---------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------- |
|
|
332
|
+
| `--profile <label>` | _(미설정)_ | 환경 label. `prod`로 시작하는 label은 읽기 전용을 강제합니다. |
|
|
333
|
+
| `--ssh-host <host>` | _(미설정)_ | bastion 호스트명. 있으면 MySQL에 접속하기 전에 tunnel을 엽니다. |
|
|
334
|
+
| `--ssh-user <user>` | — | bastion 사용자. `--ssh-host`를 주면 필수이고, `--ssh-host` 없이는 줄 수 없습니다. |
|
|
335
|
+
| `--ssh-port <port>` | `22` | bastion SSH 포트. `--ssh-host` 없이는 줄 수 없습니다. |
|
|
336
|
+
| `--ssh-private-key-path <path>` | `~/.ssh/id_rsa` | bastion 인증에 쓰는 키. 절대 경로나 `~/`로 시작하는 경로입니다. `--ssh-host` 없이는 줄 수 없습니다. |
|
|
337
|
+
| `--host <host>` | — | 접속할 주소. tunnel을 쓸 때는 **bastion에서 바라본** 데이터베이스입니다. |
|
|
338
|
+
| `--port <port>` | — | 위 주소의 포트. |
|
|
339
|
+
| `--socket-path <path>` | _(미설정)_ | Unix socket 절대 경로로 직접 접속합니다. `--host`·`--port`·`--ssh-host`와 함께 줄 수 없습니다. |
|
|
340
|
+
| `--db <schema>` | _(미설정)_ | 기본 schema. 없으면 multi-DB 모드가 켜집니다. |
|
|
341
|
+
| `--ssl` | 꺼짐 | MySQL로의 TLS(SSH tunnel과는 별개). 아래 네 인자는 이 플래그가 있을 때만 적용됩니다. |
|
|
342
|
+
| `--ssl-reject-unauthorized` | 꺼짐 | 서버 인증서를 검증합니다. |
|
|
343
|
+
| `--ssl-ca <path>` | _(미설정)_ | CA 인증서 PEM 절대 경로. |
|
|
344
|
+
| `--ssl-cert <path>` / `--ssl-key <path>` | _(미설정)_ | mTLS용 클라이언트 인증서와 개인 키 PEM 절대 경로. |
|
|
345
|
+
| `--timezone <tz>` | _(미설정)_ | mysql2에 넘기는 timezone. 날짜 값을 해석하는 기준입니다. |
|
|
346
|
+
| `--date-strings` | 꺼짐 | 날짜를 `Date`가 아닌 문자열로 반환합니다. |
|
|
347
|
+
| `--big-number-strings` | 꺼짐 | BIGINT/DECIMAL을 문자열로 반환합니다. schema가 snowflake ID를 쓴다면 켜세요. |
|
|
348
|
+
| `--pool-size <n>` | `10` | 동시에 열어 두는 커넥션 수. tunnel을 쓰면 SSH 세션 하나 위의 채널이 그만큼 생깁니다. |
|
|
349
|
+
| `--queue-limit <n>` | `100` | pool이 꽉 찼을 때 대기열에 쌓아 둘 요청 수. `0`(무제한)은 받지 않습니다. |
|
|
350
|
+
| `--connect-timeout <ms>` | `10000` | 접속 timeout. 단위는 ms입니다. |
|
|
351
|
+
|
|
352
|
+
접속 방식은 셋입니다.
|
|
353
|
+
|
|
354
|
+
| 접속 | 인자 |
|
|
355
|
+
| ------------- | ---------------------------------------------------------------------------------------------------- |
|
|
356
|
+
| bastion 경유 | `--ssh-host`, `--ssh-user`, `--host`, `--port`가 필수. `--ssh-port`, `--ssh-private-key-path`는 선택 |
|
|
357
|
+
| TCP 직접 접속 | `--host`, `--port`가 필수 |
|
|
358
|
+
| Unix socket | `--socket-path` |
|
|
459
359
|
|
|
460
360
|
### 쓰기
|
|
461
361
|
|
|
462
|
-
모두 기본값은
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
|
466
|
-
|
|
|
467
|
-
| `
|
|
468
|
-
| `
|
|
469
|
-
| `
|
|
470
|
-
|
|
|
471
|
-
|
|
|
472
|
-
|
|
473
|
-
- schema별
|
|
474
|
-
|
|
475
|
-
-
|
|
476
|
-
|
|
362
|
+
모두 기본값은 꺼짐입니다. 쓰기 금지 profile에서는 무시합니다([읽기 전용 강제](#읽기-전용-강제)).
|
|
363
|
+
|
|
364
|
+
| 인자 | 의미 |
|
|
365
|
+
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
366
|
+
| `--allow-insert` | INSERT 허용. |
|
|
367
|
+
| `--allow-update` | UPDATE 허용. |
|
|
368
|
+
| `--allow-delete` | DELETE 허용. |
|
|
369
|
+
| `--allow-ddl` | CREATE/ALTER/DROP/TRUNCATE/RENAME 허용. |
|
|
370
|
+
| `--schema-insert <db1:true,db2:false>` | schema별 INSERT override. 예: `--schema-insert haulla:true,tycoon:false`. 문장이 참조하는 schema가 모두 허용돼야 실행합니다. |
|
|
371
|
+
| `--schema-update <db1:true,db2:false>` | schema별 UPDATE override. 형식은 `--schema-insert`와 같습니다. |
|
|
372
|
+
| `--schema-delete <db1:true,db2:false>` | schema별 DELETE override. 형식은 `--schema-insert`와 같습니다. |
|
|
373
|
+
| `--schema-ddl <db1:true,db2:false>` | schema별 DDL override. 형식은 `--schema-insert`와 같습니다. |
|
|
374
|
+
|
|
375
|
+
- schema별 값이 `--allow-*`보다 우선합니다. 적은 schema는 그 값으로, 적지 않은 schema는
|
|
376
|
+
`--allow-*`로 판정합니다.
|
|
377
|
+
- 그래서 `--allow-update` 없이 `--schema-update haulla:true`만 주면 `haulla`에서만
|
|
378
|
+
UPDATE가 열립니다.
|
|
477
379
|
- `false`는 대소문자를 가리지 않고 맞춥니다. `haulla:false`면 `HAULLA`도 거부합니다.
|
|
478
|
-
`true`는 적은 철자와 같은 이름에만 적용되고, 철자가 다르면
|
|
479
|
-
|
|
480
|
-
|
|
380
|
+
`true`는 적은 철자와 같은 이름에만 적용되고, 철자가 다르면 `--allow-*`로 판정합니다.
|
|
381
|
+
|
|
382
|
+
### 실행 상한
|
|
383
|
+
|
|
384
|
+
| 인자 | 기본값 | 의미 |
|
|
385
|
+
| ------------------------ | ------ | ---------------------------------------------------------------------------------------- |
|
|
386
|
+
| `--max-timeout <초>` | `30` | `timeout_seconds` 인자의 상한. 단위는 초. 기본 상한 10초도 이 값 아래로 함께 내려갑니다. |
|
|
387
|
+
| `--max-rows <n>` | `5000` | 한 응답에 담기는 최대 행 수. 쿼리가 고르는 행이 아니라 **돌려주는** 행입니다. |
|
|
388
|
+
| `--catalog-timeout <초>` | `60` | catalog와 resource가 `information_schema`를 읽을 때 걸리는 시간 상한. 단위는 초. |
|
|
389
|
+
|
|
390
|
+
### Catalog
|
|
391
|
+
|
|
392
|
+
| 인자 | 기본값 | 의미 |
|
|
393
|
+
| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------- |
|
|
394
|
+
| `--no-catalog` | 꺼짐(catalog 켜짐) | 로컬 schema catalog를 끕니다. `mysql_catalog` 툴과 `mysql://schemas`가 빠집니다. |
|
|
395
|
+
| `--catalog-path <dir>` | `~/.cache/mysql-mcp/catalog` | profile·대상·user별 JSON 파일을 둘 directory의 절대 경로입니다. |
|
|
396
|
+
| `--catalog-ttl <시간>` | `24` | DB metadata를 stale로 보는 시간. 단위는 시간이고 정수만 받습니다. |
|
|
481
397
|
|
|
482
398
|
### 진단
|
|
483
399
|
|
|
484
|
-
|
|
|
485
|
-
|
|
|
486
|
-
| `
|
|
487
|
-
| `
|
|
400
|
+
| 인자 | 기본값 | 의미 |
|
|
401
|
+
| ----------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
402
|
+
| `--log` | 꺼짐 | 진단 출력을 stderr로. stdout을 쓰지 않으므로 MCP 스트림을 깨지 않습니다. 모델이 보낸 쿼리의 원문과 그 오류 메시지는 남기지 않습니다. |
|
|
403
|
+
| `--no-read-only-transactions` | 꺼짐 | 탈출구입니다. 읽기를 `START TRANSACTION READ ONLY` 대신 평범한 트랜잭션으로 엽니다. `START TRANSACTION READ ONLY`를 받지 못하는 proxy 뒤에 있을 때만 켜세요. 쓰기 차단은 쿼리 routing이 따로 하므로 이 값으로 쓰기가 열리지는 않지만, 마지막 한 겹이 사라집니다. |
|
|
404
|
+
|
|
405
|
+
### 인자로 옮긴 env
|
|
406
|
+
|
|
407
|
+
<!-- 다음 major 릴리스에서 이 절을 지운다. src/config/index.ts의 MIGRATED_ENV와 함께 지우며,
|
|
408
|
+
함께 지울 목록은 그 주석에 있다. -->
|
|
409
|
+
|
|
410
|
+
이전 버전은 아래 env를 읽었습니다. 지금은 값을 쓰지 않습니다. 남아 있으면 이름을 알리고
|
|
411
|
+
서버는 계속 시작합니다.
|
|
412
|
+
|
|
413
|
+
| env | 인자 |
|
|
414
|
+
| -------------------------------------- | ----------------------------- |
|
|
415
|
+
| `MYSQL_PROFILE` | `--profile` |
|
|
416
|
+
| `MYSQL_SSH_HOST` | `--ssh-host` |
|
|
417
|
+
| `MYSQL_SSH_USER` | `--ssh-user` |
|
|
418
|
+
| `MYSQL_SSH_PORT` | `--ssh-port` |
|
|
419
|
+
| `MYSQL_SSH_PRIVATE_KEY_PATH` | `--ssh-private-key-path` |
|
|
420
|
+
| `MYSQL_HOST` | `--host` |
|
|
421
|
+
| `MYSQL_PORT` | `--port` |
|
|
422
|
+
| `MYSQL_SOCKET_PATH` | `--socket-path` |
|
|
423
|
+
| `MYSQL_DB` | `--db` |
|
|
424
|
+
| `MYSQL_SSL` | `--ssl` |
|
|
425
|
+
| `MYSQL_SSL_REJECT_UNAUTHORIZED` | `--ssl-reject-unauthorized` |
|
|
426
|
+
| `MYSQL_SSL_CA` | `--ssl-ca` |
|
|
427
|
+
| `MYSQL_SSL_CERT` | `--ssl-cert` |
|
|
428
|
+
| `MYSQL_SSL_KEY` | `--ssl-key` |
|
|
429
|
+
| `MYSQL_TIMEZONE` | `--timezone` |
|
|
430
|
+
| `MYSQL_DATE_STRINGS` | `--date-strings` |
|
|
431
|
+
| `MYSQL_BIG_NUMBER_STRINGS` | `--big-number-strings` |
|
|
432
|
+
| `MYSQL_POOL_SIZE` | `--pool-size` |
|
|
433
|
+
| `MYSQL_QUEUE_LIMIT` | `--queue-limit` |
|
|
434
|
+
| `MYSQL_CONNECT_TIMEOUT` | `--connect-timeout` |
|
|
435
|
+
| `ALLOW_INSERT_OPERATION` | `--allow-insert` |
|
|
436
|
+
| `ALLOW_UPDATE_OPERATION` | `--allow-update` |
|
|
437
|
+
| `ALLOW_DELETE_OPERATION` | `--allow-delete` |
|
|
438
|
+
| `ALLOW_DDL_OPERATION` | `--allow-ddl` |
|
|
439
|
+
| `SCHEMA_INSERT_PERMISSIONS` | `--schema-insert` |
|
|
440
|
+
| `SCHEMA_UPDATE_PERMISSIONS` | `--schema-update` |
|
|
441
|
+
| `SCHEMA_DELETE_PERMISSIONS` | `--schema-delete` |
|
|
442
|
+
| `SCHEMA_DDL_PERMISSIONS` | `--schema-ddl` |
|
|
443
|
+
| `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS` | `--no-read-only-transactions` |
|
|
444
|
+
| `MYSQL_MAX_TIMEOUT_SECONDS` | `--max-timeout` |
|
|
445
|
+
| `MYSQL_MAX_RESPONSE_ROWS` | `--max-rows` |
|
|
446
|
+
| `MYSQL_CATALOG_TIMEOUT_SECONDS` | `--catalog-timeout` |
|
|
447
|
+
| `MYSQL_CATALOG_ENABLED` | `--no-catalog` |
|
|
448
|
+
| `MYSQL_CATALOG_PATH` | `--catalog-path` |
|
|
449
|
+
| `MYSQL_CATALOG_TTL_HOURS` | `--catalog-ttl` |
|
|
450
|
+
| `ENABLE_LOGGING` | `--log` |
|
|
488
451
|
|
|
489
|
-
##
|
|
452
|
+
## 환경 변수
|
|
490
453
|
|
|
491
|
-
|
|
492
|
-
두 가지를 합니다. `--profile`이 있으면 그 값으로, 없으면 deprecated `MYSQL_PROFILE`로 판정합니다.
|
|
454
|
+
credential만 env로 받습니다. 나머지 설정은 [실행 인자](#실행-인자)입니다.
|
|
493
455
|
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
456
|
+
| 변수 | 기본값 | 의미 |
|
|
457
|
+
| --------------------------- | ---------- | ------------------------------------- |
|
|
458
|
+
| `MYSQL_USER` / `MYSQL_PASS` | — | 데이터베이스 credentials. 필수입니다. |
|
|
459
|
+
| `MYSQL_SSH_PASSPHRASE` | _(미설정)_ | 암호화된 SSH 키일 때만 필요합니다. |
|
|
497
460
|
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
461
|
+
## 읽기 전용 강제
|
|
462
|
+
|
|
463
|
+
`--profile`이 `prod`로 시작하면(`prod`, `production`, `prod-ccn2`) 서버가 두 가지를
|
|
464
|
+
합니다. `MYSQL_PROFILE` env가 있고 `--profile`이 없을 때도 같습니다.
|
|
465
|
+
|
|
466
|
+
- `--allow-insert`, `--allow-update`, `--allow-delete`, `--allow-ddl`을 무시하고
|
|
467
|
+
모든 쓰기를 끕니다.
|
|
468
|
+
- `--schema-*` override를 비웁니다.
|
|
502
469
|
|
|
503
470
|
실질적인 귀결: 어떤 env 파일도, shell export도, 실행 인자도, MCP 클라이언트 설정도
|
|
504
|
-
prod profile이 쓰게 만들 수 없습니다. 시도하면 무시된
|
|
471
|
+
prod profile이 쓰게 만들 수 없습니다. 시도하면 무시된 인자를 stderr에 기록하고
|
|
505
472
|
읽기 전용으로 계속 동작합니다.
|
|
506
473
|
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
- `--profile`과 `MYSQL_PROFILE`이 다르면 표시·catalog·쓰기 판정 모두 `--profile`을
|
|
510
|
-
따르고, stderr에 알립니다.
|
|
511
|
-
|
|
512
|
-
다른 profile은 기본적으로 읽기 전용이지만 켤 수 있습니다. 그쪽의 `ALLOW_*`
|
|
513
|
-
flag는 평범한 설정이기 때문입니다.
|
|
474
|
+
다른 profile은 기본적으로 읽기 전용이지만 켤 수 있습니다. 그쪽의 `--allow-*`
|
|
475
|
+
인자는 평범한 설정이기 때문입니다.
|
|
514
476
|
|
|
515
477
|
어느 profile이든 실행하는 문장 종류는 허용 목록으로 정합니다. 읽기는 `SELECT`,
|
|
516
478
|
`SHOW`, `DESCRIBE`, `EXPLAIN`뿐이고, 쓰기는 `INSERT`, `UPDATE`, `DELETE`와
|
|
517
479
|
DDL(`CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`RENAME`)이 위 flag를 통과할 때만 실행합니다. 그
|
|
518
|
-
밖의
|
|
519
|
-
`
|
|
520
|
-
|
|
521
|
-
`schema.table`로 적습니다. `SELECT … INTO OUTFILE`·`INTO DUMPFILE`도 DB 서버에 파일을
|
|
522
|
-
쓰므로 거부합니다.
|
|
480
|
+
밖의 문장(`GRANT`, `SET`, `LOCK TABLES`, `USE` 등)은 모두 거부합니다. 다른 schema의
|
|
481
|
+
table은 `USE` 대신 `schema.table`로 적습니다. `SELECT … INTO OUTFILE`·`INTO DUMPFILE`도
|
|
482
|
+
거부합니다.
|
|
523
483
|
|
|
524
|
-
|
|
484
|
+
MySQL이 실행하는 주석도 거부합니다. 문자열 리터럴 안의 같은 글자도 거부합니다.
|
|
525
485
|
|
|
526
|
-
- `/*! … */` 실행
|
|
527
|
-
|
|
528
|
-
- `/*+ MAX_EXECUTION_TIME(…) */`와 `/*+ SET_VAR(…) */` hint. 아래 시간 상한을
|
|
529
|
-
덮어씁니다.
|
|
530
|
-
- 텍스트로 찾으므로 문자열 리터럴 안의 같은 글자도 거부합니다.
|
|
486
|
+
- `/*! … */` 실행 주석
|
|
487
|
+
- `/*+ MAX_EXECUTION_TIME(…) */`와 `/*+ SET_VAR(…) */` hint
|
|
531
488
|
|
|
532
489
|
schema별 쓰기 권한은 문장이 참조하는 schema 전부에 대해 판정합니다. 하나라도
|
|
533
490
|
막혀 있으면 거부합니다. 읽기만 하는 table의 schema도 포함하므로,
|
|
534
491
|
`INSERT INTO a.t SELECT … FROM b.u`는 `a`와 `b` 둘 다 INSERT가 허용돼야 합니다.
|
|
535
492
|
|
|
536
|
-
- schema를 적지 않은 table은 기본 schema(`
|
|
537
|
-
이름의 다른 schema table이 있어도 그렇습니다.
|
|
493
|
+
- schema를 적지 않은 table은 기본 schema(`--db`)로 봅니다. 같은 문장에 같은
|
|
494
|
+
이름의 다른 schema table이 있어도 그렇습니다.
|
|
538
495
|
- 예외는 다중 table DELETE의 대상 목록입니다. `DELETE o FROM a.t AS o …`의 `o`는
|
|
539
496
|
FROM이 붙인 이름이므로 `a`로 판정합니다.
|
|
540
497
|
- `RENAME TABLE a.t TO b.t`는 `a`와 `b` 둘 다 DDL이 허용돼야 합니다.
|
|
@@ -549,85 +506,27 @@ redaction이 아니라 그 앞단에 있습니다 — read-only 강제, profile
|
|
|
549
506
|
tunnel, 그리고 애초에 어떤 계정으로 접속하는지입니다. Column 이름 목록을 손으로
|
|
550
507
|
관리해서 얻는 masking 한 겹은 그 위에 얹을 값이 없었습니다.
|
|
551
508
|
|
|
552
|
-
## Schema owner를 추론하지 않는 이유
|
|
553
|
-
|
|
554
|
-
Owner는 사용자가 확인한 값만 기록합니다. 서버는 문서 경로, 이름 일치, 앱 설정의
|
|
555
|
-
`DB_NAME`, git 어느 것으로도 owner를 정하지 않습니다.
|
|
556
|
-
|
|
557
|
-
- 코드에는 schema 이름이 없습니다. haulla의 엔티티는 `@Entity()`만 쓰고, schema
|
|
558
|
-
이름은 env `DB_NAME`에서 옵니다.
|
|
559
|
-
- 저장소에 남은 단서는 로컬 값이라 환경과 다릅니다.
|
|
560
|
-
- core-api 공용 데이터: 로컬 `docker-compose.yml`은 `haulla`, stage는 `haulla-shared`
|
|
561
|
-
- hubspot-adapter: `.env.example`은 `hubspot-adapter`, stage는 `hubspot`
|
|
562
|
-
- 틀린 schema를 골라도 쿼리는 성공합니다. stage에는 여러 schema에 걸친 같은 이름
|
|
563
|
-
table이 12개 있고(`account`, `user`, `contract`, `deal`, `notification` 등), 숫자도
|
|
564
|
-
그럴듯합니다.
|
|
565
|
-
|
|
566
|
-
예전에는 app → schema map을 env로 받아 툴 설명에 실었습니다. 이 방식은 버렸습니다.
|
|
567
|
-
|
|
568
|
-
- 사용자마다 같은 map을 MCP 설정에 적어야 했습니다.
|
|
569
|
-
- Map에는 table 목록이 없어서, map이 있어도 모델은 table 위치를 찾으려고
|
|
570
|
-
`information_schema`를 조회했습니다.
|
|
571
|
-
- 그래서 owner는 같은 이름 table이 함께 드러나는 catalog 응답(`map`·`search`·
|
|
572
|
-
`describe`)에 둡니다. 묻는 자리는 모델이 table과 코드를 맞대 본 `link` 응답입니다.
|
|
573
|
-
|
|
574
509
|
## Tunnel이 동작하는 방식
|
|
575
510
|
|
|
576
|
-
Forwarding은 `ssh
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
1. **Teardown이 구조적으로 보장됩니다.** tunnel의 수명이 곧 프로세스의 수명입니다.
|
|
584
|
-
서버보다 오래 살아남을 자식이 없으므로, forwarding된 포트를 붙잡은 채 남아
|
|
585
|
-
있는 `ssh`라는 실패 양상 자체가 존재하지 않습니다.
|
|
586
|
-
2. **준비 완료 시점이 정확합니다.** "포트가 listening을 시작한 뒤에만 pool을
|
|
587
|
-
만든다"가 polling이 아니라 `server.listen()` callback입니다.
|
|
588
|
-
3. **남의 stderr를 떠안지 않습니다.** spawn된 `ssh`는 자기 경고를 뱉고, 어떤
|
|
589
|
-
bastion은 말이 많습니다. 여기서는 그것이 stdout에 닿을 수 없습니다.
|
|
590
|
-
|
|
591
|
-
알아둘 만한 동작:
|
|
592
|
-
|
|
593
|
-
- Listener는 `127.0.0.1`에만 bind 합니다. forwarding된 데이터베이스에 인증 없이
|
|
594
|
-
접근할 수 있게 해주므로, 네트워크에서 절대 닿을 수 있어서는 안 됩니다.
|
|
595
|
-
- **bastion 호스트 키는 OpenSSH `known_hosts`로 검증합니다.** `ssh2`는 스스로
|
|
596
|
-
`known_hosts`를 읽지 않고, 검증하지 않으면 어떤 키든 받습니다. 그러면 경로 위의
|
|
597
|
-
공격자가 bastion을 사칭해 DB 비밀번호를 받아 갈 수 있습니다.
|
|
598
|
-
- alias의 `UserKnownHostsFile`(없으면 `~/.ssh/known_hosts`, `~/.ssh/known_hosts2`)와
|
|
599
|
-
`/etc/ssh/ssh_known_hosts`를 읽습니다.
|
|
600
|
-
- 찾는 이름은 OpenSSH와 같습니다. alias에 `HostKeyAlias`가 있으면 포트를 붙이지 않고 그
|
|
601
|
-
이름 그대로 찾습니다. 없으면 호스트 이름을 소문자로 바꾸고, 22번이 아닌 포트는
|
|
511
|
+
Forwarding은 `ssh` 자식 프로세스 없이 서버 프로세스 안에서 합니다. pool은 SSH 세션 하나
|
|
512
|
+
위에서 서로 독립적인 MySQL connection 여러 개를 갖습니다.
|
|
513
|
+
|
|
514
|
+
- Listener는 `127.0.0.1`에만 bind 합니다.
|
|
515
|
+
- **bastion 호스트 키는 OpenSSH `known_hosts`로 검증합니다.**
|
|
516
|
+
- `~/.ssh/known_hosts`, `~/.ssh/known_hosts2`, `/etc/ssh/ssh_known_hosts`를 읽습니다.
|
|
517
|
+
- 찾는 이름은 OpenSSH와 같습니다. 호스트 이름을 소문자로 바꾸고, 22번이 아닌 포트는
|
|
602
518
|
`[host]:port`로 찾습니다.
|
|
603
519
|
- 기록된 키 종류로만 협상합니다. 처음 보는 호스트는 기록하지 않고 거부합니다. 지문을
|
|
604
520
|
확인할 수 있는 `ssh`로 한 번 접속해 기록하세요.
|
|
605
521
|
- `@cert-authority` 인증서 기반 호스트 키는 지원하지 않습니다.
|
|
606
|
-
- **각 서버는 자기 tunnel을 소유합니다.**
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
포트 번호에 신경 쓰지 않습니다.
|
|
522
|
+
- **각 서버는 자기 tunnel을 소유합니다.** 이미 떠 있는 forward를 빌려 쓰지 않습니다.
|
|
523
|
+
- **loopback 포트는 OS가 고릅니다.** pool은 실제로 열린 주소를 전달받으므로 포트 번호는
|
|
524
|
+
동작에 영향이 없습니다.
|
|
610
525
|
- 예기치 않게 끊기면 SSH transport를 지수 backoff(1초, 2초, 4초)로 최대 세 번
|
|
611
526
|
다시 세웁니다. 그 뒤에는 알 수 없는 `ECONNRESET` 대신 명시적인 메시지와
|
|
612
527
|
함께 쿼리가 실패합니다.
|
|
613
528
|
- Teardown은 `SIGINT`, `SIGTERM`, 그리고 클라이언트가 stdin을 닫을 때 일어납니다.
|
|
614
529
|
|
|
615
|
-
### 기본값에서 tunnel을 공유하지 않는 이유
|
|
616
|
-
|
|
617
|
-
이전 버전은 SSH 세션을 하나 더 여는 것을 피하려고, profile 포트에 이미 떠 있는
|
|
618
|
-
forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택이었습니다.
|
|
619
|
-
|
|
620
|
-
빌려 쓴 tunnel은 그것을 연 프로세스와 생사를 함께하는데, MCP 클라이언트는 서버를
|
|
621
|
-
쉴 새 없이 띄우고 내립니다 — `codex exec`는 호출이 끝날 때마다 자기 서버를
|
|
622
|
-
내립니다. 그래서 소유자가 먼저 종료되는 일이 흔하고, 그때마다 빌려 쓰던 쪽의
|
|
623
|
-
진행 중인 쿼리가 `PROTOCOL_CONNECTION_LOST`로 죽습니다. 겉보기에는 간헐적이고
|
|
624
|
-
재현되지 않는 툴 실패로 나타납니다.
|
|
625
|
-
|
|
626
|
-
서버마다 tunnel을 소유하면 SSH 세션 하나를 더 쓰는 대신 이 실패 양상이 통째로
|
|
627
|
-
사라집니다. `MYSQL_SSH_REUSE_EXISTING=true`는 forward가 외부에서 관리되고 모든
|
|
628
|
-
클라이언트보다 오래 사는 경우 — 직접 띄워 둔 장수 `ssh -L` 같은 경우 — 에만
|
|
629
|
-
켜세요.
|
|
630
|
-
|
|
631
530
|
## 실행 상한과 타임아웃 진단
|
|
632
531
|
|
|
633
532
|
읽기 쿼리 하나는 시간과 행 수 양쪽에 상한을 두고 돕니다. 상한에 걸려 취소된
|
|
@@ -635,73 +534,34 @@ forward가 있으면 거기에 붙었습니다. 결과적으로 잘못된 선택
|
|
|
635
534
|
|
|
636
535
|
### 시간 상한
|
|
637
536
|
|
|
638
|
-
모든 읽기는 10초 뒤에 취소됩니다.
|
|
639
|
-
잡았습니다.
|
|
537
|
+
모든 읽기는 10초 뒤에 취소됩니다.
|
|
640
538
|
|
|
641
539
|
- 호출마다 `mysql_query`의 `timeout_seconds` 인자로 올릴 수 있습니다. 상한은
|
|
642
|
-
`
|
|
643
|
-
- 범위 밖 값은 거부하지 않고
|
|
644
|
-
존재하는 이유는 폭주하는 쿼리를 끊는 것이지 값을 두고 실랑이하는 것이 아니기
|
|
645
|
-
때문입니다.
|
|
540
|
+
`--max-timeout`(기본 30초)입니다.
|
|
541
|
+
- 범위 밖 값은 거부하지 않고 잘라 맞춥니다. 100을 보내면 30이 됩니다.
|
|
646
542
|
- 상한 30초는 MCP 클라이언트의 기본 tool timeout보다 낮게 유지하세요. 클라이언트가
|
|
647
543
|
먼저 포기하면 모델에게는 보고서가 아니라 아무것도 남지 않습니다.
|
|
648
|
-
- SQL 안의 `/*+ MAX_EXECUTION_TIME(…) */`·`/*+ SET_VAR(…) */` hint는 거부합니다.
|
|
649
|
-
MySQL은 이 hint를 세션 상한보다 우선하므로, 허용하면 상한이 풀립니다.
|
|
650
544
|
|
|
651
545
|
### 행 수 상한
|
|
652
546
|
|
|
653
547
|
한 응답에는 최대 5000행이 담깁니다.
|
|
654
548
|
|
|
655
|
-
- 잘렸다면 경고가 별도 블록으로 붙습니다.
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
- 이름이 `RESULT`가 아니라 `RESPONSE`인 이유는 쿼리가 **고르는** 행이 아니라
|
|
661
|
-
**돌려주는** 행을 세기 때문입니다. `LIMIT n`과는 층위가 달라서, 자기 `LIMIT`을
|
|
662
|
-
더 크게 들고 온 쿼리도 5000행에서 함께 잘립니다.
|
|
549
|
+
- 잘렸다면 경고가 별도 블록으로 붙습니다.
|
|
550
|
+
- `--max-rows`로 올릴 수 있습니다. `mysql_query`에는 호출자가 상한을 푸는 인자가
|
|
551
|
+
없습니다.
|
|
552
|
+
- 쿼리가 **고르는** 행이 아니라 **돌려주는** 행을 셉니다. `LIMIT n`과는 층위가 달라서,
|
|
553
|
+
자기 `LIMIT`을 더 크게 들고 온 쿼리도 5000행에서 함께 잘립니다.
|
|
663
554
|
|
|
664
555
|
### 행 수 상한을 받지 않는 쿼리
|
|
665
556
|
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
-
|
|
669
|
-
예외가 아니어서, 모델이 직접 보낸 `SELECT ... FROM information_schema.columns`는
|
|
670
|
-
다른 쿼리와 똑같이 잘리고 경고가 붙습니다.
|
|
671
|
-
- 예외는 **서버가 스스로 보내는 쿼리** 하나뿐입니다. catalog가 table 목록과
|
|
672
|
-
column·index를 모을 때 쓰는 조회는 결과가 모델에게 가지 않고, 서버가 삼켜 catalog
|
|
673
|
-
파일에 구조 정보로 들어갑니다.
|
|
674
|
-
|
|
675
|
-
그래서 catalog 조회는 상한을 걷었다가 되돌립니다. `pool`을 읽기 경로와 공유하므로,
|
|
676
|
-
남아 있는 상한이 inventory 수집을 조용히 잘라낼 수 있기 때문입니다. 그렇게 만들어진
|
|
677
|
-
catalog는 고장 난 것이 아니라 조용히 틀린 것이 됩니다.
|
|
678
|
-
|
|
679
|
-
시간 상한은 catalog에도 걸되 별도 값(`MYSQL_CATALOG_TIMEOUT_SECONDS`, 기본 60)을
|
|
680
|
-
씁니다. Resource 조회도 같은 경로를 쓰므로 행 수 상한 없이 이 시간 상한만 받습니다.
|
|
681
|
-
|
|
682
|
-
### 무엇으로 거는가
|
|
683
|
-
|
|
684
|
-
두 상한 모두 MySQL이 원래 갖고 있는 세션 변수로 겁니다.
|
|
685
|
-
|
|
686
|
-
| 상한 | 세션 변수 |
|
|
687
|
-
| ----- | -------------------- |
|
|
688
|
-
| 시간 | `max_execution_time` |
|
|
689
|
-
| 행 수 | `sql_select_limit` |
|
|
690
|
-
|
|
691
|
-
이 둘은 MySQL 소유라 profile에 적는 값이 아닙니다. 여기 적어 두는 이유는
|
|
692
|
-
`SHOW VARIABLES`로 확인할 때 보이는 이름이 그것이기 때문입니다. profile에 적는 것은
|
|
693
|
-
`MYSQL_`로 시작하는 환경변수뿐입니다.
|
|
694
|
-
|
|
695
|
-
행 수는 상한보다 하나 크게 겁니다(기본값이면 5001). 5001번째 행이 도착했다는 것
|
|
696
|
-
자체가 잘렸다는 증거이기 때문입니다. 다만 자기 `LIMIT`을 들고 온 쿼리는
|
|
697
|
-
`sql_select_limit`을 무시하므로, 잘라내기는 응답을 조립할 때 한 번 더 적용됩니다.
|
|
557
|
+
- 모델에게 돌아가는 결과는 `information_schema`를 포함해 모두 잘립니다.
|
|
558
|
+
- 서버가 catalog를 모으려고 보내는 조회만 행 수 상한을 받지 않습니다. 대신
|
|
559
|
+
`--catalog-timeout`(기본 60초) 시간 상한을 받습니다. Resource 조회도 같습니다.
|
|
698
560
|
|
|
699
561
|
### 취소된 쿼리의 보고서
|
|
700
562
|
|
|
701
563
|
MySQL이 상한 초과로 문장을 취소하면(에러코드 `3024`) 서버는 **그때만** 같은
|
|
702
|
-
커넥션에서 `EXPLAIN FORMAT=JSON`을 한 번 실행합니다.
|
|
703
|
-
돌지 않습니다. 매 쿼리 앞에 EXPLAIN을 세우면 멀쩡한 쿼리마다 왕복 한 번(약
|
|
704
|
-
137ms)을 물리게 되는데, 비용은 그것을 유발한 쿼리가 내야 합니다.
|
|
564
|
+
커넥션에서 `EXPLAIN FORMAT=JSON`을 한 번 실행합니다.
|
|
705
565
|
|
|
706
566
|
**서버는 플랜을 판정하지 않습니다.** 사실만 돌려주고 판단은 모델이 합니다.
|
|
707
567
|
응답에 담기는 것은 다음 다섯 가지입니다.
|
|
@@ -722,53 +582,8 @@ EXPLAIN마저 실패하면 3~5번 없이 플랜을 읽지 못했다는 사실만
|
|
|
722
582
|
선택지 대신 금지 문구가 붙습니다.
|
|
723
583
|
3. 사용자에게 선택지를 제시하며 질문
|
|
724
584
|
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
보고서를 읽을 때 알아둘 것:
|
|
729
|
-
|
|
730
|
-
- **보고서는 리터럴을 가리지 않습니다.** EXPLAIN은 쿼리가 필터에 쓴 값을 플랜에
|
|
731
|
-
그대로 싣고, 3번의 조건과 5번의 원문에도 그대로 실려 돌아갑니다. 마스킹 계층은
|
|
732
|
-
PII redaction과 함께 걷어냈고, 그 근거는 [결과는 있는 그대로
|
|
733
|
-
반환합니다](#결과는-있는-그대로-반환합니다)와 같습니다 — 이 플랜을 받는 쪽은
|
|
734
|
-
그 리터럴을 방금 자기가 쓴 호출자뿐입니다.
|
|
735
|
-
- **인덱스 목록에서 없음은 사실이 아니라 무지로 보고합니다.** 카탈로그에 없는
|
|
736
|
-
테이블은 "인덱스가 없다"가 아니라 "여기서는 알 수 없다"로 적습니다. 둘을
|
|
737
|
-
뭉뚱그리면 모델이 사용자에게 잘못된 포기를 권하게 됩니다.
|
|
738
|
-
- **인덱스를 탔는지는 `key`가 아니라 `access_type`으로 판단합니다.** 보고서에도 이
|
|
739
|
-
읽는 법 한 줄이 함께 붙습니다. `ALL`과 `index`는 전부 읽는 것이고,
|
|
740
|
-
`const`·`eq_ref`·`ref`·`range`는 범위를 좁힌 것입니다. stage 실측:
|
|
741
|
-
`WHERE SUBSTRING(accountNumber,1,3)='ABC'`는 `key`에 인덱스 이름이 찍히면서도
|
|
742
|
-
9200행을 전부 읽습니다(`access_type: "index"`, `filtered: "100.00"`). `key`만
|
|
743
|
-
보면 정상으로 오판합니다.
|
|
744
|
-
- **보고서는 영어로 쓰입니다.** `executeReadOnlyQuery`의 다른 거부 메시지가 모두
|
|
745
|
-
영어라서, 그 옆에 한국어를 섞으면 톤이 깨집니다. 모델이 사용자에게 물을 때 세션
|
|
746
|
-
언어로 옮깁니다.
|
|
747
|
-
|
|
748
|
-
### 왕복 횟수
|
|
749
|
-
|
|
750
|
-
읽기 쿼리 한 건은 DB 왕복 3회로 끝납니다. tunnel 왕복이 1회당 약 137ms(stage
|
|
751
|
-
실측)이므로 이 세 번이 빠른 쿼리 비용의 대부분입니다.
|
|
752
|
-
|
|
753
|
-
1. `START TRANSACTION READ ONLY`
|
|
754
|
-
2. 쿼리
|
|
755
|
-
3. `ROLLBACK`
|
|
756
|
-
|
|
757
|
-
- 접근 모드를 세션이 아니라 트랜잭션 범위로 선언하므로 끝나고 원복할 것이
|
|
758
|
-
없습니다.
|
|
759
|
-
- `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS=true`를 켜면 1번이 평범한
|
|
760
|
-
`START TRANSACTION`으로 바뀝니다. 왕복 수는 같습니다.
|
|
761
|
-
- 세션 변수는 물리 커넥션이 처음 만들어질 때 한 번 겁니다. `pool`의 `connection`
|
|
762
|
-
이벤트는 커넥션이 호출자에게 넘어가기 전에 발생하고 명령은 큐 순서대로
|
|
763
|
-
실행되므로, 첫 쿼리가 도는 시점에는 이미 설정이 끝나 있습니다.
|
|
764
|
-
- 기본값이 아닌 `timeout_seconds`를 쓰면 그 쿼리와, 같은 커넥션에서 이어지는
|
|
765
|
-
기본값 쿼리에 왕복이 한 번씩 추가됩니다.
|
|
766
|
-
|
|
767
|
-
`ENABLE_LOGGING=true`로 확인할 수 있습니다:
|
|
768
|
-
|
|
769
|
-
```text
|
|
770
|
-
[info] Read query completed in 3 DB round trips
|
|
771
|
-
```
|
|
585
|
+
- 보고서는 리터럴을 가리지 않습니다. 쿼리가 필터에 쓴 값이 플랜에 그대로 실립니다.
|
|
586
|
+
- 보고서는 영어로 쓰입니다.
|
|
772
587
|
|
|
773
588
|
## 문제 해결
|
|
774
589
|
|
|
@@ -781,7 +596,8 @@ stderr로 보내므로, 시작할 때 뭔가를 출력하는 shell profile(`~/.z
|
|
|
781
596
|
|
|
782
597
|
```bash
|
|
783
598
|
MYSQL_USER=<user> MYSQL_PASS=<password> \
|
|
784
|
-
npx -y @ecubelabs/mysql-mcp --profile stage
|
|
599
|
+
npx -y @ecubelabs/mysql-mcp --profile stage \
|
|
600
|
+
--ssh-host <stage bastion 호스트명> --ssh-user dev --host <stage RDS reader 엔드포인트> --port 3306 < /dev/null | head
|
|
785
601
|
```
|
|
786
602
|
|
|
787
603
|
출력이 조금이라도 있다면 그것이 버그입니다.
|
|
@@ -790,8 +606,8 @@ npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-d
|
|
|
790
606
|
|
|
791
607
|
키 경로가 틀렸거나 읽을 수 없습니다. 오류 메시지에 서버가 고른 경로가 나옵니다.
|
|
792
608
|
|
|
793
|
-
- 서버는
|
|
794
|
-
|
|
609
|
+
- 서버는 `--ssh-private-key-path`를 쓰고, 없으면 `~/.ssh/id_rsa`를 씁니다.
|
|
610
|
+
`~/.ssh/config`의 `IdentityFile`과 ssh-agent는 보지 않습니다.
|
|
795
611
|
- 키는 `chmod 600`이어야 합니다.
|
|
796
612
|
- 암호화된 키라면 `MYSQL_SSH_PASSPHRASE`가 필요합니다.
|
|
797
613
|
|
|
@@ -800,7 +616,8 @@ npx -y @ecubelabs/mysql-mcp --profile stage --ssh-config-host ecubelabs2-stage-d
|
|
|
800
616
|
bastion 호스트 키가 `known_hosts`에 기록돼 있지 않습니다. 오류 메시지가 실행할 명령을
|
|
801
617
|
알려 줍니다.
|
|
802
618
|
|
|
803
|
-
-
|
|
619
|
+
- 오류 메시지의 `ssh` 명령으로 한 번 접속해 지문을 확인하고 기록하세요:
|
|
620
|
+
`ssh dev@<bastion 호스트명> "echo ok"`.
|
|
804
621
|
- 기록돼 있는지 확인하려면: `ssh-keygen -F <bastion 호스트명>`. 22번이 아닌 포트는
|
|
805
622
|
`ssh-keygen -F "[<bastion 호스트명>]:<port>"`입니다.
|
|
806
623
|
|
|
@@ -809,24 +626,10 @@ bastion 호스트 키가 `known_hosts`에 기록돼 있지 않습니다. 오류
|
|
|
809
626
|
bastion이 기록과 다른 키를 내밀었습니다. bastion을 다시 만들었거나, 누군가 접속을
|
|
810
627
|
가로채고 있습니다.
|
|
811
628
|
|
|
812
|
-
- 같은
|
|
629
|
+
- 같은 대상으로 `ssh`를 실행해 OpenSSH의 경고를 확인하세요.
|
|
813
630
|
- 키가 바뀐 것이 확실할 때만 `ssh-keygen -R <bastion 호스트명>`으로 옛 키를 지우고 다시
|
|
814
631
|
접속해 기록하세요.
|
|
815
632
|
|
|
816
|
-
### `local port N is taken` 로그
|
|
817
|
-
|
|
818
|
-
```text
|
|
819
|
-
[error] [ssh] local port N is taken; opening our own tunnel on an auto-assigned port instead.
|
|
820
|
-
```
|
|
821
|
-
|
|
822
|
-
`ENABLE_LOGGING=true`일 때만 보입니다. 오류가 아니라 정상 동작입니다.
|
|
823
|
-
|
|
824
|
-
- 서버는 남의 tunnel을 빌리지 않고 OS가 고른 포트에 자기 tunnel을 엽니다. pool은
|
|
825
|
-
접속할 주소를 전달받으므로 포트 번호가 바뀌어도 아무 영향이 없습니다.
|
|
826
|
-
- 선호 포트를 꼭 되찾아야 한다면 `lsof -nP -i :N`으로 점유한 쪽을 찾으세요.
|
|
827
|
-
- 포트가 이미 쓰이는 것 말고 다른 이유(예: 권한)로 listener를 열지 못하거나 자동
|
|
828
|
-
할당마저 실패하면 `Failed to open local tunnel listener`가 나옵니다.
|
|
829
|
-
|
|
830
633
|
### 한동안 잘 되다가 쿼리가 실패함
|
|
831
634
|
|
|
832
635
|
tunnel이 끊겼고 재연결이 포기한 것입니다. 오류 메시지에 bastion 이름이 담깁니다.
|
|
@@ -834,34 +637,24 @@ bastion에 닿을 수 있게 되면 서버를 재시작하세요.
|
|
|
834
637
|
|
|
835
638
|
### 서버가 즉시 종료됨
|
|
836
639
|
|
|
837
|
-
등록할 때와 같은 env와 인자로 직접 띄워 보세요. 시작 실패는
|
|
640
|
+
등록할 때와 같은 env와 인자로 직접 띄워 보세요. 시작 실패는 `--log`가 없어도
|
|
838
641
|
이유를 stderr에 찍습니다:
|
|
839
642
|
|
|
840
643
|
```bash
|
|
841
644
|
MYSQL_USER=<user> MYSQL_PASS=<password> \
|
|
842
|
-
npx -y @ecubelabs/mysql-mcp --profile stage
|
|
645
|
+
npx -y @ecubelabs/mysql-mcp --profile stage \
|
|
646
|
+
--ssh-host <stage bastion 호스트명> --ssh-user dev --host <stage RDS reader 엔드포인트> --port 3306
|
|
843
647
|
```
|
|
844
648
|
|
|
845
|
-
- `invalid server arguments`가 보이면 실행 인자가 틀렸습니다.
|
|
846
|
-
|
|
649
|
+
- `invalid server arguments`가 보이면 실행 인자가 틀렸습니다. 값과 조합의 위반은 모두
|
|
650
|
+
나열하고, 모르는 인자·값 없는 인자·중복 인자는 첫 위반 하나만 알립니다. 받는 인자와
|
|
651
|
+
조합 규칙은 [실행 인자](#실행-인자) 절에 있습니다.
|
|
847
652
|
|
|
848
653
|
### `PROTOCOL_CONNECTION_LOST` 또는 `Connection lost`로 쿼리가 실패함
|
|
849
654
|
|
|
850
655
|
쿼리 도중 tunnel이 사라졌습니다.
|
|
851
656
|
|
|
852
|
-
-
|
|
853
|
-
의심하세요.
|
|
854
|
-
- `MYSQL_SSH_REUSE_EXISTING=true`를 켜 뒀다면, 공유 forward를 소유한 프로세스가
|
|
855
|
-
종료된 것이 훨씬 유력한 원인입니다. flag를 다시 끄세요.
|
|
856
|
-
|
|
857
|
-
### `git push`가 "refusing to allow an OAuth App to create or update workflow"로 거부됨
|
|
858
|
-
|
|
859
|
-
`workflow` scope가 없는 토큰으로 HTTPS remote를 쓰고 있습니다. SSH remote를
|
|
860
|
-
쓰세요:
|
|
861
|
-
|
|
862
|
-
```bash
|
|
863
|
-
git remote set-url origin git@github.com:<owner>/<repo>.git
|
|
864
|
-
```
|
|
657
|
+
- 각 서버가 자기 tunnel을 소유하므로 bastion이나 네트워크를 의심하세요.
|
|
865
658
|
|
|
866
659
|
## 개발
|
|
867
660
|
|
|
@@ -893,8 +686,8 @@ yarn build
|
|
|
893
686
|
### 로컬 빌드 띄우기
|
|
894
687
|
|
|
895
688
|
env 파일은 개발에서만 씁니다. `bin/`의 wrapper가 패키지 디렉터리의
|
|
896
|
-
`.env.<profile>`을 shell로
|
|
897
|
-
이때도 파일을 읽지 않습니다.
|
|
689
|
+
`.env.<profile>`을 shell로 읽고, credential이 아닌 값은 대응하는 실행 인자로 바꿔 로컬
|
|
690
|
+
빌드를 띄웁니다([인자로 옮긴 env](#인자로-옮긴-env)). 서버 자신은 이때도 파일을 읽지 않습니다.
|
|
898
691
|
|
|
899
692
|
1. `.env.example`을 `.env.stage`로 복사해 채웁니다. `.env.*`는 gitignore 대상입니다.
|
|
900
693
|
2. `./bin/mcp-mysql-stage.sh`로 띄웁니다.
|
|
@@ -914,12 +707,12 @@ env 파일은 개발에서만 씁니다. `bin/`의 wrapper가 패키지 디렉
|
|
|
914
707
|
|
|
915
708
|
```text
|
|
916
709
|
index.ts MCP 서버, tool + resource handler, 종료 처리
|
|
917
|
-
src/config/
|
|
710
|
+
src/config/ 실행 인자·환경 변수 해석, profile 정책, mysql2 옵션
|
|
918
711
|
src/catalog/ 로컬 schema catalog: DB metadata 수집, 문서 연결, 사용 기록, 검색
|
|
919
712
|
src/db/ 쿼리 routing, 권한 검사, pool, 타임아웃 진단
|
|
920
|
-
src/ssh/config.ts
|
|
713
|
+
src/ssh/config.ts 키·known_hosts 경로의 ~ 펼치기
|
|
921
714
|
src/ssh/known-hosts.ts known_hosts 조회와 bastion 호스트 키 검증
|
|
922
|
-
src/ssh/tunnel.ts tunnel lifecycle: 열기,
|
|
715
|
+
src/ssh/tunnel.ts tunnel lifecycle: 열기, 재연결, 닫기
|
|
923
716
|
src/types/ 공유 타입
|
|
924
717
|
src/utils/ stderr 전용 로거, table resource URI
|
|
925
718
|
bin/ 개발용 profile wrapper (`.env.<profile>`로 로컬 빌드를 띄운다)
|