Skip to content
30 changes: 14 additions & 16 deletions BIGQUERY.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,22 @@

To install this extension, the Gemini CLI version must be v0.6.0 or above. The version can be found by running: `gemini --version`.

## BigQuery MCP Server (Data Plane: Connecting and Querying)
## BigQuery Skills (Data Plane: Connecting and Querying)

This section covers connecting to a BigQuery instance.
This section covers connecting to BigQuery.

1. **Verify Environment Variables**: Before attempting to connect, confirm with the user that the following environment variables are set in the extension configuration or their shell environment.
1. **Extension Configuration**: This extension requires several settings (e.g., Project ID, Location). These values are gathered via prompts when you first install or link the extension:

* `BIGQUERY_PROJECT`: The GCP project ID.
* `BIGQUERY_PROJECT`: The GCP project ID.
* `BIGQUERY_LOCATION`: (Optional) Location of the BigQuery resources.

2. **Handle Missing Variables**: If a command fails with an error message containing a placeholder like `${BIGQUERY_PROJECT}`, it signifies a missing environment variable. Inform the user which variable is missing and instruct them to set it.
If you need to update any of these values later, use the `gemini extensions config bigquery-data-analytics` command.

3. **Handle Permission Errors**:
* For operations that execute queries and view metadata, the user needs the
**BigQuery User** (`roles/bigquery.user`) and **BigQuery Metadata Viewer** (`roles/bigquery.metadataViewer`) role.
* For operations that create, or modify datasets and tables, the user neds
the **BigQuery Data Editor** (`roles/bigquery.dataEditor`) role.
* If an operation fails due to permissions, identify the type of operation
and recommend the appropriate role. you can provide these links for
assistance:
* Granting Roles: https://cloud.google.com/iam/docs/grant-role-console
* BigQuery Permissions:
https://cloud.google.com/iam/docs/roles-permissions/bigquery
2. **Handle Missing Variables**: If a command fails with an error message containing a placeholder like `${BIGQUERY_PROJECT}`, it signifies a missing environment variable. Inform the user which variable is missing and instruct them to set it.

3. **Handle Permission Errors**:
* For operations that execute queries and view metadata, the user needs the **BigQuery User** (`roles/bigquery.user`) and **BigQuery Metadata Viewer** (`roles/bigquery.metadataViewer`) role.
* For operations that create, or modify datasets and tables, the user needs the **BigQuery Data Editor** (`roles/bigquery.dataEditor`) role.
* If an operation fails due to permissions, identify the type of operation and recommend the appropriate role. You can provide these links for assistance:
* Granting Roles: https://cloud.google.com/iam/docs/grant-role-console
* BigQuery Permissions: https://cloud.google.com/iam/docs/roles-permissions/bigquery
43 changes: 10 additions & 33 deletions DEVELOPER.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ Before you begin, ensure you have the following:
1. **Gemini CLI:** Install the Gemini CLI version v0.6.0 or above. Installation
instructions can be found on the official Gemini CLI documentation. You can
verify your version by running `gemini --version`.
2. **BigQuery Access** For testing data plane tools, you will need access to an active BigQuery dataset.
2. **BigQuery Access** For testing data plane skills, you will need access to an active BigQuery dataset.

## Developing the Extension

### Running from Local Source

The core logic for this extension is handled by a pre-built `toolbox` binary. The development process involves installing the extension locally into the Gemini CLI to test changes.
The development process involves installing the extension locally into the Gemini CLI to test changes.

1. **Clone the Repository:**

Expand All @@ -25,29 +25,16 @@ The core logic for this extension is handled by a pre-built `toolbox` binary. Th
cd bigquery-data-analytics
```

2. **Download the Toolbox Binary:** The required version of the `toolbox` binary
is specified in `toolbox_version.txt`. Download it for your platform.

```bash
# Read the required version
VERSION=$(cat toolbox_version.txt)

# Example for macOS/amd64
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/geminicli/v$VERSION/darwin/amd64/toolbox
chmod +x toolbox
```
Adjust the URL for your operating system (`linux/amd64`, `darwin/arm64`, `windows/amd64`).

3. **Link the Extension Locally:** Use the Gemini CLI to install the
2. **Install the Extension Locally:** Use the Gemini CLI to install the
extension from your local directory.

```bash
gemini extensions link .
gemini extensions install .
```
The CLI will prompt you to confirm the linking. Accept it to proceed.
The CLI will prompt you to confirm the installation. Accept it to proceed.

4. **Testing Changes:** After linking, start the Gemini CLI (`gemini`).
You can now interact with the `bigquery-data-analytics` tools to manually test your changes
3. **Testing Changes:** After installing, start the Gemini CLI (`gemini`).
You can now interact with the `bigquery-data-analytics` skills to manually test your changes
against your connected database.

## Testing
Expand All @@ -59,7 +46,7 @@ for every pull request. This workflow primarily verifies that the extension can
be successfully installed by the Gemini CLI.

Currently, there are no automated unit or integration test suites
within this repository. All functional testing must be performed manually. All tools
within this repository. All functional testing must be performed manually. All skills
are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/mcp-toolbox).

### Other GitHub Checks
Expand All @@ -75,14 +62,8 @@ are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/m

## Building the Extension

The "build" process for this extension involves packaging the extension's
metadata files (`gemini-extension.json`, `bigquery-data-analytics.md`, `LICENSE`) along with the
pre-built `toolbox` binary into platform-specific archives (`.tar.gz` or `.zip`).

This process is handled automatically by the
[`package-and-upload-assets.yml`](.github/workflows/package-and-upload-assets.yml)
GitHub Actions workflow when a new release is created. Manual building is not
required.
The building process for this extension is handled automatically by the
automated workflows when a new release is created. Manual building is not required.

## Maintainer Information

Expand Down Expand Up @@ -135,7 +116,3 @@ The process is handled by the [`mirror-changelog.yml`](.github/workflows/mirror-
2. **Merge Release PR:** A maintainer approves and merges the Release PR. This
action triggers `release-please` to create a new GitHub tag and a
corresponding GitHub Release.
3. **Package and Upload:** The new release triggers the
`package-and-upload-assets.yml` workflow. This workflow builds the
platform-specific extension archives and uploads them as assets to the
GitHub Release.
Loading
Loading