MCP, Gemini CLI, 기타 에이전트와 함께 AlloyDB Omni 사용

이 문서에서는 AlloyDB Omni 인스턴스를 모델 컨텍스트 프로토콜 (MCP)을 지원하는 다양한 에이전트에 연결하는 방법을 설명합니다.

AlloyDB Omni는 PostgreSQL과 호환되므로 PostgreSQL용으로 설계된 도구와 확장 프로그램을 사용할 수 있습니다.

가장 간단한 설정을 위해서는 Gemini CLI용 전용 PostgreSQL 확장 프로그램을 사용하세요. 기본 MCP 서버가 확장 프로그램에 직접 통합되어 별도의 서버를 설정하지 않아도 됩니다. Gemini Code Assist에서 Gemini CLI를 사용하도록 구성하여 IDE에서 유사한 설정 이점을 누릴 수 있습니다.

또는 MCP를 지원하는 다른 IDE 및 에이전트가 데이터베이스용 MCP 도구 상자를 통해 연결될 수 있습니다. 도구 상자는 AI 에이전트를 데이터에 연결하도록 설계된 오픈소스 MCP 서버입니다. 인증 및 연결 풀링과 같은 태스크를 처리하므로 IDE에서 직접 자연어로 데이터와 상호작용할 수 있습니다.

시작하기 전에

AlloyDB Omni 인스턴스에 연결하기 전에 다음을 수행해야 합니다.

  1. Kubernetes용 AlloyDB Omni 또는 컨테이너용 AlloyDB Omni를 설치하고 실행 중인 데이터베이스 인스턴스가 있어야 합니다.
  2. 데이터베이스 사용자를 만들거나 재사용합니다. 사용자 이름과 비밀번호를 입력할 준비를 합니다.

PostgreSQL용 Gemini CLI 확장 프로그램 사용

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

AlloyDB Omni용 Gemini CLI와의 통합은 PostgreSQL 확장 프로그램을 통해 이루어집니다. 이 확장 프로그램은 PostgreSQL 및 AlloyDB Omni와 상호작용할 수 있는 도구 세트를 제공하므로 자연어 프롬프트를 사용하여 Gemini CLI에서 직접 데이터베이스를 관리하고, 쿼리를 실행하고, 스키마를 탐색할 수 있습니다.

다음 예시에서는 다음 테이블이 있는 샘플 ecommerce 데이터베이스를 사용합니다.

  • products: product_id, product_name, category, price를 포함한 제품 정보가 포함됩니다.
  • customers: customer_id, first_name, last_name, email과 같은 고객 데이터를 저장합니다.
  • orders: order_id, customer_id, order_date를 포함한 주문 정보를 보유합니다.

PostgreSQL 확장 프로그램 내에서 다음 도구를 사용할 수 있습니다.

카테고리 도구 자연어 프롬프트 예시
데이터베이스 작업 execute_sql '노트북' 카테고리에서 가장 비싼 제품 10개를 보여 줘.
get_query_plan 지난 6개월 동안 주문을 하지 않은 모든 고객을 찾는 쿼리에 대한 쿼리 계획을 설명해 줘.
list_active_queries 데이터베이스에서 실행 중인 쿼리는 무엇인가요?
database_overview 현재 데이터베이스의 개요를 알려 줘.
list_tables 현재 데이터베이스의 모든 테이블을 보여 줘.
list_views 어떤 보기를 사용할 수 있나요?
list_schemas 모든 스키마를 나열합니다.
list_triggers 주문 테이블의 트리거를 보여 줘.
list_available_extensions 설치할 수 있는 확장 프로그램은 무엇인가요?
list_installed_extensions 설치된 모든 확장 프로그램을 나열해 줘.
list_indexes 모든 색인을 나열합니다.
list_sequences 모든 시퀀스를 나열합니다.
데이터베이스 상태 및 유지보수 list_autovacuum_configurations 현재 autovacuum 구성을 보여 줘.
list_memory_configurations 현재 메모리 구성은 무엇인가요?
list_top_bloated_tables 가장 큰 테이블 5개를 나열해 줘.
list_replication_slots 활성 복제 슬롯을 모두 표시해 줘.
list_invalid_indexes ecommerce 데이터베이스에서 잘못된 색인을 확인해 줘.
long_running_transactions 장기 실행 트랜잭션을 보여 줘.
list_locks 모든 잠금 장치를 나열합니다.
replication_stats 복제 통계를 보여 줘.

PostgreSQL용 Gemini CLI 확장 프로그램을 다음 두 가지 방법으로 사용할 수 있습니다.

  • 독립형 명령줄 도구
  • Gemini Code Assist와 함께 IDE에 통합

Gemini CLI

  1. Gemini CLI (버전 0.6.0 이상)를 설치합니다.
  2. 다음 명령어를 사용하여 GitHub 저장소에서 Gemini CLI용 PostgreSQL 확장 프로그램을 설치합니다. 
    gemini extensions install https://github.com/gemini-cli-extensions/postgres
  3. 환경 변수를 설정하여 AlloyDB Omni 인스턴스에 연결합니다. 
    export POSTGRES_HOST="DATABASE_HOST"
export POSTGRES_PORT="DATABASE_PORT"
export POSTGRES_DATABASE="DATABASE_NAME"
export POSTGRES_USER="DATABASE_USER"
export POSTGRES_PASSWORD="DATABASE_PASSWORD"

    작업 디렉터리의 .env 파일에서 이러한 변수를 로드할 수도 있습니다.

  4. 대화형 모드에서 Gemini CLI를 시작합니다. 
    gemini
     CLI는 PostgreSQL 확장 프로그램과 도구를 자동으로 로드하므로 이를 사용하여 데이터베이스와 상호작용할 수 있습니다.

Gemini Code Assist

MCP 서버를 수동으로 구성하지 않으려면 Gemini Code Assist에서 Gemini CLI를 사용하도록 구성하세요.

  1. Gemini CLI 탭에 설명된 대로 Gemini CLI 및 postgres 확장 프로그램을 설치하고 구성합니다.
  2. Gemini Code Assist에서 Gemini CLI를 사용하도록 구성합니다.
  3. Gemini Code Assist 채팅 내에서 직접 자연어를 사용하여 AlloyDB Omni 인스턴스와 상호작용합니다.

데이터베이스용 MCP 도구 상자를 사용하여 다른 IDE와 연결

이 섹션에서는 데이터베이스용 MCP 도구 상자를 사용하여 다양한 에이전트에서 AlloyDB Omni 인스턴스에 연결하는 방법을 설명합니다.

데이터베이스용 MCP 도구 상자 설치

IDE를 AlloyDB Omni에 연결하려면 AI 에이전트를 데이터에 연결하는 오픈소스 서버인 데이터베이스용 MCP 도구 상자를 설치해야 합니다.

  1. 도구 상자 최신 버전을 바이너리로 다운로드합니다. 운영체제(OS) 및 CPU 아키텍처에 해당하는 바이너리를 선택합니다.

    linux/amd64

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

    darwin/arm64

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

    darwin/amd64

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

    windows/amd64

    curl -L -O https://storage.googleapis.com/genai-toolbox/v0.21.0/windows/amd64/toolbox.exe

  2. 바이너리를 실행 파일로 만듭니다.

    chmod +x toolbox

  3. 설치를 확인합니다.

    ./toolbox --version

클라이언트 구성

다음 옵션 중에서 에이전트 도구를 선택합니다.

커서

  1. 프로젝트 루트에 .cursor 디렉터리가 없으면 이 디렉터리를 만듭니다.
  2. .cursor/mcp.json 파일이 없으면 만들고 엽니다.
  3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.
{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
  1. 커서를 열고 설정 > 커서 설정 > MCP로 이동합니다. 서버가 연결되면 녹색 활성 상태가 표시됩니다.

Windsurf

  1. Windsurf를 열고 Cascade 어시스턴트로 이동합니다.
  2. MCP 아이콘을 클릭한 후 구성을 클릭하여 구성 파일을 엽니다.
  3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.
{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}

Visual Studio Code(Copilot)

  1. VS Code를 열고 프로젝트 루트에 .vscode 디렉터리가 없으면 이 디렉터리를 만듭니다.
  2. .vscode/mcp.json 파일이 없으면 만들고 엽니다.
  3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.
{
  "servers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}

Cline

  1. VS Code에서 Cline 확장 프로그램을 열고 MCP 서버 아이콘을 클릭합니다.
  2. MCP 서버 구성을 클릭하여 구성 파일을 엽니다.
  3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.
{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
  1. 서버가 성공적으로 연결되면 녹색 활성 상태가 표시됩니다.

Claude Desktop

  1. Claude Desktop을 열고 설정으로 이동합니다.
  2. 개발자 탭에서 구성 수정을 클릭하여 구성 파일을 엽니다.
  3. 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.
{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
  1. Claude Desktop을 다시 시작합니다.
  2. 새 채팅 화면에 새 MCP 서버와 함께 망치(MCP) 아이콘이 표시됩니다.

Claude code

  1. Claude Code를 설치합니다.
  2. 프로젝트 루트에 .mcp.json 파일이 없으면 이 파일을 만듭니다.
  3. 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.
{
  "mcpServers": {
    "alloydbomni": {
      "command": "PATH_TO_TOOLBOX",
      "args": ["--prebuilt","postgres","--stdio"],
      "env": {
        "POSTGRES_HOST": "DATABASE_HOST",
        "POSTGRES_PORT": "DATABASE_PORT",
        "POSTGRES_DATABASE": "DATABASE_NAME",
        "POSTGRES_USER": "DATABASE_USER",
        "POSTGRES_PASSWORD": "DATABASE_PASSWORD"
      }
    }
  }
}
  1. Claude 코드를 다시 시작하여 새 구성을 적용합니다.