tablestudioapp/plugins

TableStudio를 통한 데이터베이스 작업

TableStudio는 사용자의 Mac에서 실행되는 데이터베이스 앱입니다. 이 앱의 MCP 도구는 자격 증명 없이 저장된 연결에 접근할 수 있으며, 원시 psql 세션에는 없는 안전 장치(실제 행에 대한 쓰기 작업의 정확한 드라이 런, 일회용 샌드박스 복사본, 사용자가 변경 사항을 승인하는 검토 받은 편지함)를 제공합니다. psql, mysql, sqlite3 또는 자체 연결을 여는 스크립트 대신 이러한 도구를 사용하여 데이터베이스 작업을 수행하세요.

아래 도구 이름은 TableStudio의 것입니다. 사용 중인 클라이언트는 이 이름에 접두사를 붙여 표시할 수 있습니다(Claude Code의 경우: mcp__plugin_tablestudio_tablestudio__list_connections). 도구가 지연 로딩되는 경우, 첫 번째 호출 전에 해당 이름으로 로드하세요.

1. 작업 전 올바른 데이터베이스 찾기

세션의 데이터베이스 컨텍스트 노트(TableStudio 플러그인에서 제공)는 일반적으로 리포지토리의 각 데이터베이스 설정 뒤에 있는 TableStudio 연결 이름, 해당 ID 및 환경을 명시합니다. 이 ID를 connection_id로 사용하세요. 노트는 또한 TableStudio의 도구를 사용할 수 없는 경우와 사용자가 취해야 할 조치를 알려줍니다.

노트가 없거나 노트에 이름이 없는 데이터베이스의 경우:

1. list_connections를 호출하세요. 각 연결에는 사용자가 TableStudio에 알려준 정보가 포함될 수 있습니다:
   • project: 연결이 속한 프로젝트. 작업 중인 리포지토리와 일치하는 프로젝트의 연결을 우선 사용하세요.
   • environment: development, staging 또는 production. 값이 없으면 태그되지 않은 상태이며 개발 환경이 아닙니다.
   • read_only: TableStudio가 이 연결에 대한 쓰기를 거부합니다. 스테이징은 여전히 작동합니다.
   • location: local(이 Mac), remote 또는 sandbox(실험해도 안전한 일회용 복사본).
   • agent_writes: direct는 execute_query가 (쓰기가 켜져 있을 때) 거기에 쓸 수 있음을 의미합니다. review는 모든 변경 사항이 사용자가 적용할 수 있도록 stage_migration을 거쳐야 함을 의미합니다. TableStudio가 이를 결정하며 사용자는 결정할 수 없습니다: 프로덕션, 그리고 사용자가 개발 또는 스테이징으로 태그하지 않은 모든 원격 데이터베이스는 review입니다.
   • notes: 데이터베이스 규칙(소프트 삭제, 금액을 센트로 표시, 명명 규칙)에 대한 사용자의 메모입니다. 이를 따르세요.
2. 먼저 프로젝트를 일치시킨 다음, 프로젝트 자체 설정(.env, config)과 host, port 및 database를 확인하여 확정하세요.
3. 두 연결 중 사용자가 의도한 연결을 확신할 수 없거나 프로덕션인지 확인할 수 없는 경우 질문하세요. 추측하지 마세요.

그런 다음:

• 읽기 이상의 작업을 계획하기 전에 describe_capabilities를 한 번 호출하세요. 현재 직접 쓰기, 스테이징 및 샌드박스가 허용되는지 여부를 알려주고 각 설정 뒤에 있는 이름을 명시합니다. 제한 사항에 직면하여 찾기보다는 이 정보를 바탕으로 계획을 세우세요.
• agent_writes: review(프로덕션 또는 원격 및 태그되지 않음)는 직접 쓰지 말고 변경 사항을 검토용으로 스테이징해야 함을 의미합니다. TableStudio는 어차피 직접 쓰기를 거부하므로 처음부터 스테이징을 계획하세요.
• SQL을 작성하기 전에 engine(postgres, mysql, sqlite, d1, clickhouse)을 확인하고 해당 방언으로 작성하세요.
• TableStudio에 저장되지 않은 데이터베이스는 TableStudio 도구를 통해 접근할 수 없습니다. 사용자에게 TableStudio에서 추가하도록 요청하세요. 채팅에서 비밀번호를 요청하지 마세요.
• 데이터베이스에 연결할 수 없어 호출이 실패하면 connection_status를 호출하세요. 로컬 서버가 중지되었다고 표시되면 제공된 instance_id로 start_local_database를 호출하세요.

2. 읽기 및 조사

• 이름을 추측하지 말고 조회하세요: search_schema는 이름 조각으로 테이블과 열을 찾고, get_table_ddl은 전체 구조, 인덱스, 외래 키 및 referenced_by를 제공합니다.
• execute_query로 읽기를 실행하세요. 필요한 열을 선택하고, 필터링하고, 집계하고, LIMIT을 사용하세요. 결과에는 상한선(max_rows, 기본값 200)이 있으므로 truncated 결과는 전체 답변이 아닙니다.
• 읽기는 30초 제한의 읽기 전용 트랜잭션으로 실행되며 프로덕션에서도 데이터를 변경할 수 없습니다(함수를 통해서도). 그래도 부담을 최소화하세요: 대규모 프로덕션 테이블에서는 인덱스된 열로 필터링하거나 count(*) 대신 database_overview 행 추정치를 사용하세요.
• 데이터 버그: 먼저 데이터에서 재현하세요. 잘못된 행을 찾고, 개수를 세고, 발생 시점(min(created_at))을 찾으세요. 그런 다음 해당 행을 작성하는 코드를 읽으세요. 버그를 증명하는 쿼리를 사용자에게 보여주세요. 코드를 수정하고, 행을 복구해야 하는 경우 데이터 변경(섹션 3)에 해당합니다.
• 절대 비밀, 비밀번호 또는 연결 문자열을 SQL, 코드, 문서 또는 채팅에 붙여넣지 마세요. 연결 문자열이 속한 유일한 곳은 로컬 데이터베이스용 프로젝트의 gitignored env 파일입니다(로컬 데이터베이스 스킬은 get_connection_url을 다룹니다).

3. 데이터 변경(INSERT, UPDATE, DELETE)

PostgreSQL에서:

1. 문을 작성한 다음 preflight_statement를 호출하세요. verdict(looks_fine, review 또는 would_fail), dry_run.rows(변경될 정확한 행 수, 읽기 전용), 다른 테이블로의 캐스케이드, 그리고 실패하게 만드는 요소를 얻을 수 있습니다.
2. 사용자에게 수행할 작업을 평이한 언어로 알리세요: "이 작업은 invoices에서 142개 행을 업데이트하며 캐스케이드는 없습니다." 평결이 would_fail이면 먼저 문을 수정하세요. review이면 이유를 설명하세요.
3. 그런 다음 다음 중 하나를 수행하세요:
   • agent_writes: direct이고 직접 쓰기가 허용된 경우: dry_run.rows로 설정된 expected_rows와 함께 execute_query를 사용하세요. 정확히 해당 수의 행이 변경된 경우에만 커밋하고 그렇지 않으면 롤백합니다. 원격 PostgreSQL 데이터베이스에서 TableStudio는 expected_rows 없이 데이터 변경을 거부합니다.
   • agent_writes: review, 쓰기가 허용되지 않음, 또는 사용자가 먼저 봐야 하는 모든 경우: 명확한 title, SQL 및 드라이 런 개수가 포함된 rationale("…에서 발견된 142개의 중복 인보이스를 무효화합니다")와 함께 stage_migration을 호출하세요. 이는 TableStudio의 에이전트 센터에 있는 사용자의 검토 큐로 이동하며 실행되지 않습니다.

다른 엔진에서는 드라이 런이 없습니다: 동일한 WHERE로 SELECT count(*)를 먼저 실행하고, 개수를 보고한 다음 동일한 실행-또는-스테이징 규칙을 따르세요.

중요한 데이터베이스(대규모 DELETE, DROP, TRUNCATE)에서 파괴적인 작업을 수행하기 전에, 샌드박스가 활성화된 경우 create_restore_point를 호출하고 사용자에게 이를 알리세요.

4. 스키마 변경

리포지토리가 마이그레이션 도구를 사용하는 경우(Prisma, Drizzle, Rails, Django, Alembic, Laravel, Supabase, Knex, Ecto, TypeORM, Wrangler D1 또는 일반 번호가 매겨진 SQL 파일, 플러그인이 감지한 경우 세션 컨텍스트에 이름이 표시됨), 변경 사항은 해당 도구에 속합니다:

1. 해당 도구의 방식으로 변경하세요: 스키마를 편집하고 마이그레이션을 생성하거나 마이그레이션 파일을 작성하세요.
2. 로컬 개발 데이터베이스에 도구의 개발 명령어로 적용하세요.
3. 실제 데이터에 대해 확인하세요(아래 참조).
4. 다른 곳에 적용하는 것은 사용자의 일반적인 배포 프로세스에 맡기세요. 절대 도구의 배포 명령어를 프로덕션에서 직접 실행하지 마세요.

마이그레이션 도구가 스키마를 소유할 때 ALTER TABLE을 직접 실행하면 도구의 기록이 데이터베이스와 동기화되지 않아 다음 배포가 중단됩니다.

마이그레이션 도구가 없거나 사용자가 기존 데이터베이스에 대한 일회성 변경을 요청하는 경우:

1. 먼저 get_table_ddl로 테이블을 읽으세요. 테이블을 삭제하거나 이름을 변경하기 전에 referenced_by를 확인하세요.
2. 복사본에서 시도해 보세요: create_sandbox(data: none(스키마 전용), sample(실제 행의 일부)), 샌드박스의 연결에서 execute_query로 DDL을 실행하고 의도한 대로 작동하는지 확인하세요.
3. compare_schemas로 차이점을 보여주세요(샌드박스를 source_connection_id로, 실제 데이터베이스를 target_connection_id로).
4. 실제 연결에서 stage_migration으로 제안하세요. 사용자가 TableStudio에서 적용합니다.

실제 데이터에 대한 마이그레이션 확인

로컬 데이터베이스에서 통과하는 마이그레이션도 실제 행이 있는 곳에서는 실패하거나 앱을 잠글 수 있습니다. 마이그레이션이 완료되었다고 판단하기 전에 배포할 데이터베이스(일반적으로 세션 노트 또는 list_connections의 스테이징 또는 프로덕션)에 대해 읽기 전용으로 확인하세요:

1. 변경하는 각 테이블에 대해 get_table_ddl: 행 수, 인덱스 및 참조하는 항목.

2. 추가하는 각 제약 조건에 대해, 해당 제약 조건을 위반하는 행을 찾는 SELECT를 execute_query로 실행하세요:

   • NOT NULL: SELECT count(*) FROM t WHERE col IS NULL
   • UNIQUE: SELECT col, count(*) FROM t GROUP BY col HAVING count(*) > 1 LIMIT 20
   • 외래 키: 부모가 없는 자식 행(LEFT JOIN … WHERE parent.id IS NULL)
   • CHECK 또는 더 좁은 유형/길이: 새 범위를 벗어난 행

   행이 하나라도 있으면 배포가 실패합니다. 마이그레이션에 백필 또는 정리 단계를 추가하고 이를 명시하세요.

3. PostgreSQL에서 대규모 테이블을 잠그거나 다시 작성하는 단계(아래 참조)에 플래그를 지정하고 안전한 패턴으로 전환하세요.

4. 변경이 까다로운 경우 해당 연결에서 data: "sample"로 create_sandbox를 만들고, 샌드박스에서 마이그레이션 SQL을 execute_query로 실행한 다음 compare_schemas를 실행하세요.

사용자에게 확인한 내용과 발견한 내용을 알리세요("orders.status에는 120만 행 중 NULL이 0개이므로 SET NOT NULL은 안전합니다"). 이 모든 작업은 읽기 전용입니다: 마이그레이션을 로컬 개발 데이터베이스 이외의 곳에는 절대 적용하지 마세요.

PostgreSQL의 잠금

• 크고 바쁜 테이블에 인덱스를 구축하는 경우: CREATE INDEX CONCURRENTLY를 사용하세요. 이는 트랜잭션 내에서 실행할 수 없으므로 해당 문을 BEGIN … COMMIT으로 감싸지 마세요.
• 휘발성 기본값으로 NOT NULL 열을 추가하거나, 열 유형을 변경하거나, 외래 키를 추가하면 테이블을 다시 작성하거나 잠글 수 있습니다. 근거에 이를 명시하고 안전한 단계로 분할하는 것을 고려하세요(열을 nullable로 추가, 배치로 백필, 그런 다음 SET NOT NULL, NOT VALID로 외래 키 추가, 그런 다음 VALIDATE CONSTRAINT).
• schema_issues는 각 문제에 대한 lock_impact와 함께 수정 SQL을 반환합니다. 수정을 제안하기 전에 이를 읽으세요.

5. 스테이징 후

• 사용자에게 TableStudio에서 검토를 기다리고 있으며 실행되지 않았음을 알리고 결과의 review_url을 링크로 제공하세요. 이 링크는 변경 사항의 영향(영향을 받는 행, 잠금, 실패할 사항), 적용 후 스키마 다이어그램 및 실행 취소 계획과 함께 검토를 엽니다. 스테이징된 변경 사항이 적용되었다고 말하지 마세요.
• 사용자가 변경을 요청하면 list_staged_migrations는 status: changes_requested와 review_feedback에 사용자 메모를 표시합니다. 두 번째 복사본을 스테이징하는 대신 update_staged_migration(동일한 migration_id)으로 수정한 다음 다시 볼 준비가 되었음을 알리세요. 철회하려면 remove_staged_migration을 사용하세요.
• list_staged_migrations는 또한 사용자가 적용했는지, 무시했는지 또는 실패했는지 보여줍니다.

사용자가 대기 중인 항목("무엇을 스테이징했나요?", "내 마이그레이션이 실행되었나요?")을 물으면 이 리포지토리의 연결에 대해 list_staged_migrations를 호출하세요. 보류 중인 항목을 최신 순으로 먼저 보고하세요: 제목, 연결, 스테이징된 시간, review_url, 그리고 수행하는 작업과 위험 수준(대규모 테이블을 잠그거나 다시 작성하는지, 데이터를 삭제하는지, WHERE가 없는지)에 대한 한 줄 설명. 그런 다음 변경 요청 항목(사용자 메모 포함)과 실패 항목(오류 메시지 포함)을 보고하세요. 사용자가 TableStudio의 에이전트 센터에서 적용하거나, 보내거나, 무시한다는 점을 명확히 말하세요. 사용자를 대신하여 적용할 수 없습니다.

6. TableStudio가 거부하는 경우

• 설정 이름을 명시하는 거부(예: 쓰기가 꺼져 있음)는 사용자의 선택입니다. 어떤 설정이 이를 허용하는지 알려주고, 대신 변경 사항을 스테이징하도록 제안하고 중단하세요. 우회하지 마세요.
• TableStudio의 도구를 전혀 사용할 수 없는 경우 세션 노트에 이유가 설명됩니다: 앱이 닫혀 있음, MCP 서버가 꺼져 있음(설정 → MCP), 또는 클라이언트가 아직 연결되지 않음. 제공된 수정 방법을 전달하세요. Claude Code에서 사용자는 TableStudio가 열리면 /mcp로 다시 연결할 수 있습니다.
• blocked: production_review_required 또는 review_required 오류가 있는 거부는 해당 연결이 검토를 통해서만 변경 사항을 허용함을 의미합니다: 스테이징하세요. dry_run_required는 먼저 preflight_statement를 실행하고 expected_rows를 전달하라는 의미입니다. side_effect_function은 문이 트랜잭션 외부에서 작동하는 항목을 호출함을 의미합니다. 대신 SQL을 사용자에게 보여주세요.
• 플러그인의 셸 가드는 프로덕션에 쓰는 셸 명령어를 차단합니다. 차단을 우회할 대상이 아닌 위 단계를 사용하라는 신호로 처리하세요.
• TableStudio를 통해 수행하는 모든 작업은 에이전트 센터에서 이 대화별로 그룹화되어 사용자에게 표시됩니다.