> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Provision and query CockroachDB clusters from Guild agents

> Connect Guild agents to CockroachDB Cloud through the Cloud API for clusters, users, and backups, or the managed MCP server for SQL.

Integrations · CockroachDB

Guild agents create and scale CockroachDB Cloud clusters, manage databases and SQL users, control network access, and trigger backups. They can also inspect schemas and run SQL through CockroachDB Cloud's managed MCP server. Guild offers two CockroachDB integrations: one for the Cloud API, one for the MCP server. Both keep your credential server-side, and credential policies decide which operations each agent may call.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use CockroachDB.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect CockroachDB to your first agent.

## Choose an integration

Both integrations reach CockroachDB Cloud. They differ in what they cover.

| | CockroachDB | CockroachDB MCP |
| - | - | - |
| Integration | `guildlabs~cockroachdb` | `guildlabs~cockroachdb-mcp` |
| Calls | The CockroachDB Cloud API | CockroachDB Cloud's managed MCP server at `https://cockroachlabs.cloud/mcp` |
| Covers | Clusters, databases, SQL users, IP allowlists, maintenance windows, version deferral, backups and restores, invoices, folders, and audit logs | Clusters and databases, table schemas, query plans, running queries, and SQL statements |
| Runs SQL | Only through the `cockroachdb_mcp_call` passthrough | `SELECT`, `EXPLAIN`, `SHOW`, `CREATE TABLE`, and `INSERT`, one statement per call |
| Tools | `cockroachdb_` prefix, from `CockroachdbTools` | From `CockroachdbMcpTools` |

Use **CockroachDB** when an agent administers clusters: provisioning, scaling, users, network access, or backups. Use **CockroachDB MCP** for an agent that reads or writes data, so it gets a typed tool for each SQL operation instead of a raw JSON-RPC passthrough.

## How it works

**1. Create a CockroachDB Cloud service account**

In the CockroachDB Cloud Console, create a service account with an API key. Give it only the roles your agent needs. Each tool lists the roles it requires.

**2. Connect the credential in Guild**

Go to **Access & setup > Credentials**, click **Connect**, select **cockroachdb** or **cockroachdb-mcp**, and paste the key into **API Key**.

**3. Import tools and pick what you need**

Import the integration's tools and use [`pick()`](https://docs.guild.ai/sdk/tools) to include only the tools your agent needs.

## Why CockroachDB access needs governing

CockroachDB tools can delete clusters and all their data, drop databases, remove SQL users, modify IP allowlists, and write rows. Guild's credential proxy enforces [credential policies](https://docs.guild.ai/platform/credential-policies.md) before any request leaves the platform. You can write ALLOW and DENY rules that restrict which operations an agent may call, scope rules to specific agents or workspaces, and use wildcard patterns such as `*_delete` to block entire classes of destructive operations. The API key is injected server-side only after the policy check passes, so agents never handle the secret directly.

Guild logs every credential proxy call, giving you a record of which agent called which CockroachDB operation and when. You can tighten rules incrementally: start with the default allow-all policy while building, then delete it once your scoped rules cover everything agents should reach. At that point, any unmatched request is denied by default rather than passed through.

The service account's CockroachDB roles are a second limit. A key without write access can't run the MCP server's write tools, whatever your Guild policies allow.

## Authentication

* **Type:** API key from a CockroachDB Cloud service account
* **Header:** Guild sends the key as a bearer token in the `Authorization` header
* **Applies to:** both integrations

Each integration has its own credential. You can paste the same key into both.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

### CockroachDB

```typescript theme={null}
import { CockroachdbTools } from "@guildai-services/guildlabs~cockroachdb"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You report each cluster's version and whether an upgrade is available.",
  tools: {
    ...pick(CockroachdbTools, [
      "cockroachdb_list_clusters",
      "cockroachdb_get_cluster",
      "cockroachdb_list_cluster_versions",
    ]),
  },
})
```

### CockroachDB MCP

```typescript theme={null}
import { CockroachdbMcpTools } from "@guildai-services/guildlabs~cockroachdb-mcp"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You answer questions about the orders database with read-only SQL.",
  tools: {
    ...pick(CockroachdbMcpTools, [
      "cockroachdb_mcp_list_tables",
      "cockroachdb_mcp_get_table_schema",
      "cockroachdb_mcp_select_query",
    ]),
  },
})
```

## Tools

### CockroachDB tools

Tools in the latest published version of `guildlabs~cockroachdb`:

> [accordion] All 39 tools
>
> | Tool | What it does |
> | - | - |
> | `cockroachdb_add_allowlist_entry` | Add a new CIDR address to the IP allowlist |
> | `cockroachdb_create_cluster` | Create and initialize a new cluster |
> | `cockroachdb_create_database` | Create a new database |
> | `cockroachdb_create_restore` | Create a restore |
> | `cockroachdb_create_sql_user` | Create a new SQL user |
> | `cockroachdb_delete_allowlist_entry` | Delete an IP allowlist entry |
> | `cockroachdb_delete_cluster` | Delete a cluster and all of its data |
> | `cockroachdb_delete_database` | Delete a database |
> | `cockroachdb_delete_maintenance_window` | Delete the maintenance window for a cluster |
> | `cockroachdb_delete_sql_user` | Delete a SQL user |
> | `cockroachdb_get_backup_configuration` | Get the backup configuration for a cluster |
> | `cockroachdb_get_cluster` | Get extended information about a cluster |
> | `cockroachdb_get_connection_string` | Get a formatted generic connection string for a cluster |
> | `cockroachdb_get_folder` | Get folder info for a folder |
> | `cockroachdb_get_invoice` | Get a specific invoice for an organization |
> | `cockroachdb_get_maintenance_window` | Get the maintenance window for a cluster |
> | `cockroachdb_get_organization_info` | Get information about the caller's organization |
> | `cockroachdb_get_restore` | View a restore job |
> | `cockroachdb_get_version_deferral` | Get the version upgrade deferral policy for a cluster. |
> | `cockroachdb_list_allowlist_entries` | Get the IP allowlist and propagation status for a cluster |
> | `cockroachdb_list_audit_logs` | List audit logs |
> | `cockroachdb_list_available_regions` | List the regions available for new clusters and nodes |
> | `cockroachdb_list_backups` | List cluster backups |
> | `cockroachdb_list_cluster_nodes` | List nodes for a cluster |
> | `cockroachdb_list_clusters` | List clusters in the organization |
> | `cockroachdb_list_cluster_versions` | List available major cluster versions |
> | `cockroachdb_list_databases` | List databases for a cluster |
> | `cockroachdb_list_folder_contents` | List contents of a folder |
> | `cockroachdb_list_folders` | List folders owned by an organization |
> | `cockroachdb_list_invoices` | List invoices for a given organization |
> | `cockroachdb_list_restores` | List restore jobs |
> | `cockroachdb_list_sql_users` | List SQL users for a cluster |
> | `cockroachdb_mcp_call` | Low-level passthrough to CockroachDB Cloud's managed MCP server at [https://cockroachlabs.cloud/mcp](https://cockroachlabs.cloud/mcp). |
> | `cockroachdb_rename_database` | Update a database |
> | `cockroachdb_set_maintenance_window` | Set the maintenance window for a cluster |
> | `cockroachdb_set_version_deferral` | Set the version upgrade deferral policy for a cluster |
> | `cockroachdb_update_backup_configuration` | Update the backup configuration for a cluster |
> | `cockroachdb_update_cluster` | Scale, edit or upgrade a cluster |
> | `cockroachdb_update_sql_user_password` | Update a SQL user's password |

### CockroachDB MCP tools

Tools in the latest published version of `guildlabs~cockroachdb-mcp`:

| Tool | What it does |
| - | - |
| `cockroachdb_mcp_create_database` | Create a new database in the cluster |
| `cockroachdb_mcp_create_table` | Create a new table in a database using a CREATE TABLE DDL statement. |
| `cockroachdb_mcp_explain_query` | Show query execution plan without executing the query |
| `cockroachdb_mcp_get_cluster` | Get detailed information for the CockroachDB cluster |
| `cockroachdb_mcp_get_table_schema` | Get detailed schema information for a table including columns and indexes |
| `cockroachdb_mcp_insert_rows` | Insert rows into an existing table. |
| `cockroachdb_mcp_list_clusters` | List all CockroachDB clusters accessible to the authorized user |
| `cockroachdb_mcp_list_databases` | List all databases in the CockroachDB cluster. |
| `cockroachdb_mcp_list_tables` | List all tables in a database. |
| `cockroachdb_mcp_select_query` | Execute a read-only SELECT query on the CockroachDB cluster. |
| `cockroachdb_mcp_show_running_queries` | List currently executing queries on the cluster |
| `cockroachdb_mcp_show_statement` | Execute a SHOW statement for introspection (e.g., SHOW SCHEMAS, SHOW INDEXES, SHOW REGIONS, SHOW CONSTRAINTS). |

## Frequently asked questions

> [accordion] Which integration should an agent use to run SQL?
>
> **CockroachDB MCP**. It calls CockroachDB Cloud's managed MCP server directly. The **CockroachDB** integration can reach the same server through `cockroachdb_mcp_call`, but the agent has to build each JSON-RPC request and parse the event-stream response itself.

> [accordion] Can an agent write data?
>
> Yes, if the service account has write access. The MCP server can create databases and tables and insert rows. It doesn't run `DROP` or `TRUNCATE`, and it blocks system schemas. Each call runs one statement, with a 20-second timeout and a 10 KiB response cap.

> [accordion] Can I connect both CockroachDB integrations at once?
>
> Yes. Each integration has its own credential, and you can paste the same service account key into both.

> [accordion] How do I stop an agent from deleting clusters?
>
> Add a DENY rule in [credential policies](https://docs.guild.ai/platform/credential-policies.md) targeting the `cockroachdb_delete_cluster` operation, or use the wildcard pattern `*_delete` to block all delete-style operations. The credential proxy enforces the rule before the request reaches CockroachDB.

> [accordion] Can I give one agent a different CockroachDB key than the rest of my workspace?
>
> Yes. Connect a dedicated credential from the installed agent's detail page. Guild resolves that credential first for that agent and never uses it for other agents or workspaces. See [Credentials](https://docs.guild.ai/platform/credentials.md) for the full resolution order.

> [accordion] Does this integration receive webhook events from CockroachDB?
>
> No. Neither integration defines webhook events, so CockroachDB events can't trigger agents through Guild.

## Put a governed agent on CockroachDB Cloud this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use CockroachDB.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect CockroachDB to your first agent.

## Related

**Also runs on Guild:** [Airtable](https://docs.guild.ai/integrations/airtable.md) · [BigQuery](https://docs.guild.ai/integrations/bigquery.md) · [Hex](https://docs.guild.ai/integrations/hex.md) · [LlamaIndex](https://docs.guild.ai/integrations/llamaindex.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)
