MCP, Gemini CLI 및 기타 에이전트와 함께 PostgreSQL용 Cloud SQL 사용

이 페이지에서는 Cloud SQL 인스턴스를 다음과 같은 다양한 AI 개발자 지원 도구에 연결하는 방법을 보여줍니다.

통합 환경의 경우 전용 PostgreSQL용 Cloud SQL용 Gemini CLI 확장 프로그램을 사용하는 것이 좋습니다.

Google Cloud의 차세대 명령줄 인터페이스인 Gemini CLI는 기본 MCP 서버를 확장 프로그램에 직접 번들로 제공하므로 설정 및 구성이 간소화됩니다. Gemini CLI를 사용하도록 Gemini Code Assist를 구성하여 IDE에서 유사한 설정 이점을 누릴 수 있습니다.

모델 컨텍스트 프로토콜 (MCP)을 지원하는 다른 개발자 도구의 경우 데이터베이스용 MCP 도구 상자 (도구 상자)를 수동으로 구성하여 연결할 수 있습니다. 도구 상자는 인증 및 연결 풀링과 같은 작업을 관리하여 AI 에이전트를 데이터에 연결하는 오픈소스 MCP 서버입니다. 이렇게 하면 IDE에서 직접 자연어를 사용하여 데이터와 상호작용할 수 있습니다. 이러한 도구의 경우 이 메서드는 핵심 데이터베이스 상호작용 기능을 제공합니다.

자세한 내용은 사전 빌드 도구 및 GitHub의 데이터베이스용 MCP 도구 상자를 참고하세요.

Gemini CLI 및 확장 프로그램 정보

Gemini CLI는 코딩, 디버깅, 데이터 탐색, 콘텐츠 제작을 지원하여 개발 워크플로를 지원하도록 설계된 오픈소스 AI 에이전트입니다. 데이터베이스 및 분석 서비스와 인기 있는 오픈소스 데이터베이스와 상호작용할 수 있는 에이전트 인터페이스를 제공합니다.

확장 프로그램 작동 방식

Gemini CLI는 확장성이 뛰어나 확장 프로그램을 통해 새로운 도구와 기능을 추가할 수 있습니다. GitHub URL, 로컬 디렉터리 또는 구성 가능한 레지스트리에서 확장 프로그램을 로드할 수 있습니다. 워크플로를 지원하는 새로운 도구, 슬래시 명령어, 프롬프트를 제공합니다.

PostgreSQL용 Cloud SQL에서 Gemini CLI 확장 프로그램 사용

Cloud SQL Gemini CLI 확장 프로그램은 데이터베이스용 MCP 도구 상자를 기반으로 합니다. 데이터베이스용 MCP 도구 상자는 현재 베타 (v1.0 이전)이며 첫 번째 안정화 버전 (v1.0)이 출시될 때까지 브레이킹 체인지가 발생할 수 있습니다.

Gemini CLI와의 통합은 표준 도구 상자 연결에 비해 추가 기능을 제공하는 전용 확장 프로그램을 통해 이루어집니다. 이 확장 프로그램은 간소화된 설치 프로세스와 도구 모음을 제공합니다.

자세한 내용은 PostgreSQL용 Cloud SQL용 Gemini CLI 확장 프로그램에 관한 GitHub 문서를 참고하세요.

PostgreSQL용 Cloud SQL 데이터베이스용 Gemini CLI 확장 프로그램

cloud-sql-postgresql 확장 프로그램에는 데이터베이스를 쿼리하고, Cloud SQL 리소스를 관리하고, 데이터베이스 상태를 모니터링하는 도구가 포함되어 있습니다.

카테고리 도구
데이터베이스 작업
  • list_tables: 데이터베이스에 있는 모든 테이블과 해당 설명을 나열합니다.
  • execute_sql: SQL 문을 실행합니다.
  • list_active_queries: Cloud SQL 인스턴스에서 현재 실행 중인 쿼리를 나열합니다.
  • list_available_extensions: Cloud SQL 인스턴스에 설치할 수 있는 PostgreSQL 확장 프로그램을 나열합니다.
  • list_installed_extensions: Cloud SQL 인스턴스에 설치된 PostgreSQL 확장 프로그램을 나열합니다.
  • get_query_plan: Cloud SQL 인스턴스에서 단일 문의 쿼리 계획을 가져옵니다.
인스턴스 및 사용자 리소스 관리
  • create_user: Cloud SQL 인스턴스에서 새 사용자를 만듭니다.
  • list_databases: Cloud SQL 인스턴스의 모든 데이터베이스를 나열합니다.
  • create_database: Cloud SQL 인스턴스 내에 새 데이터베이스를 만듭니다.
  • list_instances: 지정된 프로젝트의 Cloud SQL 인스턴스를 나열합니다.
  • get_instance: 특정 Cloud SQL 인스턴스에 관한 세부정보를 가져옵니다.
  • create_instance: 새 Cloud SQL 인스턴스를 만듭니다.
  • wait_for_operation: 작업이 완료될 때까지 작업 API를 폴링합니다.
데이터베이스 상태 및 유지관리
  • list_autovacuum_configurations: Cloud SQL 인스턴스의 autovacuum 설정을 나열합니다. 진공 작업은 디스크 공간을 확보하고, 테이블이 비대해지는 것을 방지하며, 읽기 및 쓰기 성능을 개선하기 위해 데드 튜플을 삭제합니다.
  • list_memory_configurations: Cloud SQL 인스턴스의 인스턴스 수준 메모리 설정을 나열합니다. 쿼리 실행 및 캐싱을 위한 리소스 할당을 평가하고 최적화하는 데 도움이 되는 shared_buffers 및 work_mem과 같은 매개변수를 표시합니다.
  • list_top_bloated_tables: 가장 사용하지 않는 공간 (블로트)이 많은 Cloud SQL 인스턴스의 테이블을 나열합니다. 이 정보를 사용하여 디스크 공간을 확보하고 쿼리 속도를 개선하기 위해 청소 또는 색인 재생성과 같은 유지보수를 예약할 수 있습니다.
  • list_replication_slots: Cloud SQL 인스턴스의 WAL (Write-Ahead Logging)과 같은 복제 슬롯 세부정보를 나열합니다. 복제 관련 문제의 관리 및 문제 해결을 지원합니다.
  • list_invalid_indexes: Cloud SQL 인스턴스의 잘못된 색인을 나열합니다. 이 정보를 사용하여 쿼리 성능을 개선하기 위해 잘못된 색인을 재빌드하거나 삭제할 수 있습니다.

cloud-sql-postgresql-observability 확장 프로그램은 Gemini CLI에서 직접 데이터베이스 성능과 상태를 관리하고 모니터링할 수 있는 통합 인터페이스를 제공합니다.

카테고리 도구
관측 가능성
  • get_system_metrics: Cloud SQL 인스턴스의 시스템 측정항목을 가져옵니다.
  • get_query_metrics: Cloud SQL 인스턴스의 쿼리 관련 측정항목을 가져옵니다.

PostgreSQL 데이터베이스용 Gemini CLI 확장 프로그램

이러한 작업 목록은 데이터베이스용 MCP 도구 상자 및 PostgreSQL용 Gemini CLI 확장 프로그램을 참고하세요.

시작하기 전에

MCP Toolbox 설치

  1. 도구 상자를 설치하려면 운영체제 및 CPU 아키텍처에 해당하는 바이너리를 다운로드합니다.

    linux/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/windows/amd64/toolbox

  2. 바이너리를 실행 가능하게 만듭니다.

    chmod +x toolbox

  3. 다음 명령어를 사용하여 설치를 확인합니다.

    ./toolbox --version

MCP 클라이언트 구성

이 섹션에서는 Toolbox를 사용하여 Cloud SQL 인스턴스에 연결하도록 다양한 개발자 도구를 구성하는 방법을 설명합니다. 이 도구 상자는 IDE와 데이터베이스 사이에 있는 오픈소스 모델 컨텍스트 프로토콜 (MCP) 서버 역할을 하며 AI 도구를 위한 안전하고 효율적인 컨트롤 플레인을 제공합니다. 특정 도구의 탭을 선택하여 구성 안내를 확인합니다.

PostgreSQL용 Cloud SQL용 Gemini CLI


  1. Gemini CLI를 설치합니다.
  2. 다음 명령어를 사용하여 GitHub 저장소에서 Gemini CLI용 PostgreSQL용 Cloud SQL 확장 프로그램을 설치합니다. 
      gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql
  3. Cloud SQL 인스턴스에 연결하도록 환경 변수를 설정합니다. 
      export CLOUD_SQL_POSTGRES_PROJECT="PROJECT_NAME"
  export CLOUD_SQL_POSTGRES_REGION="REGION"
  export CLOUD_SQL_POSTGRES_INSTANCE="INSTANCE_NAME"
  export CLOUD_SQL_POSTGRES_DATABASE="DATABASE_NAME"
  export CLOUD_SQL_POSTGRES_USER="DATABASE_USER_NAME"
  export CLOUD_SQL_POSTGRES_PASSWORD="PASSWORD"
  export CLOUD_SQL_POSTGRES_IP_TYPE="IP_TYPE"
    다음을 바꿉니다.
    • PROJECT_NAME: Google Cloud 프로젝트 ID입니다.
    • REGION: Cloud SQL 인스턴스의 리전입니다.
    • INSTANCE_NAME: Cloud SQL 인스턴스의 ID입니다.
    • DATABASE_NAME: 연결할 데이터베이스의 이름입니다.
    • DATABASE_USER_NAME: 선택사항: 데이터베이스 사용자 이름입니다. 지정되지 않은 경우 기본값은 IAM 인증입니다.
    • PASSWORD: 선택사항: 데이터베이스 사용자의 비밀번호입니다. 지정되지 않은 경우 기본값은 IAM 인증입니다.
    • IP_TYPE: 선택사항: IP 유형입니다(예: 'Public'(기본값) 또는 'Private').
  4. 대화형 모드에서 Gemini CLI를 시작합니다. 
      gemini

    CLI는 Cloud SQL용 Gemini CLI 확장 프로그램과 도구를 자동으로 로드하므로 이를 사용하여 데이터베이스와 상호작용할 수 있습니다.

    Gemini CLI에서 /extensions 명령어를 사용하여 확장 프로그램이 설치되어 있는지 확인하고 /mcp list 명령어를 사용하여 도구를 확인합니다.

PostgreSQL용 Gemini CLI


1. Gemini CLI를 설치합니다.
2. 다음 명령어를 사용하여 GitHub 저장소에서 Gemini CLI용 PostgreSQL 소프트웨어 확장 프로그램을 설치합니다. 
      gemini extensions install https://github.com/gemini-cli-extensions/postgres
3. PostgreSQL 인스턴스에 연결하도록 환경 변수를 설정합니다. 
      export POSTGRES_HOST="HOST"
      export POSTGRES_PORT="PORT"
      export POSTGRES_DATABASE="DATABASE"
      export POSTGRES_USER="USER"
      export POSTGRES_PASSWORD="PASSWORD"
      export POSTGRES_QUERY_PARAMETERS="QUERY_PARAMETERS"
다음을 바꿉니다.
  • HOST: PostgreSQL 서버의 호스트 이름 또는 IP 주소입니다.
  • PORT: PostgreSQL 서버의 포트 번호입니다.
  • DATABASE: 연결할 데이터베이스의 이름입니다.
  • USER: 데이터베이스 사용자 이름입니다.
  • PASSWORD: 데이터베이스 사용자의 비밀번호입니다.
  • QUERY_PARAMETERS: 선택사항: db 연결 문자열에 추가할 원시 쿼리입니다.
4. 대화형 모드에서 Gemini CLI를 시작합니다. 
      gemini

CLI는 PostgreSQL용 Gemini CLI 확장 프로그램과 도구를 자동으로 로드하므로 이를 사용하여 데이터베이스와 상호작용할 수 있습니다.

Gemini Code Assist


1. Visual Studio Code에 Gemini Code Assist 확장 프로그램을 설치합니다.
2. Gemini Code Assist 채팅에서 에이전트 모드를 사용 설정합니다.
3. 작업 디렉터리에 .gemini 폴더를 만듭니다. 이 폴더 내에 settings.json 파일을 만듭니다.
4. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Claude code


1. Claude Code를 설치합니다.
2. .mcp.json 파일이 없으면 프로젝트 루트에 이 파일을 만듭니다.
3. 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다. 


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Claude Desktop


1. Claude Desktop을 열고 설정으로 이동합니다.
2. 개발자 탭에서 구성 수정을 탭하여 구성 파일을 엽니다.
3. 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다. 


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
    }
  }
}

5. Claude Desktop을 다시 시작합니다.
6. 새 채팅 화면에 사용 가능한 새 MCP 서버와 함께 망치(MCP) 아이콘이 표시됩니다.

Cline


1. VS Code에서 Cline 확장 프로그램을 열고 MCP Servers 아이콘을 탭합니다.
2. MCP 서버 구성을 탭하여 구성 파일을 엽니다.
3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다. 


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

4. 서버가 성공적으로 연결되면 녹색 활성 상태가 표시됩니다.

커서


1. .cursor 디렉터리가 없으면 프로젝트 루트에 이 디렉터리를 만듭니다.
2. .cursor/mcp.json 파일이 없으면 이 파일을 만들고 엽니다.
3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

4. 커서를 열고 설정 > 커서 설정 > MCP로 이동합니다. 서버가 연결되면 녹색 활성 상태가 표시됩니다.

Visual Studio Code(Copilot)


1. VS Code를 열고 프로젝트 루트에 .vscode 디렉터리가 없으면 만듭니다.
2. .vscode/mcp.json 파일이 없으면 이 파일을 만들고 엽니다.
3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다. 


{
  "servers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Windsurf


1. Windsurf를 열고 Cascade 어시스턴트로 이동합니다.
2. MCP 아이콘을 탭한 후 구성을 탭하여 구성 파일을 엽니다.
3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다. 


{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
        "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_POSTGRES_REGION": "REGION",
        "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
        "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_POSTGRES_USER": "USER_ID",
        "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}