MCP Tools Reference: cloud-sql

도구: execute_sql

Cloud SQL 인스턴스에서 데이터 정의 언어 (DDL), 데이터 제어 언어 (DCL), 데이터 쿼리 언어 (DQL) 또는 데이터 조작 언어 (DML) 문을 비롯한 유효한 SQL 문을 실행합니다.

execute_sql 도구를 지원하려면 Cloud SQL 인스턴스가 다음 요구사항을 충족해야 합니다.

• data_api_access의 값은 ALLOW_DATA_API로 설정해야 합니다.
• MySQL 인스턴스의 경우 데이터베이스 플래그 cloudsql_iam_authentication을 on으로 설정해야 합니다. PostgreSQL 인스턴스의 경우 데이터베이스 플래그 cloudsql.iam_authentication를 on로 설정해야 합니다.
• execute_sql 도구를 호출하려면 IAM 사용자 계정 또는 IAM 서비스 계정 (CLOUD_IAM_USER 또는 CLOUD_IAM_SERVICE_ACCOUNT)이 필요합니다. 이 도구는 IAM 데이터베이스 인증으로 로그인한 데이터베이스 사용자의 권한을 사용하여 SQL 문을 실행합니다.

create_instance 도구를 사용하여 인스턴스를 만든 후 create_user 도구를 사용하여 현재 프로젝트에 로그인한 사용자의 IAM 사용자 계정을 만들 수 있습니다.

execute_sql 도구에는 다음과 같은 제한사항이 있습니다.

• SQL 문이 10MB보다 큰 응답을 반환하면 응답이 잘립니다.
• execute_sql 도구의 기본 제한 시간은 30초입니다. 쿼리가 30초 이상 실행되면 도구에서 DEADLINE_EXCEEDED 오류를 반환합니다.
• SQL Server에는 execute_sql 도구가 지원되지 않습니다.

'인스턴스에 IAM 인증이 사용 설정되지 않음'과 같은 오류가 표시되면 get_instance 도구를 사용하여 인스턴스의 IAM 데이터베이스 인증 플래그 값을 확인할 수 있습니다.

'인스턴스에서 executeSql을 사용하여 이 인스턴스에 액세스할 수 없습니다'와 같은 오류가 표시되면 get_instance 도구를 사용하여 data_api_access 설정을 확인할 수 있습니다.

인증 오류가 표시되는 경우:

1. list_users 도구를 사용하여 현재 로그인한 사용자 계정이 인스턴스에 IAM 사용자로 있는지 확인합니다.
2. IAM 사용자 계정이 없으면 create_user 도구를 사용하여 로그인한 사용자의 IAM 사용자 계정을 만듭니다.
3. 현재 로그인한 사용자에게 적절한 데이터베이스 사용자 역할이 없는 경우 update_user 도구를 사용하여 사용자에게 데이터베이스 역할을 부여할 수 있습니다. 예를 들어 cloudsqlsuperuser 역할은 IAM 사용자에게 필요한 많은 권한을 제공할 수 있습니다.

4. 현재 로그인한 사용자에게 프로젝트에 올바른 IAM 권한이 할당되어 있는지 확인합니다. gcloud projects get-iam-policy [PROJECT_ID] 명령어를 사용하여 사용자에게 프로젝트에 적합한 IAM 역할 또는 권한이 할당되어 있는지 확인할 수 있습니다.

   • 자동 IAM 데이터베이스 인증을 수행하려면 사용자에게 cloudsql.instance.login 권한이 있어야 합니다.
   • execute_sql 도구 또는 executeSql API를 사용하여 SQL 문을 실행하려면 사용자에게 cloudsql.instances.executeSql 권한이 있어야 합니다.
   • 필요한 권한이 포함된 일반적인 IAM 역할: Cloud SQL 인스턴스 사용자 (roles/cloudsql.instanceUser) 또는 Cloud SQL 관리자 (roles/cloudsql.admin)

ExecuteSqlResponse를 수신할 때는 항상 응답 본문 내의 message 및 status 필드를 확인하세요. HTTP 상태 코드가 성공이라고 해서 모든 SQL 문이 완전히 성공하는 것은 아닙니다. message 및 status 필드는 SQL 문 실행 중에 부분 오류나 경고가 있었는지 여부를 나타냅니다.

다음 샘플은 curl를 사용하여 execute_sql MCP 도구를 호출하는 방법을 보여줍니다.

curl 요청
curl --location 'https://sqladmin.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "execute_sql", "arguments": { // provide these details according to the tool's MCP specification } }, "jsonrpc": "2.0", "id": 1 }'

입력 스키마

MCP의 인스턴스 SQL 실행 요청입니다.

SqlInstancesExecuteSqlMcpRequest

JSON 표현
{ "instance": string, "project": string, "sqlStatement": string, "database": string }

필드
instance	string 필수 항목입니다. 데이터베이스 인스턴스 ID입니다. 여기에는 프로젝트 ID가 포함되지 않습니다.
project	string 필수 항목입니다. 인스턴스가 포함된 프로젝트의 프로젝트 ID입니다.
sqlStatement	string 필수 항목입니다. 데이터베이스에서 실행할 SQL 문입니다. 단일 문일 수도 있고 세미콜론으로 구분된 문 시퀀스일 수도 있습니다.
database	string 선택사항입니다. 문이 실행될 데이터베이스의 이름입니다. Postgres의 경우 필수이고 MySQL의 경우 선택사항입니다. Postgres의 경우 쿼리가 데이터베이스 나열 / 새 데이터베이스 만들기 / 역할 부여와 같은 기존 데이터베이스로 범위가 지정되지 않은 경우 기본값을 postgres로 전달할 수 있습니다.

출력 스키마

SQL 문 실행 응답입니다.

SqlInstancesExecuteSqlResponse

JSON 표현
{ "messages": [ { object (Message) } ], "metadata": { object (Metadata) }, "results": [ { object (QueryResult) } ], "status": { object (Status) } }

필드
messages[]	object (Message) 쿼리 실행 중에 생성된 알림 및 경고 목록입니다. PostgreSQL의 경우 모든 알림과 경고가 포함됩니다. MySQL의 경우 마지막으로 실행된 문에서 생성된 경고가 포함됩니다. 멀티 문 쿼리의 모든 경고를 가져오려면 각 문 뒤에 SHOW WARNINGS를 실행해야 합니다.
metadata	object (Metadata) SQL 문 실행에 관한 추가 메타데이터 정보입니다.
results[]	object (QueryResult) 모든 SQL 문을 실행한 후의 결과 목록입니다.
status	object (Status) SQL 실행이 실패한 경우 데이터베이스의 오류를 포함합니다.

메시지

JSON 표현
{ // Union field _message can be only one of the following: "message": string // End of list of possible types for union field _message. // Union field _severity can be only one of the following: "severity": string // End of list of possible types for union field _severity. }

필드
통합 필드 _message. _message는 다음 중 하나여야 합니다.
message	string 전체 메시지 문자열입니다. PostgreSQL의 경우 심각도, 코드, 알림/경고 메시지가 포함될 수 있는 형식화된 문자열입니다. MySQL의 경우 경고 메시지가 포함됩니다.
통합 필드 _severity. _severity는 다음 중 하나여야 합니다.
severity	string 메시지의 심각도입니다 (예: PostgreSQL의 경우 'NOTICE', MySQL의 경우 'WARNING')

메타데이터

JSON 표현
{ "sqlStatementExecutionTime": string }

필드
sqlStatementExecutionTime	string (Duration format) SQL 문을 실행하는 데 걸린 시간입니다. 소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

기간

JSON 표현
{ "seconds": string, "nanos": integer }

필드
seconds	string (int64 format) 시간 범위의 부호가 있는 초입니다. -315,576,000,000~+315,576,000,000(포함) 사이여야 합니다. 참고: 이 범위는 60초/분 * 60분/시간 * 24시간/일 * 365.25일/년 * 10,000년에서 계산됩니다.
nanos	integer 시간 범위의 나노초 단위로 된 부호가 있는 초수입니다. 1초 미만의 기간은 0 seconds 필드와 양수 또는 음수 nanos 필드로 표현됩니다. 1초 이상의 기간의 경우 nanos 필드의 0이 아닌 값은 seconds 필드와 부호가 같아야 합니다. -999,999,999~+999,999,999(포함) 사이여야 합니다.

QueryResult

JSON 표현
{ "columns": [ { object (Column) } ], "rows": [ { object (Row) } ], "message": string, "partialResult": boolean, "status": { object (Status) } }

필드
columns[]	object (Column) 결과에 포함된 열 목록입니다. 여기에는 열의 데이터 유형도 포함됩니다.
rows[]	object (Row) SQL 문에 의해 반환된 행입니다.
message	string SQL 실행 결과와 관련된 메시지입니다.
partialResult	boolean 크기 제한 또는 결과를 가져오는 중 발생한 오류로 인해 SQL 실행 결과가 잘린 경우 true로 설정됩니다.
status	object (Status) 오류로 인해 결과가 잘린 경우 해당 오류의 세부정보입니다.

열

JSON 표현
{ "name": string, "type": string }

필드
name	string 열 이름입니다.
type	string 열의 데이터 유형입니다.

행

JSON 표현
{ "values": [ { object (Value) } ] }

필드
values[]	object (Value) 행의 값입니다.

값

JSON 표현
{ "value": string, "nullValue": boolean }

필드
value	string 문자열 형식의 셀 값입니다.
nullValue	boolean 셀 값이 null이면 이 플래그가 true로 설정됩니다.

상태

JSON 표현
{ "code": integer, "message": string, "details": [ { "@type": string, field1: ..., ... } ] }

필드
code	integer 상태 코드로, google.rpc.Code의 열거형 값이어야 합니다.
message	string 개발자에게 정보를 제공하는 오류 메시지로, 영어로 작성되어야 합니다. 사용자에게 표시되는 모든 오류 메시지는 현지화되어 google.rpc.Status.details 필드에 전송되거나, 클라이언트 측에서 현지화되어야 합니다.
details[]	object 오류 세부정보를 설명하는 메시지 목록입니다. API에서 사용할 일반적인 메시지 유형 집합이 있습니다. 임의 유형의 필드를 포함하는 객체입니다. 추가 필드 "@type"은 유형을 식별하는 URI를 포함합니다. 예: { "id": 1234, "@type": "types.example.com/standard/id" }

모두

JSON 표현
{ "typeUrl": string, "value": string }

필드
typeUrl	string 직렬화된 프로토콜 버퍼 메시지의 유형을 고유하게 식별하는 URL/리소스 이름입니다. 이 문자열에는 '/' 문자가 하나 이상 포함되어야 합니다. URL 경로의 마지막 세그먼트는 유형의 정규화된 이름을 나타내야 합니다 (예: path/google.protobuf.Duration). 이름은 표준 형식이어야 합니다 (예: 선행 '.'은 허용되지 않음). 실제로 팀은 Any 컨텍스트에서 사용할 것으로 예상되는 모든 유형을 바이너리로 사전 컴파일합니다. 하지만 http, https 스킴을 사용하거나 스킴이 없는 URL의 경우 유형 URL을 메시지 정의에 매핑하는 유형 서버를 다음과 같이 선택적으로 설정할 수 있습니다. 제공된 스키마가 없으면 https을 가정합니다. URL에 대한 HTTP GET은 바이너리 형식의 google.protobuf.Type 값을 생성하거나 오류를 생성해야 합니다. 애플리케이션은 URL을 기반으로 조회 결과를 캐시하거나 조회를 방지하기 위해 바이너리로 사전 컴파일할 수 있습니다. 따라서 유형 변경 시 바이너리 호환성을 유지해야 합니다. (버전이 지정된 유형 이름을 사용하여 브레이킹 체인지를 관리하세요.) 참고: 이 기능은 현재 공식 protobuf 출시에서 사용할 수 없으며 type.googleapis.com으로 시작하는 유형 URL에는 사용되지 않습니다. 2023년 5월 현재 널리 사용되는 유형 서버 구현이 없으며 구현 계획도 없습니다. http, https (또는 빈 스킴) 이외의 스킴은 구현별 시맨틱과 함께 사용될 수 있습니다.
value	string (bytes format) 위에 지정된 유형의 유효한 직렬화된 프로토콜 버퍼여야 합니다. base64 인코딩 문자열입니다.

도구 주석

파괴적 힌트: ✅ | 동일한 힌트: ❌ | 읽기 전용 힌트: ❌ | 오픈 월드 힌트: ❌