CockroachDB Cloud

CockroachDB Cloud is Cockroach Labs' fully managed, distributed SQL database service. Its Cloud API is a REST interface for administering your CockroachDB Cloud organization — provisioning and scaling clusters, managing databases, SQL users, backups and restores, IAM roles and service accounts, billing, and cluster networking. This connector uses the Cloud API to read organization and cluster metadata into Nexla and to drive management operations from your data flows.

Power end-to-end data operations for your CockroachDB Cloud API with Nexla. Our bi-directional CockroachDB Cloud connector is purpose-built for CockroachDB Cloud, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to CockroachDB Cloud or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your CockroachDB Cloud workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

• Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
• Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
• API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
• Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites

The CockroachDB Cloud API authenticates with a service-account API key, sent as a Bearer token in the Authorization header. The base URL for all requests is https://cockroachlabs.cloud/api/v1/. Before creating a credential in Nexla, create a service account in the CockroachDB Cloud Console and generate an API key for it. The secret key inherits the permissions of the service account, so grant the account only the roles it needs for your use case.

To create a service account and generate an API key, follow these steps:

1. Sign in to the CockroachDB Cloud Console at console.cockroachlabs.cloud with an account that has permission to manage access.

2. Open the Access Management page from the left navigation, and select the Service Accounts tab.

3. Click Create, enter an Account name and an optional Description, and assign the roles the service account requires.

4. Confirm creation to open the new account's Service Account Details page.

5. Click Create API Key, enter an API key name, and click Create.

6. Copy the Secret key immediately using the Copy button, and store it securely.

   warning

   The secret key is shown only once and is not available after you close the Create API Key dialog. If the secret key is lost, delete the API key and create a new one. Treat the secret key as a sensitive credential — it should never be shared or made publicly accessible.

For complete information about creating service accounts, managing roles, and generating API keys, see the CockroachDB Cloud API documentation and the Managing Access guide.

Authenticate

Credentials required

CockroachDB Cloud authenticates with a service-account API key as a Bearer token. Create one at console.cockroachlabs.cloud > Access > Service Accounts.

Field	Required	Secret	Description
API Key	Yes	Yes	CockroachDB Cloud service-account API key (Bearer token). Generated once at creation time in the Cloud Console.

Create a credential in Nexla

1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

3. Enter your CockroachDB Cloud service-account API key in the API Key field. Nexla sends this value as a Bearer token in the Authorization header of every request to the Cloud API, so it must be kept confidential.

   The API key inherits the permissions of the service account it belongs to. If a request returns an authorization error, verify that the service account has been granted the roles required for the resource you are accessing.

4. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the CockroachDB Cloud connector tile, then select the credential that will be used to connect to CockroachDB Cloud, and click Next; or, create a new CockroachDB Cloud credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common CockroachDB Cloud endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

[Rest API] Get Organization

Get information about the caller's organization. Use this template to retrieve the organization details associated with your API key.

[Rest API] List Clusters

List clusters in the organization. Use this template to retrieve all clusters your service account can access, including their identifiers used by the cluster-scoped endpoints below.

[Rest API] Get Cluster

Get extended information about a single cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] List Cluster Nodes

List the nodes for a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] List Databases

List the databases for a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] List Backups

List the backups for a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] Get Backup Configuration

Get the backup configuration for a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] List Restore Jobs

List the restore jobs for a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] Get Restore Job

View a single restore job.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.
• Enter the Restore Job ID, the restore job UUID within the cluster obtained from the List Restore Jobs endpoint.

[Rest API] List SQL Users

List the SQL users for a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] List Cluster Versions

List the available major cluster versions.

[Rest API] List Available Regions

List the regions available for new clusters and nodes.

[Rest API] List API Keys

List the API keys for the organization.

[Rest API] List Service Accounts

List the service accounts for the organization.

[Rest API] List Invoices

List the invoices for the organization.

[Rest API] Get Invoice

Get a specific invoice for the organization.

• Enter the Invoice ID, the invoice UUID obtained from the List Invoices endpoint.

[Rest API] List Folders

List the folders owned by the organization.

[Rest API] List Audit Logs

List the organization audit log entries.

[Rest API] List Role Grants

List all role grants in the organization.

[Rest API] List IP Allowlist

Get the IP allowlist and propagation status for a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration

CockroachDB Cloud data sources can also be manually configured to ingest data from any valid Cloud API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new CockroachDB Cloud data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination

Click the + icon on the Nexset that will be sent to the CockroachDB Cloud destination, and select the Send to Destination option from the menu. Select the CockroachDB Cloud connector from the list of available destination connectors, then select the credential that will be used to connect to CockroachDB Cloud, and click Next; or, create a new CockroachDB Cloud credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common CockroachDB Cloud endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings. Each record from the Nexset is sent as the JSON request body of a separate API call.

[Rest API] Create Cluster

Create and initialize a new CockroachDB Cloud cluster. Each Nexset record supplies the new cluster specification in the request body.

[Rest API] Update Cluster

Scale, edit, or upgrade an existing cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] Create Database

Create a new database on a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] Update Database

Rename an existing database on a cluster. The current name and new name are supplied in the request body (name and new_name), not the URL path.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] Create Restore

Create a restore job into the destination cluster.

• Enter the Destination Cluster ID, the UUID of the cluster to restore into.

[Rest API] Create SQL User

Create a new SQL user for a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID.

[Rest API] Update SQL User Password

Update a SQL user's password.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.
• Enter the SQL Username, the SQL user name within the cluster.

[Rest API] Update Backup Configuration

Update the backup configuration for a cluster.

• Enter the Cluster ID, the CockroachDB Cloud cluster UUID obtained from the List Clusters endpoint.

[Rest API] Create API Key

Create a new organization API key. Each Nexset record supplies the API key specification in the request body.

[Rest API] Create Service Account

Create a new service account for the organization.

[Rest API] Add Role Grant

Add a role to a user or service account on a resource.

• Enter the User ID, the user or service-account UUID.
• Enter the Resource Type, the role-grant resource type (for example, cluster, folder, or organization).
• Enter the Resource ID, the UUID of the resource the role grant applies to.
• Enter the Role Name, the name of the role to grant.

[Rest API] Create Folder

Create a folder for organizing clusters.

Manual configuration

CockroachDB Cloud destinations can also be manually configured to send data to any valid Cloud API endpoint. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

The CockroachDB Cloud API expects JSON request bodies for create and update operations, and is rate-limited to 10 requests per second per user. For detailed request and response formats, see the CockroachDB Cloud API documentation.

Save & activate

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured CockroachDB Cloud endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to the CockroachDB Cloud endpoint until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.