ClickHouse Cloud React Hooks

A collection of reusable React hooks to interact with the ClickHouse Cloud API: https://clickhouse.com/docs/cloud/manage/api/api-overview

Roadmap

The project is under active development and aims to cover the following ClickHouse Cloud API endpoints.

src/hooks/useOrganizations.ts

• [x] GET /v1/organizations — useOrganizations
  Returns a list with a single organization associated with the API key in the request.
• [x] GET /v1/organizations/{organizationId} — useOrganization
  Returns details of a single organization. In order to get the details, the auth key must belong to the organization.
• [x] PATCH /v1/organizations/{organizationId} — useUpdateOrganization
  Updates organization fields. Requires ADMIN auth key role.
• [ ] GET /v1/organizations/{organizationId}/privateEndpointConfig — useOrganizationPrivateEndpointConfig Information required to set up a private endpoint for region within cloud provider for an organization.
• [ ] GET /v1/organizations/{organizationId}/usageCost — useOrganizationUsageCost Returns a grand total and a list of daily, per-entity organization usage cost records for the organization in the queried time period (maximum 31 days).

src/hooks/useOrganizationActivities.ts

• [!] GET /v1/organizations/{organizationId}/activities — useOrganizationActivities
  Returns a list of all organization activities.
• [!] GET /v1/organizations/{organizationId}/activities/{activityId} — useOrganizationActivity Returns a single organization activity by ID.

src/hooks/usePrometheusMetrics.ts

• [ ] GET /v1/organizations/{organizationId}/prometheus — useOrganizationPrometheusMetrics
  Returns prometheus metrics for all services in an organization.

src/hooks/useServices.ts

• [ ] GET /v1/organizations/{organizationId}/services — useServices
  Returns a list of all services in the organization.
• [ ] POST /v1/organizations/{organizationId}/services — useCreateService
  Creates a new service in the organization, and returns the current service state and a password to access the service. The service is started asynchronously.
• [ ] GET /v1/organizations/{organizationId}/services/{serviceId} — useService
  Returns a service that belongs to the organization.
• [ ] PATCH /v1/organizations/{organizationId}/services/{serviceId} — useUpdateService
  Updates basic service details like service name or IP access list.
• [ ] DELETE /v1/organizations/{organizationId}/services/{serviceId} — useDeleteService
  Deletes the service. The service must be in stopped state and is deleted asynchronously after this method call.
• [!] GET /v1/organizations/{organizationId}/services/{serviceId}/privateEndpointConfig — useServicePrivateEndpointConfig
  Information required to set up a private endpoint.
• [!] GET /v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint — useServiceQueryEndpoint
  Get the service query endpoint for a given instance. Experimental feature.
• [!] DELETE /v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint — useServiceQueryEndpoint
  Delete the service query endpoint for a given instance. Experimental feature.
• [!] POST /v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint — useServiceQueryEndpoint
  Upsert the service query endpoint for a given instance. Experimental feature.
• [!] PATCH /v1/organizations/{organizationId}/services/{serviceId}/state — useUpdateServiceState
  Starts or stops service.
• [!] PATCH /v1/organizations/{organizationId}/services/{serviceId}/scaling — useUpdateServiceTier
  Updates minimum and maximum total memory limits and idle mode scaling behavior for the service. Deprecated.
• [!] PATCH /v1/organizations/{organizationId}/services/{serviceId}/replicaScaling — useServiceReplicaScaling
  Updates minimum and maximum memory limits per replica and idle mode scaling behavior for the service.
• [!] PATCH /v1/organizations/{organizationId}/services/{serviceId}/password — useResetServicePassword
  Sets a new password for the service.
• [!] POST /v1/organizations/{organizationId}/services/{serviceId}/privateEndpoint — useCreateServicePrivateEndpoint
  Create a new private endpoint. The private endpoint will be associated with this service and organization.

src/hooks/usePrometheusMetrics.ts

• [ ] GET /v1/organizations/{organizationId}/services/{serviceId}/prometheus — useServicePrometheusMetrics
  Returns prometheus metrics for a service.

src/hooks/useBackups.ts

• [ ] GET /v1/organizations/{organizationId}/services/{serviceId}/backups — useServiceBackups
  Returns a list of all backups for the service. The most recent backups comes first in the list.
• [ ] GET /v1/organizations/{organizationId}/services/{serviceId}/backups/{backupId} — useServiceBackup
  Returns a single backup info.
• [ ] DELETE /v1/organizations/{organizationId}/services/{serviceId}/backups/{backupId} — useDeleteServiceBackup
  Deletes a backup.
• [ ] GET /v1/organizations/{organizationId}/services/{serviceId}/backupConfiguration — useServiceBackupConfiguration
  Returns the service backup configuration.
• [ ] PATCH /v1/organizations/{organizationId}/services/{serviceId}/backupConfiguration — useUpdateServiceBackupConfiguration
  Updates service backup configuration. Requires ADMIN auth key role. Setting the properties with null value will reset the properties to their default values.

src/hooks/useApiKeys.ts

• [ ] GET /v1/organizations/{organizationId}/keys — useApiKeys
  Returns a list of all keys in the organization.
• [ ] POST /v1/organizations/{organizationId}/keys — useCreateApiKey
  Creates new API key.
• [ ] GET /v1/organizations/{organizationId}/keys/{keyId} — useApiKey
  Returns a single key details.
• [ ] PATCH /v1/organizations/{organizationId}/keys/{keyId} — useUpdateApiKey
  Updates API key properties.
• [ ] DELETE /v1/organizations/{organizationId}/keys/{keyId} — useDeleteApiKey Deletes API key. Only a key not used to authenticate the active request can be deleted.

src/hooks/useInvitations.ts

• [ ] GET /v1/organizations/{organizationId}/invitations — useInvitations
  Returns list of all organization invitations.
• [ ] POST /v1/organizations/{organizationId}/invitations — useCreateInvitation
  Creates organization invitation.
• [ ] GET /v1/organizations/{organizationId}/invitations/{invitationId} — useInvitation
  Returns details for a single organization invitation.
• [ ] DELETE /v1/organizations/{organizationId}/invitations/{invitationId} — useDeleteInvitation
  Deletes a single organization invitation.

src/hooks/useClickpipesReversePrivateEndpoints.ts

• [!] GET /v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints — useClickpipesReversePrivateEndpoints
  Returns a list of reverse private endpoints for the specified service.
• [!] POST /v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints — useCreateClickpipesReversePrivateEndpoint
  Create a new reverse private endpoint.
• [!] GET /v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints/{reversePrivateEndpointId} — useClickpipesReversePrivateEndpoint
  Returns the reverse private endpoint with the specified ID.
• [!] DELETE /v1/organizations/{organizationId}/services/{serviceId}/clickpipesReversePrivateEndpoints/{reversePrivateEndpointId} — useDeleteClickpipesReversePrivateEndpoint
  Delete the reverse private endpoint with the specified ID.

src/hooks/useClickpipes.ts

• [ ] GET /v1/organizations/{organizationId}/services/{serviceId}/clickpipes — useClickpipes
  Returns a list of ClickPipes.
• [ ] POST /v1/organizations/{organizationId}/services/{serviceId}/clickpipes — useCreateClickpipe
  Create a new ClickPipe.
• [ ] GET /v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId} — useClickpipe
  Returns the specified ClickPipe.
• [ ] PATCH /v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId} — useUpdateClickpipe
  Update the specified ClickPipe.
• [ ] DELETE /v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId} — useDeleteClickpipe
  Delete the specified ClickPipe.
• [!] PATCH /v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/scaling — useUpdateClickpipeTier
  Change scaling settings for the specified ClickPipe.
• [!] PATCH /v1/organizations/{organizationId}/services/{serviceId}/clickpipes/{clickPipeId}/state — useUpdateClickpipeState
  Start, stop or resync ClickPipe.

Installation

npm install clickhouse-cloud-react-hooks

or

yarn add clickhouse-cloud-react-hooks

Usage

Basic Example

import {
  useOrganizations,
  type ClickHouseConfig,
  type Organization,
  ClickHouseAPIError,
} from "clickhouse-cloud-react-hooks";

const OrganizationsList = () => {
  const config: ClickHouseConfig = {
    keyId: process.env.REACT_APP_CLICKHOUSE_KEY_ID!,
    keySecret: process.env.REACT_APP_CLICKHOUSE_KEY_SECRET!,
  };

  const { data: organizations, error, isLoading } = useOrganizations(config);

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (error) {
    if (error instanceof ClickHouseAPIError) {
      return (
        <div>
          ClickHouse API Error: {error.error} (Status: {error.status})
        </div>
      );
    }
    return <div>Error: {error.message}</div>;
  }

  return (
    <div>
      <h1>Organizations</h1>
      <ul>
        {organizations?.map((org: Organization) => (
          <li key={org.id}>
            <h3>{org.name}</h3>
            <p>Created: {new Date(org.createdAt).toLocaleDateString()}</p>
            <p>ID: {org.id}</p>
          </li>
        ))}
      </ul>
    </div>
  );
};

export default OrganizationsList;

Advanced Usage with Activities

import {
  useOrganizationActivities,
  type Activity,
  type ClickHouseConfig,
} from "clickhouse-cloud-react-hooks";

const ActivityLog = ({ organizationId }: { organizationId: string }) => {
  const config: ClickHouseConfig = {
    keyId: process.env.REACT_APP_CLICKHOUSE_KEY_ID!,
    keySecret: process.env.REACT_APP_CLICKHOUSE_KEY_SECRET!,
  };

  const {
    data: activities,
    error,
    isLoading,
  } = useOrganizationActivities(organizationId, config);

  if (isLoading) return <div>Loading activities...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h2>Recent Activities</h2>
      <ul>
        {activities?.map((activity: Activity) => (
          <li key={activity.id}>
            <strong>{activity.type}</strong> - {activity.actorType}
            <small>
              {" "}
              ({new Date(activity.createdAt).toLocaleDateString()})
            </small>
          </li>
        ))}
      </ul>
    </div>
  );
};

Available Hooks

Organizations

• useOrganizations(config) - Fetch all organizations
• useOrganization(organizationId, config) - Fetch single organization
• useUpdateOrganization(organizationId, config) - Update organization
• useOrganizationActivities(organizationId, config) - Fetch organization activities
• useOrganizationActivity(organizationId, activityId, config) - Fetch single activity
• useOrganizationUsageCost(organizationId, config, params?) - Fetch usage costs
• useOrganizationPrivateEndpointConfig(organizationId, config, params?) - Fetch private endpoint config

Services

• useServices(organizationId, config) - Manage services
• (Additional service hooks to be documented)

API Keys

• useApiKeys(organizationId, config) - Manage API keys
• (Additional API key hooks to be documented)

Backups

• useBackups(organizationId, serviceId, config) - Manage backups
• (Additional backup hooks to be documented)

ClickPipes

• useClickpipes(organizationId, serviceId, config) - Manage ClickPipes
• (Additional ClickPipe hooks to be documented)

User Management

• useUserManagement(organizationId, config) - Manage users and roles
• (Additional user management hooks to be documented)

Configuration

ClickHouse Config

type ClickHouseConfig = {
  keyId: string; // Your ClickHouse API Key ID
  keySecret: string; // Your ClickHouse API Key Secret
  baseUrl?: string; // Optional: Custom API base URL (defaults to https://api.clickhouse.cloud)
};

Development

To run the example application:

# Install dependencies
yarn

# Navigate to the example directory
cd example

# Install example dependencies
yarn

# Start the development server
yarn dev

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all existing tests pass
5. Submit a pull request

License

This project is licensed under the MIT License.