MCP Tools Reference: cloud-sql

도구: execute_sql

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

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

  • data_api_access의 값은 ALLOW_DATA_API로 설정해야 합니다.
  • built_in 사용자의 경우 password_secret_version을 설정해야 합니다.
  • 그렇지 않은 경우 IAM 사용자의 경우 MySQL 인스턴스에 대해 데이터베이스 플래그 cloudsql_iam_authentication를 on로 설정해야 합니다. PostgreSQL 인스턴스의 경우 데이터베이스 플래그 cloudsql.iam_authentication를 on로 설정해야 합니다.
  • 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,
  "user": string,
  "passwordSecretVersion": string
}
필드
instance

string

필수 항목입니다. 데이터베이스 인스턴스 ID입니다. 여기에는 프로젝트 ID가 포함되지 않습니다.
project

string

필수 항목입니다. 인스턴스가 포함된 프로젝트의 프로젝트 ID입니다.
sqlStatement

string

필수 항목입니다. 데이터베이스에서 실행할 SQL 문입니다. 단일 문일 수도 있고 세미콜론으로 구분된 문 시퀀스일 수도 있습니다.
database

string

선택사항입니다. 문이 실행될 데이터베이스의 이름입니다. Postgres의 경우 필수이고 MySQL의 경우 선택사항입니다. Postgres의 경우 쿼리가 데이터베이스 나열 / 새 데이터베이스 만들기 / 역할 부여와 같은 기존 데이터베이스로 범위가 지정되지 않은 경우 기본값을 postgres로 전달할 수 있습니다.
user

string

선택사항입니다. 데이터베이스에 연결할 기존 데이터베이스 사용자의 이름입니다. auto_iam_authn가 true로 설정되면 이 필드는 무시되고 API 호출자의 IAM 사용자가 사용됩니다.
passwordSecretVersion

string

선택사항입니다. 데이터베이스에 로그인할 사용자의 비밀번호를 보유한 Secret Manager 보안 비밀의 리소스 이름입니다. 예상되는 형식은 projects/{project}/secrets/{secret}/versions/{secret_version}입니다. 보안 비밀 리소스 이름은 저장되지 않습니다.

출력 스키마

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

슬래시로 끝나는 접두사와 정규화된 유형 이름으로 구성된 URI 참조를 사용하여 직렬화된 Protobuf 메시지의 유형을 식별합니다.

예: type.googleapis.com/google.protobuf.StringValue

이 문자열에는 / 문자가 하나 이상 포함되어야 하며, 마지막 / 뒤의 콘텐츠는 선행 점이 없는 표준 형식의 유형의 정규화된 이름이어야 합니다. 클라이언트가 연락을 시도하지 않도록 이러한 URI 참조에 스킴을 작성하지 마세요.

접두사는 임의적이며 Protobuf 구현은 유형을 식별하기 위해 마지막 /까지 포함한 모든 것을 삭제해야 합니다. type.googleapis.com/는 일부 기존 구현에 필요한 일반적인 기본 접두사입니다. 이 접두사는 유형의 출처를 나타내지 않으며, 이를 포함하는 URI는 요청에 응답하지 않을 것으로 예상됩니다.

모든 유형 URL 문자열은 참조의 콘텐츠가 영숫자, 퍼센트 인코딩된 이스케이프, 다음 집합의 문자(외부 백틱 제외)로만 구성되어야 한다는 추가 제한사항이 있는 합법적인 URI 참조여야 합니다. /-.~_!$&()*+,;= Google에서는 퍼센트 인코딩을 허용하지만 기존 파서와의 혼동을 방지하기 위해 구현에서 퍼센트 인코딩을 이스케이프 해제해서는 안 됩니다. 예를 들어 type.googleapis.com%2FFoo는 거부되어야 합니다.

Any의 원래 설계에서는 이러한 유형 URL에서 유형 확인 서비스를 실행할 가능성이 고려되었지만 Protobuf는 이를 구현하지 않았으며 이러한 URL에 연결하는 것을 문제이자 잠재적인 보안 문제로 간주합니다. 연락처 유형 URL을 시도하지 마세요.
value

string (bytes format)

type_url로 설명된 유형의 Protobuf 직렬화를 보유합니다.

base64 인코딩 문자열입니다.

도구 주석

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