Build contexts using Gemini CLI

This document describes how to use the Gemini CLI and the MCP toolbox to build agent context files. These files contain templates and facets that provide context for generating SQL queries from natural language. You will also use the DB Context Enrichment MCP Server.

To build agent context, perform the following high-level steps:

• Prepare your environment
• Generate targeted templates
• Generate targeted facets
• Optional. Generate bulk templates

Before you begin

Complete the following prerequisites before creating an agent.

Prepare a Cloud SQL instance

• Make sure that you have access to an existing Cloud SQL instance or create a new one. For more information, see Create instances for Cloud SQL.
• Populate the database with the data and schema that the end user wants to access.

Required roles and permissions

• Add an IAM user or service account to the instance. For more information, see Manage users with IAM database authentication for Cloud SQL.
• Grant the cloudsql.studioUser and cloudsql.instanceUser roles to the IAM user at the project level. For more information, see Add IAM policy binding for a project.
You must also grant database privileges to an IAM user or service account. For more information, see [Grant database privileges to an individual IAM user or service account](/sql/docs/postgres/add-manage-iam-users#grant-db-privileges).You must also grant database privileges to an IAM user or service account. For more information, see Grant database privileges to an individual IAM user or service account.

Grant executesql permission to Cloud SQL instance

gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

Prepare your environment

You can build agent context files from any any local development environment or IDE. To prepare the environment, perform the following steps:

• Install Gemini CLI
• Install and setup MCP toolbox
• Install and setup the DB Context Enrichment MCP Server

Install Gemini CLI

To install Gemini CLI, see Get Started with Gemini CLI. Make sure that you install Gemini CLI in a separate directory, which is also used to install the MCP toolbox and the DB Context Enrichment MCP Server.

Install and setup MCP toolbox

1. In the same directory where you installed Gemini CLI, install the MCP Toolbox Gemini CLI extension:

   gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

2. Create a tools.yaml configuration file in the same directory where you installed the MCP toolbox for configuring the database connection:

     sources:
       my-cloud-sql-pg-source:
         kind: cloud-sql-postgres
         project: PROJECT_ID
         region: REGION_ID
         instance: INSTANCE_ID
         database: DATABASE_ID
         user: USER_NAME
         password: PASSWORD
   

   Replace the following:

   • PROJECT_ID: Your Google Cloud project ID.
   • REGION_ID: The region of your Cloud SQL instance (e.g., us-central1).
   • INSTANCE_ID: The ID of your Cloud SQL instance.
   • DATABASE_ID: The name of the database to connect to.
   • USER_NAME: The database user. For more information about how to set this value, see Sources in MCP toolbox.
   • PASSWORD: The password for the database user. For more information about how to set this value, see Sources in MCP toolbox.

3. Verify that the tools.yaml file is configured correctly:

   ./toolbox --tools-file "tools.yaml"

Install DB Context Enrichment MCP Server

The DB Context Enrichment MCP Server provides a guided, interactive workflow to generate structured NL2SQL templates from your database schemas. It relies on the MCP Toolbox extension for database connectivity. For more information about installing the DB Context Enrichment MCP Server, see DB Context Enrichment MCP Server.

To install the DB Context Enrichment MCP Server, do the following:

1. In the same directory where you installed Gemini CLI, install uv Python package installer.

     pip install --user pipx
     pipx ensurepath
     pipx install uv

2. Install the DB Context Enrichment MCP Server.

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

The server uses Gemini API for generation. Make sure that you export your API key as an environment variable. For more information about how to find your API key, see Using Gemini API keys.

To export the Gemini API key, run the following command:

export GEMINI_API_KEY="YOUR_API_KEY"

Replace YOUR_API_KEY with your Gemini API key.

Generate targeted templates

If you want to add a specific query pair as a query template to the agent context, then you can use the /generate_targeted_templates command. For more information about templates, see Data agents overview.

To add a query template to the agent context, perform the following steps:

1. In the same directory where you installed Gemini CLI, start Gemini:

   gemini

2. Complete the Gemini CLI Authentication Setup.

3. Verify that the MCP toolbox and the database enrichment extension are ready to use:

   /mcp list

4. Run the /generate_targeted_templates command:

   /generate_targeted_templates

5. Enter the natural language query that you want to add to the query template.

6. Enter the corresponding SQL query to the query template.

7. Review the generated query template. You can either save the query template as an agent context file or append it to an existing context file.

The agent context file similar to my-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the context file and the query template, see Agent context.

Generate targeted facets

If you want to add a specific query pair as a facet to the agent context file, then you can use the /generate_targeted_fragments command. For more information about facets, see Data agents overview.

To add a facet to the agent context, perform the following steps:

1. Run the /generate_targeted_fragments command:

   /generate_targeted_fragments

2. Enter the natural language query that you want to add to the query template.

3. Enter the corresponding SQL query to the query template.

4. Review the generated facet. You can either save the facet to an agent context file or append it to an existing context file.

The agent context file similar to my-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the context file and facets, see Agent context.

Optional: Generate bulk templates

If you want to auto-generate the agent context file based on your database schema and data, then you can use the /generate_bulk_templates command.

To auto-generate bulk templates, perform the following steps:

1. Run the /generate_bulk_templates command:

   /generate_bulk_templates

2. Based on your database schema, the template-based SQL generation takes you through a series of questions related to verifying the database information and granting permissions to access the database schema.

3. Review the generated query template. You can either approve the template or update a query pair that you want to revise.

4. Enter the natural language query that you want to add to the query template.

5. Enter the corresponding SQL query to the query template.

6. Review the generated query template. You can either save the query template as an agent context file or append it to an existing context file.

7. After you approve the query template, you can either create a new template file or append the query pairs to an existing template file. The query template is saved as a JSON file in your local directory.

The agent context file similar to my-cluster-psc-primary_postgres_templates_20251104111122.json is saved in the directory where you ran the commands.

For more information about the agent context file, see Agent context.

What's next

• Learn more about data agents.
• Learn how to create or delete a data agent in Cloud SQL Studio.
• Learn how to inspect and call a data agent.