Usa Cloud SQL para PostgreSQL con MCP, la CLI de Gemini y otros agentes

En esta página, se muestra cómo conectar tu instancia de Cloud SQL a varias herramientas de asistencia para desarrolladores de IA, incluidas las siguientes:

Para una experiencia integrada, recomendamos usar la extensión de la CLI de Gemini dedicada para Cloud SQL para PostgreSQL.

Como interfaz de línea de comandos de próxima generación de As Google Cloud, Gemini CLI incluye el servidor de MCP subyacente directamente en la extensión, lo que simplifica la configuración. Puedes configurar Gemini Code Assist para que use la CLI de Gemini, lo que ofrece beneficios de configuración similares en tu IDE.

En el caso de otras herramientas para desarrolladores que admiten el Protocolo de contexto del modelo (MCP), puedes conectarte configurando manualmente la caja de herramientas del MCP para bases de datos (caja de herramientas). Toolbox es un servidor de MCP de código abierto que conecta agentes de IA a tus datos administrando tareas como la autenticación y la agrupación de conexiones. Esto te permite interactuar con tus datos usando lenguaje natural directamente desde tu IDE. Para estas herramientas, este método proporciona capacidades centrales de interacción con la base de datos.

Para obtener más información, consulta Herramientas prediseñadas y MCP Toolbox for Databases en GitHub.

Acerca de Gemini CLI y las extensiones

La CLI de Gemini es un agente de IA de código abierto diseñado para ayudar con los flujos de trabajo de desarrollo, ya que asiste con la programación, la depuración, la exploración de datos y la creación de contenido. Proporciona una interfaz basada en agentes para interactuar con servicios de bases de datos y análisis, y bases de datos populares de código abierto.

Cómo funcionan las extensiones

Gemini CLI es altamente extensible, lo que permite agregar nuevas herramientas y capacidades a través de extensiones. Puedes cargar las extensiones desde una URL de GitHub, un directorio local o un registro configurable. Proporcionan nuevas herramientas, comandos de barra y mensajes para ayudarte con tu flujo de trabajo.

Usa las extensiones de la CLI de Gemini en Cloud SQL para PostgreSQL

La extensión de Gemini CLI de Cloud SQL se basa en la caja de herramientas de MCP para bases de datos. Actualmente, MCP Toolbox for Databases se encuentra en versión beta (anterior a la versión 1.0) y es posible que sufra cambios que interrumpan su funcionamiento hasta el lanzamiento de la primera versión estable (v1.0).

La integración con Gemini CLI se realiza a través de una extensión dedicada que ofrece capacidades adicionales en comparación con la conexión estándar de la Caja de herramientas. La extensión ofrece un proceso de instalación optimizado y un conjunto de herramientas.

Para obtener más información, consulta la documentación de GitHub sobre la extensión de la CLI de Gemini para Cloud SQL para PostgreSQL.

Extensión de la CLI de Gemini para bases de datos de Cloud SQL para PostgreSQL

La extensión cloud-sql-postgresql incluye herramientas para consultar la base de datos, administrar recursos de Cloud SQL y supervisar el estado de la base de datos.

Categoría Herramientas
Operaciones de bases de datos
  • list_tables: Enumera todas las tablas y sus descripciones correspondientes que se encuentran en una base de datos.
  • execute_sql: Ejecuta cualquier instrucción de SQL.
  • list_active_queries: Enumera las consultas que se están ejecutando en una instancia de Cloud SQL.
  • list_available_extensions: Enumera las extensiones de PostgreSQL disponibles para la instalación en una instancia de Cloud SQL.
  • list_installed_extensions: Enumera las extensiones de PostgreSQL instaladas en una instancia de Cloud SQL.
  • get_query_plan: Obtiene el plan de consultas para una sola instrucción de una instancia de Cloud SQL.
Administración de recursos para instancias y usuarios
  • create_user: Crea un usuario nuevo en una instancia de Cloud SQL.
  • list_databases: Enumera todas las bases de datos de una instancia de Cloud SQL.
  • create_database: Crea una base de datos nueva dentro de una instancia de Cloud SQL.
  • list_instances: Enumera las instancias de Cloud SQL en un proyecto determinado.
  • get_instance: Obtén detalles sobre una instancia de Cloud SQL específica.
  • create_instance: Crea una nueva instancia de Cloud SQL.
  • wait_for_operation: Sondea la API de Operations hasta que se completa una operación.
Estado y mantenimiento de la base de datos
  • list_autovacuum_configurations: Enumera la configuración de autovacuum en una instancia de Cloud SQL. Las operaciones de VACUUM quitan las tuplas inactivas para liberar espacio en el disco, evitar la expansión de la tabla y mejorar el rendimiento de lectura y escritura.
  • list_memory_configurations: Enumera la configuración de memoria a nivel de la instancia en una instancia de Cloud SQL. Muestra parámetros como shared_buffers y work_mem para ayudarte a evaluar y optimizar la asignación de recursos para la ejecución y el almacenamiento en caché de consultas.
  • list_top_bloated_tables: Enumera las tablas de una instancia de Cloud SQL con la mayor cantidad de espacio sin usar (inflación). Esta información puede ayudarte a programar el mantenimiento, como la limpieza o la reindexación, para recuperar espacio en el disco y mejorar la velocidad de las búsquedas.
  • list_replication_slots: Enumera los detalles de la ranura de replicación, como el registro previo a la escritura (WAL) en una instancia de Cloud SQL. Ayuda a la administración y solución de problemas relacionados con la replicación.
  • list_invalid_indexes: Enumera los índices no válidos en una instancia de Cloud SQL. Puedes usar esta información para volver a compilar o descartar índices no válidos y mejorar el rendimiento de las consultas.

La extensión cloud-sql-postgresql-observability proporciona una interfaz unificada para administrar y supervisar el rendimiento y el estado de la base de datos directamente desde la CLI de Gemini.

Categoría Herramientas
Observabilidad
  • get_system_metrics: Recupera las métricas del sistema para una instancia de Cloud SQL.
  • get_query_metrics: Recupera métricas relacionadas con las consultas para una instancia de Cloud SQL.

Extensión de Gemini CLI para bases de datos de PostgreSQL

Para obtener una lista de esas operaciones, consulta MCP Toolbox for Databases y Extensión de la CLI de Gemini para PostgreSQL.

Antes de comenzar

Instala MCP Toolbox

  1. Para instalar la caja de herramientas, descarga el objeto binario que corresponda a tu sistema operativo y a la arquitectura de 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. Haz que el objeto binario sea ejecutable:

    chmod +x toolbox

  3. Verifica la instalación con el siguiente comando:

    ./toolbox --version

Configura el cliente de MCP

En esta sección, se describe cómo configurar varias herramientas para desarrolladores para conectarse a tu instancia de Cloud SQL con Toolbox. Toolbox actúa como un servidor de Protocolo de contexto del modelo (MCP) de código abierto que se encuentra entre tu IDE y tu base de datos, y proporciona un plano de control seguro y eficiente para tus herramientas de IA. Selecciona la pestaña de tu herramienta específica para ver las instrucciones de configuración.

CLI de Gemini para Cloud SQL para PostgreSQL


  1. Instala Gemini CLI.
  2. Instala la extensión de Cloud SQL para PostgreSQL para la CLI de Gemini desde el repositorio de GitHub con el siguiente comando: 
      gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql
  3. Establece variables de entorno para conectarte a tu instancia de 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"
    Reemplaza lo siguiente:
    • PROJECT_NAME: ID del proyecto de Google Cloud
    • REGION: Es la región de tu instancia de Cloud SQL.
    • INSTANCE_NAME: Es el ID de tu instancia de Cloud SQL.
    • DATABASE_NAME: El nombre de la base de datos a la que te conectarás.
    • DATABASE_USER_NAME: Opcional: Es el nombre de usuario de la base de datos. Si no se especifica, se usa la autenticación de IAM de forma predeterminada.
    • PASSWORD: Opcional: Es la contraseña del usuario de la base de datos. Si no se especifica, se usa la autenticación de IAM de forma predeterminada.
    • IP_TYPE: Opcional: Es el tipo de IP, como "Pública" (predeterminado) o "Privada".
  4. Inicia la CLI de Gemini en modo interactivo: 
      gemini

    La CLI carga automáticamente la extensión de Gemini CLI para Cloud SQL y sus herramientas, que puedes usar para interactuar con tu base de datos.

    En la CLI de Gemini, usa el comando /extensions para verificar que la extensión esté instalada y el comando /mcp list para ver las herramientas.

Gemini CLI para PostgreSQL


 1. Instala la CLI de Gemini.
2. Instala la extensión de software de PostgreSQL para Gemini CLI desde el repositorio de GitHub con el siguiente comando: 
      gemini extensions install https://github.com/gemini-cli-extensions/postgres
3. Configura variables de entorno para conectarte a tu instancia de 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"
Reemplaza lo siguiente:
  • HOST: Es el nombre de host o la dirección IP del servidor de PostgreSQL.
  • PORT: Es el número de puerto del servidor de PostgreSQL.
  • DATABASE: El nombre de la base de datos a la que te conectarás.
  • USER: Es el nombre de usuario de la base de datos.
  • PASSWORD: Es la contraseña del usuario de la base de datos.
  • QUERY_PARAMETERS: Opcional: Es la consulta sin procesar que se agregará a la cadena de conexión db.
4. Inicia la CLI de Gemini en modo interactivo: 
      gemini

La CLI carga automáticamente la extensión de Gemini CLI para PostgreSQL y sus herramientas, que puedes usar para interactuar con tu base de datos.

Gemini Code Assist


 1. Instala la extensión de Gemini Code Assist en Visual Studio Code.
2. Habilita el modo de agente en el chat de Gemini Code Assist.
3. En tu directorio de trabajo, crea una carpeta llamada .gemini. Dentro de él, crea un archivo settings.json.
4. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y, luego, guarda:


{
  "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. Instala Claude Code.
2. Crea el archivo .mcp.json en la raíz de tu proyecto si no existe.
3. Agrega la configuración, reemplaza las variables de entorno por tus valores y guarda: 


{
  "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 para computadoras de escritorio


 1. Abre Claude Desktop y navega a Configuración.
2. En la pestaña Desarrollador, presiona Editar configuración para abrir el archivo de configuración.
3. Agrega la configuración, reemplaza las variables de entorno por tus valores y guarda: 


{
  "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. Reinicia Claude para computadoras.
6. En la nueva pantalla de chat, se muestra un ícono de martillo (MCP) con el nuevo servidor de MCP disponible.

Cline


 1. Abre la extensión Cline en VS Code y presiona el ícono de Servidores de MCP.
2. Presiona Configure MCP Servers para abrir el archivo de configuración.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda: 


{
  "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. Aparece un estado activo verde después de que el servidor se conecta correctamente.

Cursor


 1. Crea el directorio .cursor en la raíz del proyecto si no existe.
2. Crea el archivo .cursor/mcp.json si no existe y ábrelo.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda:


{
  "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. Abre Cursor y navega a Configuración > Configuración del cursor > MCP. Cuando el servidor se conecta, aparece un estado activo de color verde.

Visual Studio Code (Copilot)


 1. Abre VS Code y crea el directorio .vscode en la raíz de tu proyecto si no existe.
2. Crea el archivo .vscode/mcp.json si no existe y ábrelo.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda: 


{
  "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. Abre Windsurf y navega al asistente de Cascade.
2. Presiona el ícono de MCP y, luego, Configurar para abrir el archivo de configuración.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda: 


{
  "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"
      }
    }
  }
}