--- title: OpenSearch API Reference product: Databases url: https://docs.digitalocean.com/reference/api/reference/databases/ --- > **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document). # OpenSearch API Reference [View full API reference](https://docs.digitalocean.com/reference/api/reference/index.html.md) DigitalOcean's [managed database service](https://docs.digitalocean.com/products/databases) simplifies the creation and management of highly available database clusters. Currently, it offers support for [PostgreSQL](http://docs.digitalocean.com/products/databases/postgresql/), [Caching](https://docs.digitalocean.com/products/databases/redis/index.html.md), [Valkey](https://docs.digitalocean.com/products/databases/valkey/index.html.md), [MySQL](https://docs.digitalocean.com/products/databases/mysql/index.html.md), [MongoDB](https://docs.digitalocean.com/products/databases/mongodb/index.html.md), and [OpenSearch](https://docs.digitalocean.com/products/databases/opensearch/index.html.md). By sending requests to the `/v2/databases` endpoint, you can list, create, or delete database clusters as well as scale the size of a cluster, add or remove read-only replicas, and manage other configuration details. Database clusters may be deployed in a multi-node, high-availability configuration. If your machine type is above the basic nodes, your node plan is above the smallest option, or you are running MongoDB, you may additionally include up to two standby nodes in your cluster. The size of individual nodes in a database cluster is represented by a human-readable slug, which is used in some of the following requests. Each slug denotes the node's identifier, CPU count, and amount of RAM, in that order. For a list of currently available database slugs and options, use the `/v2/databases/options` endpoint or use the `doctl databases options` [command](https://docs.digitalocean.com/reference/doctl/reference/databases/options). Base URL `https://api.digitalocean.com` ## Endpoints - **GET** [List Database Options](#databases_list_options) - **GET** [List All Database Clusters](#databases_list_clusters) - **POST** [Create a New Database Cluster](#databases_create_cluster) - **GET** [Retrieve an Existing Database Cluster](#databases_get_cluster) - **DELETE** [Destroy a Database Cluster](#databases_destroy_cluster) - **GET** [Retrieve an Existing Database Cluster Configuration](#databases_get_config) - **PATCH** [Update the Database Configuration for an Existing Database](#databases_patch_config) - **GET** [Retrieve the Public Certificate](#databases_get_ca) - **GET** [Retrieve the Status of an Online Migration](#databases_get_migrationStatus) - **PUT** [Start an Online Migration](#databases_update_onlineMigration) - **DELETE** [Stop an Online Migration](#databases_delete_onlineMigration) - **PUT** [Migrate a Database Cluster to a New Region](#databases_update_region) - **PUT** [Resize a Database Cluster](#databases_update_clusterSize) - **GET** [List Firewall Rules (Trusted Sources) for a Database Cluster](#databases_list_firewall_rules) - **PUT** [Update Firewall Rules (Trusted Sources) for a Database](#databases_update_firewall_rules) - **GET** [Retrieve DO Settings for a Database Cluster](#databases_get_do_settings) - **PUT** [Update DO Settings for a Database Cluster](#databases_update_do_settings) - **PUT** [Configure a Database Cluster's Maintenance Window](#databases_update_maintenanceWindow) - **PUT** [Start Database Maintenance](#databases_install_update) - **GET** [List Backups for a Database Cluster](#databases_list_backups) - **GET** [List All Read-only Replicas](#databases_list_replicas) - **POST** [Create a Read-only Replica](#databases_create_replica) - **GET** [List all Events Logs](#databases_list_events_logs) - **GET** [Retrieve an Existing Read-only Replica](#databases_get_replica) - **DELETE** [Destroy a Read-only Replica](#databases_destroy_replica) - **PUT** [Promote a Read-only Replica to become a Primary Cluster](#databases_promote_replica) - **GET** [List all Database Users](#databases_list_users) - **POST** [Add a Database User](#databases_add_user) - **GET** [Retrieve an Existing Database User](#databases_get_user) - **PUT** [Update a Database User](#databases_update_user) - **DELETE** [Remove a Database User](#databases_delete_user) - **POST** [Reset a Database User's Password or Authentication Method](#databases_reset_auth) - **GET** [List All Databases](#databases_list) - **POST** [Add a New Database](#databases_add) - **GET** [Retrieve an Existing Database](#databases_get) - **DELETE** [Delete a Database](#databases_delete) - **GET** [List Connection Pools (PostgreSQL)](#databases_list_connectionPools) - **POST** [Add a New Connection Pool (PostgreSQL)](#databases_add_connectionPool) - **GET** [Retrieve Existing Connection Pool (PostgreSQL)](#databases_get_connectionPool) - **PUT** [Update Connection Pools (PostgreSQL)](#databases_update_connectionPool) - **DELETE** [Delete a Connection Pool (PostgreSQL)](#databases_delete_connectionPool) - **GET** [Retrieve the Eviction Policy for a Caching or Valkey Cluster](#databases_get_evictionPolicy) - **PUT** [Configure the Eviction Policy for a Caching or Valkey Cluster](#databases_update_evictionPolicy) - **GET** [Retrieve the SQL Modes for a MySQL Cluster](#databases_get_sql_mode) - **PUT** [Update SQL Mode for a Cluster](#databases_update_sql_mode) - **PUT** [Upgrade Major Version for a Database](#databases_update_major_version) - **GET** [Retrieve Autoscale Configuration for a Database Cluster](#databases_get_autoscale) - **PUT** [Configure Autoscale Settings for a Database Cluster](#databases_update_autoscale) - **GET** [List Topics for a Kafka Cluster](#databases_list_kafka_topics) - **POST** [Create Topic for a Kafka Cluster](#databases_create_kafka_topic) - **GET** [Get Topic for a Kafka Cluster](#databases_get_kafka_topic) - **PUT** [Update Topic for a Kafka Cluster](#databases_update_kafka_topic) - **DELETE** [Delete Topic for a Kafka Cluster](#databases_delete_kafka_topic) - **GET** [List Logsinks for a Database Cluster](#databases_list_logsink) - **POST** [Create Logsink for a Database Cluster](#databases_create_logsink) - **GET** [Get Logsink for a Database Cluster](#databases_get_logsink) - **PUT** [Update Logsink for a Database Cluster](#databases_update_logsink) - **DELETE** [Delete Logsink for a Database Cluster](#databases_delete_logsink) - **GET** [List Schemas for Kafka Cluster](#databases_list_kafka_schemas) - **POST** [Create Schema Registry for Kafka Cluster](#databases_create_kafka_schema) - **GET** [Get a Kafka Schema by Subject Name](#databases_get_kafka_schema) - **DELETE** [Delete a Kafka Schema by Subject Name](#databases_delete_kafka_schema) - **GET** [Get Kafka Schema by Subject Version](#databases_get_kafka_schema_version) - **GET** [Retrieve Schema Registry Configuration for a kafka Cluster](#databases_get_kafka_schema_config) - **PUT** [Update Schema Registry Configuration for a kafka Cluster](#databases_update_kafka_schema_config) - **GET** [Retrieve Schema Registry Configuration for a Subject of kafka Cluster](#databases_get_kafka_schema_subject_config) - **PUT** [Update Schema Registry Configuration for a Subject of kafka Cluster](#databases_update_kafka_schema_subject_config) - **GET** [Retrieve Database Clusters' Metrics Endpoint Credentials](#databases_get_cluster_metrics_credentials) - **PUT** [Update Database Clusters' Metrics Endpoint Credentials](#databases_update_cluster_metrics_credentials) - **GET** [List Indexes for a OpenSearch Cluster](#databases_list_opeasearch_indexes) - **DELETE** [Delete Index for OpenSearch Cluster](#databases_delete_opensearch_index) ## GET List Database Options `/v2/databases/options` **Authorizations: bearer_auth (1 scope)** Http: Bearer Required scopes: database:read ### OAuth Authentication In order to interact with the DigitalOcean API, you or your application must authenticate. The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints. You can generate an OAuth token by visiting the [Apps & API](https://cloud.digitalocean.com/account/api/tokens) section of the DigitalOcean control panel for your account. An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair. Because of this, it is absolutely **essential** that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised. DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens. - `dop_v1_` for personal access tokens generated in the control panel - `doo_v1_` for tokens generated by applications using [the OAuth flow](https://docs.digitalocean.com/reference/api/oauth-api/index.html.md) - `dor_v1_` for OAuth refresh tokens #### Scopes Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes. Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete). | HTTP Verb | CRUD Operation | Scope | |---|---|---| | GET | Read | `:read` | | POST | Create | `:create` | | PUT/PATCH | Update | `:update` | | DELETE | Delete | `:delete` | For example, creating a new Droplet by making a `POST` request to the `/v2/droplets` endpoint requires the `droplet:create` scope while listing Droplets by making a `GET` request to the `/v2/droplets` endpoint requires the `droplet:read` scope. Each endpoint below specifies which scope is required to access it when using custom scopes. #### How to Authenticate with OAuth In order to make an authenticated request, include a bearer-type `Authorization` header containing your OAuth token. All requests must be made over HTTPS. #### Authenticate with a Bearer Authorization Header ``` curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT" ``` To list all of the options available for the offered database engines, send a GET request to `/v2/databases/options`. The result will be a JSON object with an `options` key. ##### Request: `/v2/databases/options` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/options" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() options, _, err := client.Databases.ListOptions(ctx) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.list_options() ``` #### Responses **200** A JSON string with a key of options. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `options` object optional **Show child properties** `advanced_mysql` object optional `advanced_pg` object optional `kafka` object optional `mongodb` object optional `mysql` object optional `opensearch` object optional `pg` object optional `redis` object optional `valkey` object optional `version_availability` object optional **Show child properties** `advanced_mysql` array of object optional An array of objects, each indicating the version end-of-life, end-of-availability for various database engines **Show child properties** `end_of_availability` string optional Nullable Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `end_of_life` string optional Nullable Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `version` string optional Example: `8` The engine version. `advanced_pg` array of object optional An array of objects, each indicating the version end-of-life, end-of-availability for various database engines **Show child properties** `end_of_availability` string optional Nullable Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `end_of_life` string optional Nullable Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `version` string optional Example: `8` The engine version. `kafka` array of object optional An array of objects, each indicating the version end-of-life, end-of-availability for various database engines **Show child properties** `end_of_availability` string optional Nullable Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `end_of_life` string optional Nullable Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `version` string optional Example: `8` The engine version. `mongodb` array of object optional An array of objects, each indicating the version end-of-life, end-of-availability for various database engines **Show child properties** `end_of_availability` string optional Nullable Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `end_of_life` string optional Nullable Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `version` string optional Example: `8` The engine version. `mysql` array of object optional An array of objects, each indicating the version end-of-life, end-of-availability for various database engines **Show child properties** `end_of_availability` string optional Nullable Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `end_of_life` string optional Nullable Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `version` string optional Example: `8` The engine version. `opensearch` array of object optional An array of objects, each indicating the version end-of-life, end-of-availability for various database engines **Show child properties** `end_of_availability` string optional Nullable Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `end_of_life` string optional Nullable Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `version` string optional Example: `8` The engine version. `pg` array of object optional An array of objects, each indicating the version end-of-life, end-of-availability for various database engines **Show child properties** `end_of_availability` string optional Nullable Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `end_of_life` string optional Nullable Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `version` string optional Example: `8` The engine version. `redis` array of object optional An array of objects, each indicating the version end-of-life, end-of-availability for various database engines **Show child properties** `end_of_availability` string optional Nullable Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `end_of_life` string optional Nullable Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `version` string optional Example: `8` The engine version. `valkey` array of object optional An array of objects, each indicating the version end-of-life, end-of-availability for various database engines **Show child properties** `end_of_availability` string optional Nullable Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `end_of_life` string optional Nullable Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `version` string optional Example: `8` The engine version. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "options": { "advanced_mysql": { "default_version": "8.4.8", "layouts": [ { "num_nodes": 1, "sizes": [ "gd-2vcpu-8gb-intel", "so1_5-2vcpu-16gb-intel", "so1_5-2vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb-intel", "so1_5-4vcpu-32gb-intel", "so1_5-4vcpu-32gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "so1_5-8vcpu-64gb", "gd-8vcpu-32gb-intel", "so1_5-8vcpu-64gb-intel", "gd-16vcpu-64gb", "so1_5-16vcpu-128gb", "gd-16vcpu-64gb-intel", "so1_5-16vcpu-128gb-intel", "so1_5-24vcpu-192gb", "so1_5-24vcpu-192gb-intel", "so1_5-32vcpu-256gb-intel", "gd-32vcpu-128gb", "gd-32vcpu-128gb-intel", "so1_5-32vcpu-256gb", "gd-40vcpu-160gb", "so1_5-48vcpu-384gb-intel", "gd-48vcpu-192gb-intel", "so1_5-48vcpu-256gb", "c-96-intel" ] }, { "num_nodes": 3, "sizes": [ "gd-2vcpu-8gb-intel", "so1_5-2vcpu-16gb-intel", "so1_5-2vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb-intel", "so1_5-4vcpu-32gb-intel", "so1_5-4vcpu-32gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "so1_5-8vcpu-64gb", "gd-8vcpu-32gb-intel", "so1_5-8vcpu-64gb-intel", "gd-16vcpu-64gb", "so1_5-16vcpu-128gb", "gd-16vcpu-64gb-intel", "so1_5-16vcpu-128gb-intel", "so1_5-24vcpu-192gb", "so1_5-24vcpu-192gb-intel", "so1_5-32vcpu-256gb-intel", "gd-32vcpu-128gb", "gd-32vcpu-128gb-intel", "so1_5-32vcpu-256gb", "gd-40vcpu-160gb", "so1_5-48vcpu-384gb-intel", "gd-48vcpu-192gb-intel", "so1_5-48vcpu-256gb", "c-96-intel" ] } ], "regions": [ "ams3", "blr1", "fra1", "lon1", "nyc1", "nyc2", "nyc3", "sfo2", "sfo3", "sgp1", "syd1", "tor1", "ric1", "atl1" ], "versions": [ "8.4.8" ] }, "advanced_pg": { "default_version": "18", "layouts": [ { "num_nodes": 1, "sizes": [ "gd-2vcpu-8gb-intel", "so1_5-2vcpu-16gb-intel", "so1_5-2vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb-intel", "so1_5-4vcpu-32gb-intel", "so1_5-4vcpu-32gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "so1_5-8vcpu-64gb", "gd-8vcpu-32gb-intel", "so1_5-8vcpu-64gb-intel", "gd-16vcpu-64gb", "so1_5-16vcpu-128gb", "gd-16vcpu-64gb-intel", "so1_5-16vcpu-128gb-intel", "so1_5-24vcpu-192gb", "so1_5-24vcpu-192gb-intel", "so1_5-32vcpu-256gb-intel", "gd-32vcpu-128gb", "gd-32vcpu-128gb-intel", "so1_5-32vcpu-256gb", "gd-40vcpu-160gb", "so1_5-48vcpu-384gb-intel", "gd-48vcpu-192gb-intel", "so1_5-48vcpu-256gb", "c-96-intel" ] }, { "num_nodes": 2, "sizes": [ "gd-2vcpu-8gb-intel", "so1_5-2vcpu-16gb-intel", "so1_5-2vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb-intel", "so1_5-4vcpu-32gb-intel", "so1_5-4vcpu-32gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "so1_5-8vcpu-64gb", "gd-8vcpu-32gb-intel", "so1_5-8vcpu-64gb-intel", "gd-16vcpu-64gb", "so1_5-16vcpu-128gb", "gd-16vcpu-64gb-intel", "so1_5-16vcpu-128gb-intel", "so1_5-24vcpu-192gb", "so1_5-24vcpu-192gb-intel", "so1_5-32vcpu-256gb-intel", "gd-32vcpu-128gb", "gd-32vcpu-128gb-intel", "so1_5-32vcpu-256gb", "gd-40vcpu-160gb", "so1_5-48vcpu-384gb-intel", "gd-48vcpu-192gb-intel", "so1_5-48vcpu-256gb", "c-96-intel" ] }, { "num_nodes": 3, "sizes": [ "gd-2vcpu-8gb-intel", "so1_5-2vcpu-16gb-intel", "so1_5-2vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb-intel", "so1_5-4vcpu-32gb-intel", "so1_5-4vcpu-32gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "so1_5-8vcpu-64gb", "gd-8vcpu-32gb-intel", "so1_5-8vcpu-64gb-intel", "gd-16vcpu-64gb", "so1_5-16vcpu-128gb", "gd-16vcpu-64gb-intel", "so1_5-16vcpu-128gb-intel", "so1_5-24vcpu-192gb", "so1_5-24vcpu-192gb-intel", "so1_5-32vcpu-256gb-intel", "gd-32vcpu-128gb", "gd-32vcpu-128gb-intel", "so1_5-32vcpu-256gb", "gd-40vcpu-160gb", "so1_5-48vcpu-384gb-intel", "gd-48vcpu-192gb-intel", "so1_5-48vcpu-256gb", "c-96-intel" ] } ], "regions": [ "ams3", "blr1", "fra1", "lon1", "nyc1", "nyc2", "nyc3", "sfo2", "sfo3", "sgp1", "syd1", "tor1", "ric1", "atl1" ], "versions": [ "16", "17", "18" ] }, "kafka": { "default_version": "3.8", "layouts": [ { "num_nodes": 3, "sizes": [ "gd-2vcpu-8gb", "gd-4vcpu-16gb", "db-s-2vcpu-4gb", "db-s-2vcpu-2gb" ] }, { "num_nodes": 6, "sizes": [ "gd-2vcpu-8gb", "gd-4vcpu-16gb" ] }, { "num_nodes": 9, "sizes": [ "gd-2vcpu-8gb", "gd-4vcpu-16gb" ] }, { "num_nodes": 15, "sizes": [ "gd-2vcpu-8gb", "gd-4vcpu-16gb" ] } ], "regions": [ "ams3", "blr1", "fra1", "lon1", "nyc1", "nyc2", "nyc3", "sfo2", "sfo3", "sgp1", "syd1", "tor1", "ric1", "atl1" ], "versions": [ "3.8" ] }, "mongodb": { "default_version": "7.0", "layouts": [ { "num_nodes": 1, "sizes": [ "db-s-1vcpu-1gb", "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "db-s-8vcpu-32gb", "db-s-16vcpu-64gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "gd-16vcpu-64gb", "gd-32vcpu-128gb", "gd-40vcpu-160gb", "so1_5-2vcpu-16gb", "so1_5-4vcpu-32gb", "so1_5-8vcpu-64gb", "so1_5-16vcpu-128gb", "so1_5-24vcpu-192gb", "so1_5-32vcpu-256gb" ] }, { "num_nodes": 3, "sizes": [ "db-s-1vcpu-1gb", "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "db-s-8vcpu-32gb", "db-s-16vcpu-64gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "gd-16vcpu-64gb", "gd-32vcpu-128gb", "gd-40vcpu-160gb", "so1_5-2vcpu-16gb", "so1_5-4vcpu-32gb", "so1_5-8vcpu-64gb", "so1_5-16vcpu-128gb", "so1_5-24vcpu-192gb", "so1_5-32vcpu-256gb" ] } ], "regions": [ "ams3", "blr1", "fra1", "lon1", "nyc1", "nyc2", "nyc3", "sfo2", "sfo3", "sgp1", "syd1", "tor1", "ric1", "atl1" ], "versions": [ "6.0", "7.0" ] }, "mysql": { "default_version": "8", "layouts": [ { "num_nodes": 1, "sizes": [ "db-s-1vcpu-1gb", "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "gd-16vcpu-64gb", "gd-32vcpu-128gb", "gd-40vcpu-160gb", "so1_5-2vcpu-16gb", "so1_5-4vcpu-32gb", "so1_5-8vcpu-64gb", "so1_5-16vcpu-128gb", "so1_5-24vcpu-192gb", "so1_5-32vcpu-256gb", "db-intel-1vcpu-1gb", "db-amd-1vcpu-1gb", "db-intel-1vcpu-2gb", "db-amd-1vcpu-2gb", "db-amd-2vcpu-4gb", "db-intel-2vcpu-4gb", "db-amd-2vcpu-8gb", "db-intel-2vcpu-8gb", "db-intel-4vcpu-8gb", "db-amd-4vcpu-8gb", "db-amd-4vcpu-16gb", "db-intel-4vcpu-16gb", "db-intel-8vcpu-32gb", "db-amd-8vcpu-32gb", "db-intel-16vcpu-64gb", "db-amd-16vcpu-64gb" ] }, { "num_nodes": 2, "sizes": [ "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "gd-16vcpu-64gb", "gd-32vcpu-128gb", "gd-40vcpu-160gb", "so1_5-2vcpu-16gb", "so1_5-4vcpu-32gb", "so1_5-8vcpu-64gb", "so1_5-16vcpu-128gb", "so1_5-24vcpu-192gb", "so1_5-32vcpu-256gb", "db-intel-1vcpu-2gb", "db-amd-1vcpu-2gb", "db-amd-2vcpu-4gb", "db-intel-2vcpu-4gb", "db-intel-2vcpu-8gb", "db-amd-2vcpu-8gb", "db-intel-4vcpu-8gb", "db-amd-4vcpu-8gb", "db-intel-4vcpu-16gb", "db-amd-4vcpu-16gb", "db-amd-8vcpu-32gb", "db-intel-8vcpu-32gb", "db-amd-16vcpu-64gb", "db-intel-16vcpu-64gb" ] }, { "num_nodes": 3, "sizes": [ "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "gd-16vcpu-64gb", "gd-32vcpu-128gb", "gd-40vcpu-160gb", "so1_5-2vcpu-16gb", "so1_5-4vcpu-32gb", "so1_5-8vcpu-64gb", "so1_5-16vcpu-128gb", "so1_5-24vcpu-192gb", "so1_5-32vcpu-256gb", "db-intel-1vcpu-2gb", "db-amd-1vcpu-2gb", "db-amd-2vcpu-4gb", "db-intel-2vcpu-4gb", "db-intel-2vcpu-8gb", "db-amd-2vcpu-8gb", "db-intel-4vcpu-8gb", "db-amd-4vcpu-8gb", "db-intel-4vcpu-16gb", "db-amd-4vcpu-16gb", "db-amd-8vcpu-32gb", "db-intel-8vcpu-32gb", "db-amd-16vcpu-64gb", "db-intel-16vcpu-64gb" ] } ], "regions": [ "ams3", "blr1", "fra1", "lon1", "nyc1", "nyc2", "nyc3", "sfo2", "sfo3", "sgp1", "syd1", "tor1", "ric1", "atl1" ], "versions": [ "8" ] }, "opensearch": { "default_version": "2", "layouts": [ { "num_nodes": 1, "sizes": [ "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "gd-2vcpu-8gb", "m3-2vcpu-16gb", "db-s-4vcpu-8gb", "gd-4vcpu-16gb", "m3-4vcpu-32gb", "m3-8vcpu-64gb" ] }, { "num_nodes": 3, "sizes": [ "db-s-2vcpu-4gb", "gd-2vcpu-8gb", "m3-2vcpu-16gb", "db-s-4vcpu-8gb", "gd-4vcpu-16gb", "m3-4vcpu-32gb", "m3-8vcpu-64gb" ] }, { "num_nodes": 6, "sizes": [ "gd-2vcpu-8gb", "m3-2vcpu-16gb", "gd-4vcpu-16gb", "m3-4vcpu-32gb", "m3-8vcpu-64gb" ] }, { "num_nodes": 9, "sizes": [ "gd-2vcpu-8gb", "m3-2vcpu-16gb", "gd-4vcpu-16gb", "m3-4vcpu-32gb", "m3-8vcpu-64gb" ] }, { "num_nodes": 15, "sizes": [ "gd-2vcpu-8gb", "m3-2vcpu-16gb", "gd-4vcpu-16gb", "m3-4vcpu-32gb", "m3-8vcpu-64gb" ] } ], "regions": [ "ams3", "blr1", "fra1", "lon1", "nyc1", "nyc2", "nyc3", "sfo2", "sfo3", "sgp1", "syd1", "tor1", "ric1", "atl1" ], "versions": [ "1", "2" ] }, "pg": { "default_version": "17", "layouts": [ { "num_nodes": 1, "sizes": [ "db-s-1vcpu-1gb", "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "gd-16vcpu-64gb", "gd-32vcpu-128gb", "gd-40vcpu-160gb", "so1_5-2vcpu-16gb", "so1_5-4vcpu-32gb", "so1_5-8vcpu-64gb", "so1_5-16vcpu-128gb", "so1_5-24vcpu-192gb", "so1_5-32vcpu-256gb", "db-intel-1vcpu-1gb", "db-amd-1vcpu-1gb", "db-intel-1vcpu-2gb", "db-amd-1vcpu-2gb", "db-amd-2vcpu-4gb", "db-intel-2vcpu-4gb", "db-amd-2vcpu-8gb", "db-intel-2vcpu-8gb", "db-intel-4vcpu-8gb", "db-amd-4vcpu-8gb", "db-amd-4vcpu-16gb", "db-intel-4vcpu-16gb", "db-intel-8vcpu-32gb", "db-amd-8vcpu-32gb", "db-intel-16vcpu-64gb", "db-amd-16vcpu-64gb" ] }, { "num_nodes": 2, "sizes": [ "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "gd-16vcpu-64gb", "gd-32vcpu-128gb", "gd-40vcpu-160gb", "so1_5-2vcpu-16gb", "so1_5-4vcpu-32gb", "so1_5-8vcpu-64gb", "so1_5-16vcpu-128gb", "so1_5-24vcpu-192gb", "so1_5-32vcpu-256gb", "db-intel-1vcpu-2gb", "db-amd-1vcpu-2gb", "db-amd-2vcpu-4gb", "db-intel-2vcpu-4gb", "db-intel-2vcpu-8gb", "db-amd-2vcpu-8gb", "db-intel-4vcpu-8gb", "db-amd-4vcpu-8gb", "db-intel-4vcpu-16gb", "db-amd-4vcpu-16gb", "db-amd-8vcpu-32gb", "db-intel-8vcpu-32gb", "db-amd-16vcpu-64gb", "db-intel-16vcpu-64gb" ] }, { "num_nodes": 3, "sizes": [ "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "gd-2vcpu-8gb", "gd-4vcpu-16gb", "gd-8vcpu-32gb", "gd-16vcpu-64gb", "gd-32vcpu-128gb", "gd-40vcpu-160gb", "so1_5-2vcpu-16gb", "so1_5-4vcpu-32gb", "so1_5-8vcpu-64gb", "so1_5-16vcpu-128gb", "so1_5-24vcpu-192gb", "so1_5-32vcpu-256gb", "db-intel-1vcpu-2gb", "db-amd-1vcpu-2gb", "db-amd-2vcpu-4gb", "db-intel-2vcpu-4gb", "db-intel-2vcpu-8gb", "db-amd-2vcpu-8gb", "db-intel-4vcpu-8gb", "db-amd-4vcpu-8gb", "db-intel-4vcpu-16gb", "db-amd-4vcpu-16gb", "db-amd-8vcpu-32gb", "db-intel-8vcpu-32gb", "db-amd-16vcpu-64gb", "db-intel-16vcpu-64gb" ] } ], "regions": [ "ams3", "blr1", "fra1", "lon1", "nyc1", "nyc2", "nyc3", "sfo2", "sfo3", "sgp1", "syd1", "tor1", "ric1", "atl1" ], "versions": [ "13", "14", "15", "16", "17" ] }, "redis": { "layouts": [ { "num_nodes": 1, "sizes": [ "db-s-1vcpu-1gb", "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "db-s-8vcpu-32gb", "db-s-16vcpu-64gb", "m-2vcpu-16gb", "m-4vcpu-32gb", "m-8vcpu-64gb", "m-16vcpu-128gb", "m-24vcpu-192gb", "m-32vcpu-256gb" ] }, { "num_nodes": 2, "sizes": [ "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "db-s-8vcpu-32gb", "db-s-16vcpu-64gb", "m-2vcpu-16gb", "m-4vcpu-32gb", "m-8vcpu-64gb", "m-16vcpu-128gb", "m-24vcpu-192gb", "m-32vcpu-256gb" ] }, { "num_nodes": 3, "sizes": [ "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "db-s-8vcpu-32gb", "db-s-16vcpu-64gb", "m-2vcpu-16gb", "m-4vcpu-32gb", "m-8vcpu-64gb", "m-16vcpu-128gb", "m-24vcpu-192gb", "m-32vcpu-256gb" ] } ], "regions": [ "ams3", "blr1", "fra1", "lon1", "nyc1", "nyc2", "nyc3", "sfo2", "sfo3", "sgp1", "syd1", "tor1", "ric1", "atl1" ], "versions": [ "7" ] }, "valkey": { "default_version": "8", "layouts": [ { "num_nodes": 1, "sizes": [ "db-s-1vcpu-1gb", "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "db-s-8vcpu-32gb", "db-s-16vcpu-64gb", "m-2vcpu-16gb", "m-4vcpu-32gb", "m-8vcpu-64gb", "m-16vcpu-128gb", "m-24vcpu-192gb", "m-32vcpu-256gb" ] }, { "num_nodes": 2, "sizes": [ "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "db-s-8vcpu-32gb", "db-s-16vcpu-64gb", "m-2vcpu-16gb", "m-4vcpu-32gb", "m-8vcpu-64gb", "m-16vcpu-128gb", "m-24vcpu-192gb", "m-32vcpu-256gb" ] }, { "num_nodes": 3, "sizes": [ "db-s-1vcpu-2gb", "db-s-2vcpu-4gb", "db-s-4vcpu-8gb", "db-s-6vcpu-16gb", "db-s-8vcpu-32gb", "db-s-16vcpu-64gb", "m-2vcpu-16gb", "m-4vcpu-32gb", "m-8vcpu-64gb", "m-16vcpu-128gb", "m-24vcpu-192gb", "m-32vcpu-256gb" ] } ], "regions": [ "ams3", "blr1", "fra1", "lon1", "nyc1", "nyc3", "sfo2", "sfo3", "sgp1", "syd1", "tor1", "ric1", "atl1" ], "versions": [ "8" ] } }, "version_availability": { "advanced_mysql": [ { "default": true, "end_of_availability": null, "end_of_life": null, "version": "8.4.8" } ], "advanced_pg": [ { "default": false, "end_of_availability": "2028-05-09T00:00:00Z", "end_of_life": "2028-11-09T00:00:00Z", "version": "16" }, { "default": false, "end_of_availability": "2029-05-08T00:00:00Z", "end_of_life": "2029-11-08T00:00:00Z", "version": "17" }, { "default": true, "end_of_availability": "2030-05-13T00:00:00Z", "end_of_life": "2030-11-13T00:00:00Z", "version": "18" } ], "kafka": [ { "default": true, "end_of_availability": "2025-06-03T00:00:00Z", "end_of_life": null, "version": "3.8" } ], "mongodb": [ { "default": false, "end_of_availability": null, "end_of_life": "2025-07-01T07:00:00Z", "version": "6.0" }, { "default": true, "end_of_availability": null, "end_of_life": "2026-08-01T07:00:00Z", "version": "7.0" } ], "mysql": [ { "default": true, "end_of_availability": null, "end_of_life": null, "version": "8" } ], "opensearch": [ { "default": false, "end_of_availability": null, "end_of_life": null, "version": "1" }, { "default": true, "end_of_availability": null, "end_of_life": null, "version": "2" } ], "pg": [ { "default": false, "end_of_availability": "2025-05-13T00:00:00Z", "end_of_life": "2025-11-13T00:00:00Z", "version": "13" }, { "default": false, "end_of_availability": "2026-05-12T00:00:00Z", "end_of_life": "2026-11-12T00:00:00Z", "version": "14" }, { "default": false, "end_of_availability": "2027-05-12T00:00:00Z", "end_of_life": "2027-11-11T00:00:00Z", "version": "15" }, { "default": false, "end_of_availability": "2028-05-09T00:00:00Z", "end_of_life": "2028-11-09T00:00:00Z", "version": "16" }, { "default": true, "end_of_availability": "2029-05-08T00:00:00Z", "end_of_life": "2029-11-08T00:00:00Z", "version": "17" } ], "redis": [ { "default": true, "end_of_availability": "2025-04-30T00:00:00Z", "end_of_life": "2025-06-30T00:00:00Z", "version": "7" } ], "valkey": [ { "default": true, "end_of_availability": null, "end_of_life": null, "version": "8" } ] } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List All Database Clusters `/v2/databases` To list all of the database clusters available on your account, send a GET request to `/v2/databases`. To limit the results to database clusters with a specific tag, include the `tag_name` query parameter set to the name of the tag. For example, `/v2/databases?tag_name=$TAG_NAME`. The result will be a JSON object with a `databases` key. This will be set to an array of database objects, each of which will contain the standard database attributes. The embedded `connection` and `private_connection` objects will contain the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects will contain the information needed to connect to the cluster's standby node(s). The embedded `maintenance_window` object will contain information about any scheduled maintenance for the database cluster. #### Query Parameters `tag_name` string optional Example: `production` Limits the results to database clusters with a specific tag. Requires `tag:read` scope. ##### Request: `/v2/databases` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() opt := &godo.ListOptions{ Page: 1, PerPage: 200, } clusters, _, err := client.Databases.List(ctx, opt) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.list_clusters(tag_name="production") ``` #### Responses **200** A JSON object with a key of databases. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `databases` array of object optional **Show child properties** `connection` object optional `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the database cluster was created. `db_names` array of string optional read-only Nullable Example: `["doadmin"]` An array of strings containing the names of databases created in the database cluster. `do_settings` object optional `engine` string (enum) required Example: `mysql` A slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" for OpenSearch, "valkey" for Valkey, "advanced_pg" for PostgreSQL Advanced Edition, and "advanced_mysql" for MySQL Advanced Edition. Advanced Edition engines are currently in public preview. `id` string (uuid) optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID that can be used to identify and reference a database cluster. `maintenance_window` object optional `metrics_endpoints` array of object optional read-only Public hostname and port of the cluster's metrics endpoint(s). Includes one record for the cluster's primary node and a second entry for the cluster's standby node(s). **Show child properties** `host` string optional read-only Example: `db.example.com` A FQDN pointing to the database cluster's node(s). `port` integer optional read-only Example: `9273` The port on which a service is listening. `name` string required Example: `backend` A unique, human-readable name referring to a database cluster. `num_nodes` integer required Example: `2` The number of nodes in the database cluster. `private_connection` object optional `private_network_uuid` string optional Example: `d455e75d-4858-4eec-8c95-da2f0a5f93a7` A string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster when creating a new database cluster, it will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. `project_id` string (uuid) optional Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster, it will be assigned to your default project. Requires `project:read` scope. `region` string required Example: `nyc3` The slug identifier for the region where the database cluster is located. `rules` array of object optional **Show child properties** `cluster_uuid` string optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID for the database cluster to which the rule is applied. `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the firewall rule was created. `description` string optional Example: `an IP address for local development` A human-readable description of the rule. `type` string, one of: droplet, k8s, ip_addr, tag, app required Example: `droplet` The type of resource that the firewall rule allows to access the database cluster. `uuid` string optional Example: `79f26d28-ea8a-41f2-8ad8-8cfcdd020095` A unique ID for the firewall rule itself. `value` string required Example: `ff2a6c52-5a44-4b63-b99c-0e98e7a63d61` The ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster. `schema_registry_connection` object optional The connection details for Schema Registry. `semantic_version` string optional read-only Example: `8.0.28` A string representing the semantic version of the database engine in use for the cluster. `size` string required Example: `db-s-2vcpu-4gb` The slug identifier representing the size of the nodes in the database cluster. `standby_connection` object optional `standby_private_connection` object optional `status` string, one of: creating, online, resizing, migrating, forking optional read-only Example: `creating` A string representing the current status of the database cluster. `storage_size_mib` integer optional Example: `61440` Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage. `tags` array of string optional Nullable Example: `["production"]` An array of tags that have been applied to the database cluster. Requires `tag:read` scope. `ui_connection` object optional The connection details for OpenSearch dashboard. `users` array of object optional read-only Nullable **Show child properties** `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. `version` string optional Example: `8` A string representing the version of the database engine in use for the cluster. `version_end_of_availability` string optional read-only Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `version_end_of_life` string optional read-only Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "databases": [ { "connection": { "database": "", "host": "db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "created_at": "2019-01-11T18:37:36Z", "db_names": [ "defaultdb" ], "engine": "pg", "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "maintenance_window": { "day": "saturday", "description": [ "Update TimescaleDB to version 1.2.1", "Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases" ], "hour": "08:45:12", "pending": true }, "name": "backend", "num_nodes": 1, "private_connection": { "database": "", "host": "private-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@private-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "private_network_uuid": "d455e75d-4858-4eec-8c95-da2f0a5f93a7", "region": "nyc3", "size": "db-s-2vcpu-4gb", "status": "online", "storage_size_mib": 61440, "tags": [ "production" ], "users": [ { "name": "doadmin", "password": "example_password", "role": "primary" } ], "version": "10", "version_end_of_availability": "2023-05-09T00:00:00Z", "version_end_of_life": "2023-11-09T00:00:00Z" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create a New Database Cluster `/v2/databases` To create a database cluster, send a POST request to `/v2/databases`. To see a list of options for each engine, such as available regions, size slugs, and versions, send a GET request to the `/v2/databases/options` endpoint. The available sizes for the `storage_size_mib` field depends on the cluster's size. To see a list of available sizes, see [Managed Database Pricing](https://www.digitalocean.com/pricing/managed-databases). The create response returns a JSON object with a key called `database`. The value of this is an object that contains the standard attributes associated with a database cluster. The initial value of the database cluster's `status` attribute is `creating`. When the cluster is ready to receive traffic, this changes to `online`. The embedded `connection` and `private_connection` objects contains the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects contain the information needed to connect to the cluster's standby node(s). DigitalOcean managed PostgreSQL and MySQL database clusters take automated daily backups. To create a new database cluster based on a backup of an existing cluster, send a POST request to `/v2/databases`. In addition to the standard database cluster attributes, the JSON body must include a key named `backup_restore` with the name of the original database cluster and the timestamp of the backup to be restored. Creating a database from a backup is the same as forking a database in the control panel. PostgreSQL and MySQL Advanced Edition clusters can be provisioned by setting `engine` to `advanced_pg` or `advanced_mysql`. Advanced Edition clusters are currently in public preview and target highly available workloads. `advanced_pg` supports 1-, 2-, and 3-node deployments; `advanced_mysql` only supports 1- and 3-node deployments. See the [PostgreSQL Advanced Edition](https://docs.digitalocean.com/products/databases/postgresql/how-to/use-advanced-edition-clusters/index.html.md) and [MySQL Advanced Edition](https://docs.digitalocean.com/products/databases/mysql/how-to/use-advanced-edition-clusters/index.html.md) documentation for the feature differences vs. Standard Edition and current preview limitations. Note: Caching cluster creates are no longer supported as of 2025-04-30T00:00:00Z. Backups are also not supported for Caching or Valkey clusters. #### Request Body: `application/json` `autoscale` object optional Autoscaling configuration for the database cluster. Currently only supports storage autoscaling. If null, autoscaling is not configured for the cluster. `connection` object optional `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the database cluster was created. `db_names` array of string optional read-only Nullable Example: `["doadmin"]` An array of strings containing the names of databases created in the database cluster. `do_settings` object optional `engine` string (enum) required Example: `mysql` A slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" for OpenSearch, "valkey" for Valkey, "advanced_pg" for PostgreSQL Advanced Edition, and "advanced_mysql" for MySQL Advanced Edition. Advanced Edition engines are currently in public preview. `id` string (uuid) optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID that can be used to identify and reference a database cluster. `maintenance_window` object optional `metrics_endpoints` array of object optional read-only Public hostname and port of the cluster's metrics endpoint(s). Includes one record for the cluster's primary node and a second entry for the cluster's standby node(s). **Show child properties** `host` string optional read-only Example: `db.example.com` A FQDN pointing to the database cluster's node(s). `port` integer optional read-only Example: `9273` The port on which a service is listening. `name` string required Example: `backend` A unique, human-readable name referring to a database cluster. `num_nodes` integer required Example: `2` The number of nodes in the database cluster. `private_connection` object optional `private_network_uuid` string optional Example: `d455e75d-4858-4eec-8c95-da2f0a5f93a7` A string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster when creating a new database cluster, it will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. `project_id` string (uuid) optional Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster, it will be assigned to your default project. Requires `project:assign_resource` scope. `region` string required Example: `nyc3` The slug identifier for the region where the database cluster is located. `rules` array of object optional **Show child properties** `cluster_uuid` string optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID for the database cluster to which the rule is applied. `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the firewall rule was created. `description` string optional Example: `an IP address for local development` A human-readable description of the rule. `type` string, one of: droplet, k8s, ip_addr, tag, app required Example: `droplet` The type of resource that the firewall rule allows to access the database cluster. `uuid` string optional Example: `79f26d28-ea8a-41f2-8ad8-8cfcdd020095` A unique ID for the firewall rule itself. `value` string required Example: `ff2a6c52-5a44-4b63-b99c-0e98e7a63d61` The ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster. `schema_registry_connection` object optional The connection details for Schema Registry. `semantic_version` string optional read-only Example: `8.0.28` A string representing the semantic version of the database engine in use for the cluster. `size` string required Example: `db-s-2vcpu-4gb` The slug identifier representing the size of the nodes in the database cluster. `standby_connection` object optional `standby_private_connection` object optional `status` string, one of: creating, online, resizing, migrating, forking optional read-only Example: `creating` A string representing the current status of the database cluster. `storage_size_mib` integer optional Example: `61440` Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage. `tags` array of string optional Nullable Example: `["production"]` An array of tags (as strings) to apply to the database cluster. Requires `tag:create` scope. `ui_connection` object optional The connection details for OpenSearch dashboard. `users` array of object optional read-only Nullable **Show child properties** `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. **Show child properties** `id` string optional Example: `aaa` An identifier for the ACL. Will be computed after the ACL is created/updated. `permission` string, one of: admin, consume, produce, produceconsume required Example: `consume` Permission set applied to the ACL. 'consume' allows for messages to be consumed from the topic. 'produce' allows for messages to be published to the topic. 'produceconsume' allows for both 'consume' and 'produce' permission. 'admin' allows for 'produceconsume' as well as any operations to administer the topic (delete, update). `topic` string required Example: `topic-abc.*` A regex for matching the topic(s) that this ACL should apply to. `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. **Show child properties** `databases` array of string optional Example: `["my-db","my-db-2"]` A list of databases to which the user should have access. When the database is set to `admin`, the user will have access to all databases based on the user's role i.e. a user with the role `readOnly` assigned to the `admin` database will have read access to all databases. `role` string, one of: readOnly, readWrite, dbAdmin optional Example: `readOnly` The role to assign to the user with each role mapping to a MongoDB built-in role. `readOnly` maps to a [read](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) role. `readWrite` maps to a [readWrite](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) role. `dbAdmin` maps to a [dbAdmin](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) role. `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. **Show child properties** `index` string optional Example: `index-abc.*` A regex for matching the indexes that this ACL should apply to. `permission` string, one of: deny, admin, read, readwrite, write optional Example: `read` Permission set applied to the ACL. 'read' allows user to read from the index. 'write' allows for user to write to the index. 'readwrite' allows for both 'read' and 'write' permission. 'deny'(default) restricts user from performing any operation over an index. 'admin' allows for 'readwrite' as well as any operations to administer the index. `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. `version` string optional Example: `8` A string representing the version of the database engine in use for the cluster. `version_end_of_availability` string optional read-only Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `version_end_of_life` string optional read-only Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. `backup_restore` object optional **Show child properties** `backup_created_at` string (date-time) optional Example: `2019-01-31T19:25:22Z` The timestamp of an existing database cluster backup in ISO8601 combined date and time format. The most recent backup will be used if excluded. `database_name` string required Example: `backend` The name of an existing database cluster from which the backup will be restored. ##### Request: `/v2/databases` ### Payload Content type `application/json` Example ```json { "engine": "pg", "name": "backend", "num_nodes": 2, "region": "nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440, "tags": [ "production" ], "version": "14" } ``` ```json { "do_settings": { "service_cnames": [ "db.example.com", "database.myapp.io" ] }, "engine": "pg", "name": "backend", "num_nodes": 2, "region": "nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440, "tags": [ "production" ], "version": "14" } ``` ```json { "engine": "pg", "name": "backend", "num_nodes": 2, "region": "nyc3", "rules": [ { "type": "ip_addr", "value": "192.168.1.1" }, { "type": "k8s", "value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61" }, { "type": "droplet", "value": "163973392" }, { "description": "a test tag", "type": "tag", "value": "test" } ], "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440, "tags": [ "production" ], "version": "14" } ``` ```json { "engine": "advanced_mysql", "name": "backend-advanced", "num_nodes": 3, "region": "nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440, "tags": [ "production" ], "version": "8.4.8" } ``` ```json { "engine": "advanced_pg", "name": "backend-advanced", "num_nodes": 3, "region": "nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440, "tags": [ "production" ], "version": "18" } ``` ```json { "engine": "advanced_mysql", "name": "backend-advanced-single", "num_nodes": 1, "region": "nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440, "tags": [ "production" ], "version": "8.4.8" } ``` ```json { "backup_restore": { "backup_created_at": "2019-01-31T19:25:22Z", "database_name": "backend" }, "engine": "pg", "name": "backend-restored", "num_nodes": 2, "region": "nyc3", "size": "db-s-2vcpu-4gb", "version": "14" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"name": "backend", "engine": "pg", "version": "14", "region": "nyc3", "size": "db-s-2vcpu-4gb", "num_nodes": 2, "storage_size_mib": 61440, "tags": ["production"], "do_settings": {"service_cnames": ["db.example.com", "database.myapp.io"]}}' \ "https://api.digitalocean.com/v2/databases" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() createRequest := &godo.DatabaseCreateRequest{ Name: "backend", EngineSlug: "pg", Version: "14", Region: "nyc3", SizeSlug: "db-s-2vcpu-4gb", NumNodes: 2, StorageSizeMiB : 61440, DOSettings: &godo.DOSettings{ ServiceCnames: []string{"db.example.com", "database.myapp.io"}, }, } cluster, _, err := client.Databases.Create(ctx, createRequest) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) create_req = { "name": "backend", "engine": "pg", "version": "14", "region": "nyc3", "size": "db-s-2vcpu-4gb", "num_nodes": 2, "storage_size_mib": 61440, "tags": [ "production" ], "do_settings": { "service_cnames": [ "db.example.com", "database.myapp.io" ] } } create_resp = client.databases.create_cluster(body=create_req) ``` #### Responses **201** A JSON object with a key of database. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `database` object required **Show child properties** `connection` object optional `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the database cluster was created. `db_names` array of string optional read-only Nullable Example: `["doadmin"]` An array of strings containing the names of databases created in the database cluster. `do_settings` object optional `engine` string (enum) required Example: `mysql` A slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" for OpenSearch, "valkey" for Valkey, "advanced_pg" for PostgreSQL Advanced Edition, and "advanced_mysql" for MySQL Advanced Edition. Advanced Edition engines are currently in public preview. `id` string (uuid) optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID that can be used to identify and reference a database cluster. `maintenance_window` object optional `metrics_endpoints` array of object optional read-only Public hostname and port of the cluster's metrics endpoint(s). Includes one record for the cluster's primary node and a second entry for the cluster's standby node(s). **Show child properties** `host` string optional read-only Example: `db.example.com` A FQDN pointing to the database cluster's node(s). `port` integer optional read-only Example: `9273` The port on which a service is listening. `name` string required Example: `backend` A unique, human-readable name referring to a database cluster. `num_nodes` integer required Example: `2` The number of nodes in the database cluster. `private_connection` object optional `private_network_uuid` string optional Example: `d455e75d-4858-4eec-8c95-da2f0a5f93a7` A string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster when creating a new database cluster, it will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. `project_id` string (uuid) optional Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster, it will be assigned to your default project. Requires `project:read` scope. `region` string required Example: `nyc3` The slug identifier for the region where the database cluster is located. `rules` array of object optional **Show child properties** `cluster_uuid` string optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID for the database cluster to which the rule is applied. `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the firewall rule was created. `description` string optional Example: `an IP address for local development` A human-readable description of the rule. `type` string, one of: droplet, k8s, ip_addr, tag, app required Example: `droplet` The type of resource that the firewall rule allows to access the database cluster. `uuid` string optional Example: `79f26d28-ea8a-41f2-8ad8-8cfcdd020095` A unique ID for the firewall rule itself. `value` string required Example: `ff2a6c52-5a44-4b63-b99c-0e98e7a63d61` The ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster. `schema_registry_connection` object optional The connection details for Schema Registry. `semantic_version` string optional read-only Example: `8.0.28` A string representing the semantic version of the database engine in use for the cluster. `size` string required Example: `db-s-2vcpu-4gb` The slug identifier representing the size of the nodes in the database cluster. `standby_connection` object optional `standby_private_connection` object optional `status` string, one of: creating, online, resizing, migrating, forking optional read-only Example: `creating` A string representing the current status of the database cluster. `storage_size_mib` integer optional Example: `61440` Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage. `tags` array of string optional Nullable Example: `["production"]` An array of tags that have been applied to the database cluster. Requires `tag:read` scope. `ui_connection` object optional The connection details for OpenSearch dashboard. `users` array of object optional read-only Nullable **Show child properties** `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. `version` string optional Example: `8` A string representing the version of the database engine in use for the cluster. `version_end_of_availability` string optional read-only Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `version_end_of_life` string optional read-only Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **201** ```json { "database": { "connection": { "database": "", "host": "db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "created_at": "2019-01-11T18:37:36Z", "db_names": [ "defaultdb" ], "do_settings": { "service_cnames": [ "db.example.com", "database.myapp.io" ] }, "engine": "pg", "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "maintenance_window": { "day": "saturday", "description": [ "Update TimescaleDB to version 1.2.1", "Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases" ], "hour": "08:45:12", "pending": true }, "name": "backend", "num_nodes": 2, "private_connection": { "database": "", "host": "private-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@private-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "private_network_uuid": "d455e75d-4858-4eec-8c95-da2f0a5f93a7", "region": "nyc3", "semantic_version": "14.5", "size": "db-s-2vcpu-4gb", "standby_connection": { "database": "", "host": "replica-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@replica-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "standby_private_connection": { "database": "", "host": "private-replica-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@private-replica-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "status": "creating", "storage_size_mib": 61440, "tags": [ "production" ], "users": [ { "name": "doadmin", "password": "example_password", "role": "primary" } ], "version": "14", "version_end_of_availability": "2023-05-09T00:00:00Z", "version_end_of_life": "2023-11-09T00:00:00Z" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Existing Database Cluster `/v2/databases/{database_cluster_uuid}` To show information about an existing database cluster, send a GET request to `/v2/databases/$DATABASE_ID`. The response will be a JSON object with a database key. This will be set to an object containing the standard database cluster attributes. The embedded `connection` and `private_connection` objects will contain the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects contain the information needed to connect to the cluster's standby node(s). The embedded maintenance_window object will contain information about any scheduled maintenance for the database cluster. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() cluster, _, err := client.Databases.Get(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_cluster(database_cluster_uuid="a7a89a") ``` #### Responses **200** A JSON object with a key of database. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `database` object required **Show child properties** `connection` object optional `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the database cluster was created. `db_names` array of string optional read-only Nullable Example: `["doadmin"]` An array of strings containing the names of databases created in the database cluster. `do_settings` object optional `engine` string (enum) required Example: `mysql` A slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" for OpenSearch, "valkey" for Valkey, "advanced_pg" for PostgreSQL Advanced Edition, and "advanced_mysql" for MySQL Advanced Edition. Advanced Edition engines are currently in public preview. `id` string (uuid) optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID that can be used to identify and reference a database cluster. `maintenance_window` object optional `metrics_endpoints` array of object optional read-only Public hostname and port of the cluster's metrics endpoint(s). Includes one record for the cluster's primary node and a second entry for the cluster's standby node(s). **Show child properties** `host` string optional read-only Example: `db.example.com` A FQDN pointing to the database cluster's node(s). `port` integer optional read-only Example: `9273` The port on which a service is listening. `name` string required Example: `backend` A unique, human-readable name referring to a database cluster. `num_nodes` integer required Example: `2` The number of nodes in the database cluster. `private_connection` object optional `private_network_uuid` string optional Example: `d455e75d-4858-4eec-8c95-da2f0a5f93a7` A string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster when creating a new database cluster, it will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. `project_id` string (uuid) optional Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster, it will be assigned to your default project. Requires `project:read` scope. `region` string required Example: `nyc3` The slug identifier for the region where the database cluster is located. `rules` array of object optional **Show child properties** `cluster_uuid` string optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID for the database cluster to which the rule is applied. `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the firewall rule was created. `description` string optional Example: `an IP address for local development` A human-readable description of the rule. `type` string, one of: droplet, k8s, ip_addr, tag, app required Example: `droplet` The type of resource that the firewall rule allows to access the database cluster. `uuid` string optional Example: `79f26d28-ea8a-41f2-8ad8-8cfcdd020095` A unique ID for the firewall rule itself. `value` string required Example: `ff2a6c52-5a44-4b63-b99c-0e98e7a63d61` The ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster. `schema_registry_connection` object optional The connection details for Schema Registry. `semantic_version` string optional read-only Example: `8.0.28` A string representing the semantic version of the database engine in use for the cluster. `size` string required Example: `db-s-2vcpu-4gb` The slug identifier representing the size of the nodes in the database cluster. `standby_connection` object optional `standby_private_connection` object optional `status` string, one of: creating, online, resizing, migrating, forking optional read-only Example: `creating` A string representing the current status of the database cluster. `storage_size_mib` integer optional Example: `61440` Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage. `tags` array of string optional Nullable Example: `["production"]` An array of tags that have been applied to the database cluster. Requires `tag:read` scope. `ui_connection` object optional The connection details for OpenSearch dashboard. `users` array of object optional read-only Nullable **Show child properties** `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. `version` string optional Example: `8` A string representing the version of the database engine in use for the cluster. `version_end_of_availability` string optional read-only Example: `2023-05-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. `version_end_of_life` string optional read-only Example: `2023-11-09T00:00:00Z` A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "database": { "connection": { "database": "", "host": "db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "created_at": "2019-01-11T18:37:36Z", "db_names": [ "defaultdb" ], "do_settings": { "service_cnames": [ "db.example.com", "database.myapp.io" ] }, "engine": "pg", "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "maintenance_window": { "day": "saturday", "description": [ "Update TimescaleDB to version 1.2.1", "Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases" ], "hour": "08:45:12", "pending": true }, "name": "backend", "num_nodes": 2, "private_connection": { "database": "", "host": "private-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@private-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "private_network_uuid": "d455e75d-4858-4eec-8c95-da2f0a5f93a7", "region": "nyc3", "semantic_version": "14.5", "size": "db-s-2vcpu-4gb", "standby_connection": { "database": "", "host": "replica-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@replica-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "standby_private_connection": { "database": "", "host": "private-replica-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@private-replica-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "status": "creating", "storage_size_mib": 61440, "tags": [ "production" ], "users": [ { "name": "doadmin", "password": "example_password", "role": "primary" } ], "version": "14", "version_end_of_availability": "2023-05-09T00:00:00Z", "version_end_of_life": "2023-11-09T00:00:00Z" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Destroy a Database Cluster `/v2/databases/{database_cluster_uuid}` To destroy a specific database, send a DELETE request to `/v2/databases/$DATABASE_ID`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30" ``` ### Go ```go import ( "context" "github.com/digitalocean/godo" ) func main() { pat := "mytoken" client := godo.NewFromToken(pat) ctx := context.TODO() _, err := client.Databases.Delete(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) delete_resp = client.databases.destroy_cluster(database_cluster_uuid="a7abba8") ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Existing Database Cluster Configuration `/v2/databases/{database_cluster_uuid}/config` Shows configuration parameters for an existing database cluster by sending a GET request to `/v2/databases/$DATABASE_ID/config`. The response is a JSON object with a `config` key, which is set to an object containing any database configuration parameters. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/config` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/config" ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_config(database_cluster_uuid="a7a90ab") ``` #### Responses **200** A JSON object with a key of config. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `config` anyOf required One of: **Mysql Advanced Config** `automatic_sp_privileges` boolean optional Example: `true` When enabled, grants `EXECUTE` and `ALTER ROUTINE` privileges to the creator of a stored routine. When disabled, these privileges are not granted automatically. `backup_hour` integer optional Example: `3` The hour of day (in UTC) when backup for the service starts. New backup only starts if previous backup has already completed. `backup_minute` integer optional Example: `30` The minute of the backup hour when backup for the service starts. New backup only starts if previous backup has already completed. `binlog_retention_period` number optional Example: `600` The minimum amount of time, in seconds, to keep binlog entries before deletion. This may be extended for services that require binlog entries for longer than the default, for example if using the MySQL Debezium Kafka connector. `connect_timeout` integer optional Example: `10` The number of seconds that the mysqld server waits for a connect packet before responding with bad handshake. `default_time_zone` string optional Example: `+03:00` Default server time zone, in the form of an offset from UTC (from -12:00 to +12:00), a time zone name (EST), or 'SYSTEM' to use the MySQL server default. `div_precision_increment` integer optional Example: `4` The number of digits by which to increase the scale of the result of division operations performed with the `/` operator. `end_markers_in_json` boolean optional Example: `false` When enabled, the JSON output of `EXPLAIN FORMAT=JSON` includes end markers for nested structures. `eq_range_index_dive_limit` integer optional Example: `200` The number of equality ranges in an equality comparison condition when the optimizer should switch from using index dives to index statistics. `group_concat_max_len` integer optional Example: `1024` The maximum permitted result length, in bytes, for the GROUP_CONCAT() function. `information_schema_stats_expiry` integer optional Example: `86400` The time, in seconds, before cached statistics expire. `innodb_change_buffer_max_size` integer optional Example: `25` Specifies the maximum size of the InnoDB change buffer as a percentage of the buffer pool. `innodb_flush_neighbors` integer, one of: 0, 1, 2 optional Example: `0` Specifies whether flushing a page from the InnoDB buffer pool also flushes other dirty pages in the same extent. - 0 — disables this functionality, dirty pages in the same extent are not flushed. - 1 — flushes contiguous dirty pages in the same extent. - 2 — flushes dirty pages in the same extent. `innodb_ft_enable_stopword` boolean optional Example: `true` When enabled, the InnoDB FULLTEXT index stopword list is used. Disabled by default when a custom stopword table is configured. `innodb_ft_max_token_size` integer optional Example: `20` The maximum length of words that an InnoDB FULLTEXT index stores. Changing this parameter will lead to a restart of the MySQL service. `innodb_ft_min_token_size` integer optional Example: `3` The minimum length of words that an InnoDB FULLTEXT index stores. `innodb_ft_num_word_optimize` integer optional Example: `2000` The number of words to process during each OPTIMIZE TABLE operation on an InnoDB FULLTEXT index. `innodb_ft_result_cache_limit` integer optional Example: `2000000000` The InnoDB FULLTEXT index query result cache size limit, in bytes. `innodb_ft_server_stopword_table` string optional Example: `db_name/table_name` The InnoDB FULLTEXT index stopword list for all InnoDB tables. `innodb_ft_user_stopword_table` string optional Nullable Example: `db_name/table_name` The InnoDB FULLTEXT index stopword list for user-created FULLTEXT indexes. Must be in the form `db_name/table_name`. Set to `null` to clear a previously configured value. `innodb_lock_wait_timeout` integer optional Example: `50` The time, in seconds, that an InnoDB transaction waits for a row lock. before giving up. `innodb_log_buffer_size` integer optional Example: `16777216` The size of the buffer, in bytes, that InnoDB uses to write to the log files. on disk. `innodb_online_alter_log_max_size` integer optional Example: `134217728` The upper limit, in bytes, of the size of the temporary log files used during online DDL operations for InnoDB tables. `innodb_optimize_fulltext_only` boolean optional Example: `false` When enabled, OPTIMIZE TABLE rebuilds only the InnoDB FULLTEXT index, not the table itself. `innodb_print_all_deadlocks` boolean optional Example: `true` When enabled, records information about all deadlocks in InnoDB user transactions in the error log. Disabled by default. `innodb_read_io_threads` integer optional Example: `16` The number of I/O threads for read operations in InnoDB. Changing this parameter will lead to a restart of the MySQL service. `innodb_rollback_on_timeout` boolean optional Example: `true` When enabled, transaction timeouts cause InnoDB to abort and roll back the entire transaction. `innodb_thread_concurrency` integer optional Example: `0` Defines the maximum number of threads permitted inside of InnoDB. A value of 0 (the default) is interpreted as infinite concurrency (no limit). This variable is intended for performance tuning on high concurrency systems. `innodb_write_io_threads` integer optional Example: `16` The number of I/O threads for write operations in InnoDB. Changing this parameter will lead to a restart of the MySQL service. `interactive_timeout` integer optional Example: `3600` The time, in seconds, the server waits for activity on an interactive. connection before closing it. `internal_tmp_mem_storage_engine` string, one of: TempTable, MEMORY optional Example: `TempTable` The storage engine for in-memory internal temporary tables. `log_output` string, one of: INSIGHTS, TABLE, INSIGHTS,TABLE, NONE optional Example: `INSIGHTS` Defines the destination for logs. Can be `INSIGHTS`, `TABLE`, or both (`INSIGHTS,TABLE`), or `NONE` to disable logs. To specify both destinations, use `INSIGHTS,TABLE` (order matters). Default is NONE. `long_query_time` number optional Example: `10` The time, in seconds, for a query to take to execute before being captured by slow_query_logs. Default is 10 seconds. `max_allowed_packet` integer optional Example: `67108864` The size of the largest message, in bytes, that can be received by the server. Default is 67108864 (64M). `max_execution_time` integer optional Example: `0` The execution timeout for `SELECT` statements, in milliseconds. A value of `0` disables the timeout (no limit). `max_heap_table_size` integer optional Example: `16777216` The maximum size, in bytes, of internal in-memory tables. Also set tmp_table_size. Default is 16777216 (16M) `max_seeks_for_key` integer optional Example: `1000` Limits the assumed maximum number of seeks when looking up rows based on a key. Lower values cause the query optimizer to prefer indexes over table scans for non-covering indexes. `mysql_incremental_backup` object optional MySQL Incremental Backup configuration settings **Show child properties** `enabled` boolean optional Enable periodic incremental backups. When enabled, full_backup_week_schedule must be set. Incremental backups only store changes since the last backup, making them faster and more storage-efficient than full backups. This is particularly useful for large databases where daily full backups would be too time-consuming or expensive. `full_backup_week_schedule` string optional Example: `mon,thu` Comma-separated list of days of the week when full backups should be created. Valid values: mon, tue, wed, thu, fri, sat, sun. Default is null. Example : "mon,fri,sun". `net_buffer_length` integer optional Example: `4096` Start sizes of connection buffer and result buffer, must be multiple of 1024. Changing this parameter will lead to a restart of the MySQL service. `net_read_timeout` integer optional Example: `30` The time, in seconds, to wait for more data from an existing connection. aborting the read. `net_write_timeout` integer optional Example: `30` The number of seconds to wait for a block to be written to a connection before aborting the write. `optimizer_prune_level` integer optional Example: `1` Controls the heuristics applied during query optimization to prune less promising partial plans from the optimizer search space. `0` disables pruning and `1` enables it. `optimizer_search_depth` integer optional Example: `62` The maximum depth of search performed by the query optimizer. Smaller values can reduce compilation time for large joins; a value of `0` lets the server automatically pick a reasonable value. `optimizer_switch` string optional Example: `batched_key_access=on,hash_join=off` Controls query optimizer behavior as a comma-separated list of `option=value` pairs, or `default` to restore server defaults. Each value must be `on`, `off`, or `default`. `slow_query_log` boolean optional Example: `true` When enabled, captures slow queries. When disabled, also truncates the mysql.slow_log table. Default is false. `sort_buffer_size` integer optional Example: `262144` The sort buffer size, in bytes, for ORDER BY optimization. Default is 262144. (256K). `sql_mode` string optional Example: `ANSI,TRADITIONAL` Global SQL mode. If empty, uses MySQL server defaults. Must only include uppercase alphabetic characters, underscores, and commas. `sql_require_primary_key` boolean optional Example: `true` Require primary key to be defined for new tables or old tables modified with ALTER TABLE and fail if missing. It is recommended to always have primary keys because various functionality may break if any large table is missing them. `tmp_table_size` integer optional Example: `16777216` The maximum size, in bytes, of internal in-memory tables. Also set max_heap_table_size. Default is 16777216 (16M). `wait_timeout` integer optional Example: `28800` The number of seconds the server waits for activity on a noninteractive connection before closing it. `windowing_use_high_precision` boolean optional Example: `true` When enabled, window functions use a higher precision for internal calculations, which can be more accurate but slower. **Postgres Advanced Config** `autovacuum_analyze_scale_factor` number optional Example: `0.2` Specifies a fraction, in a decimal value, of the table size to add to autovacuum_analyze_threshold when deciding whether to trigger an ANALYZE. The default is 0.2 (20% of table size). `autovacuum_analyze_threshold` integer optional Example: `50` Specifies the minimum number of inserted, updated, or deleted tuples needed to trigger an ANALYZE in any one table. The default is 50 tuples. `autovacuum_freeze_max_age` integer optional Example: `200000000` Specifies the maximum age (in transactions) that a table's pg_class.relfrozenxid field can attain before a VACUUM operation is forced to prevent transaction ID wraparound within the table. Note that the system will launch autovacuum processes to prevent wraparound even when autovacuum is otherwise disabled. This parameter will cause the server to be restarted. `autovacuum_max_workers` integer optional Example: `5` Specifies the maximum number of autovacuum processes (other than the autovacuum launcher) that may be running at any one time. The default is three. This parameter can only be set at server start. `autovacuum_naptime` integer optional Example: `43200` Specifies the minimum delay, in seconds, between autovacuum runs on any given database. The default is one minute. `autovacuum_vacuum_cost_delay` integer optional Example: `20` Specifies the cost delay value, in milliseconds, that will be used in automatic VACUUM operations. If -1, uses the regular vacuum_cost_delay value, which is 20 milliseconds. `autovacuum_vacuum_cost_limit` integer optional Example: `-1` Specifies the cost limit value that will be used in automatic VACUUM operations. If -1 is specified (which is the default), the regular vacuum_cost_limit value will be used. `autovacuum_vacuum_scale_factor` number optional Example: `0.2` Specifies a fraction, in a decimal value, of the table size to add to autovacuum_vacuum_threshold when deciding whether to trigger a VACUUM. The default is 0.2 (20% of table size). `autovacuum_vacuum_threshold` integer optional Example: `50` Specifies the minimum number of updated or deleted tuples needed to trigger a VACUUM in any one table. The default is 50 tuples. `backup_hour` integer optional Example: `3` The hour of day (in UTC) when backup for the service starts. New backup only starts if previous backup has already completed. `backup_minute` integer optional Example: `30` The minute of the backup hour when backup for the service starts. New backup is only started if previous backup has already completed. `bgwriter_delay` integer optional Example: `200` Specifies the delay, in milliseconds, between activity rounds for the background writer. Default is 200 ms. `bgwriter_flush_after` integer optional Example: `512` The amount of kilobytes that need to be written by the background writer before attempting to force the OS to issue these writes to underlying storage. Specified in kilobytes, default is 512. Setting of 0 disables forced writeback. `bgwriter_lru_maxpages` integer optional Example: `100` The maximum number of buffers that the background writer can write. Setting this to zero disables background writing. Default is 100. `bgwriter_lru_multiplier` number optional Example: `2` The average recent need for new buffers is multiplied by bgwriter_lru_multiplier to arrive at an estimate of the number that will be needed during the next round, (up to bgwriter_lru_maxpages). 1.0 represents a “just in time” policy of writing exactly the number of buffers predicted to be needed. Larger values provide some cushion against spikes in demand, while smaller values intentionally leave writes to be done by server processes. The default is 2.0. `deadlock_timeout` integer optional Example: `1000` The amount of time, in milliseconds, to wait on a lock before checking to see if there is a deadlock condition. `default_toast_compression` string, one of: lz4, pglz optional Example: `lz4` Specifies the default TOAST compression method for values of compressible columns (the default is lz4). `idle_in_transaction_session_timeout` integer optional Example: `10000` Time out sessions with open transactions after this number of milliseconds `jit` boolean optional Example: `true` Activates, in a boolean, the system-wide use of Just-in-Time Compilation (JIT). `log_autovacuum_min_duration` integer optional Example: `-1` Causes each action executed by autovacuum to be logged if it ran for at least the specified number of milliseconds. Setting this to zero logs all autovacuum actions. Minus-one (the default) disables logging autovacuum actions. `log_error_verbosity` string, one of: TERSE, DEFAULT, VERBOSE optional Example: `VERBOSE` Controls the amount of detail written in the server log for each message that is logged. `log_line_prefix` string, one of: pid=%p,user=%u,db=%d,app=%a,client=%h, %m \[%p] %q\[user=%u,db=%d,app=%a], %t \[%p]: \[%l-1] user=%u,db=%d,app=%a,client=%h optional Example: `pid=%p,user=%u,db=%d,app=%a,client=%h` Selects one of the available log-formats. These can support popular log analyzers like pgbadger, pganalyze, etc. `log_min_duration_statement` integer optional Example: `-1` Log statements that take more than this number of milliseconds to run. If -1, disables. `max_connections` integer optional Example: `75` Sets the PostgreSQL maximum number of concurrent connections to the database server. This is a limited-release parameter. Contact your account team to confirm your eligibility. You cannot decrease this parameter value when set. For services with a read replica, first increase the read replica's value. After the change is applied to the replica, you can increase the primary service's value. Changing this parameter causes a service restart. `max_failover_replication_time_lag` integer optional Example: `50` Number of seconds of master unavailability before triggering database failover to standby. The default value is 60. `max_files_per_process` integer optional Example: `2048` PostgreSQL maximum number of files that can be open per process. `max_locks_per_transaction` integer optional Example: `128` PostgreSQL maximum locks per transaction. Once increased, this parameter cannot be lowered from its set value. `max_logical_replication_workers` integer optional Example: `16` PostgreSQL maximum logical replication workers (taken from the pool of max_parallel_workers). `max_parallel_workers` integer optional Example: `12` Sets the maximum number of workers that the system can support for parallel queries. `max_parallel_workers_per_gather` integer optional Example: `16` Sets the maximum number of workers that can be started by a single Gather or Gather Merge node. `max_pred_locks_per_transaction` integer optional Example: `128` PostgreSQL maximum predicate locks per transaction. `max_prepared_transactions` integer optional Example: `20` PostgreSQL maximum prepared transactions. Once increased, this parameter cannot be lowered from its set value. `max_replication_slots` integer optional Example: `16` PostgreSQL maximum replication slots. `max_slot_wal_keep_size` integer optional Example: `100` PostgreSQL maximum WAL size (MB) reserved for replication slots. If -1 is specified, replication slots may retain an unlimited amount of WAL files. The default is -1 (upstream default). wal_keep_size minimum WAL size setting takes precedence over this. `max_stack_depth` integer optional Example: `2097152` Maximum depth of the stack in bytes. `max_standby_archive_delay` integer optional Example: `43200` Max standby archive delay in milliseconds. `max_standby_streaming_delay` integer optional Example: `43200` Max standby streaming delay in milliseconds. `max_wal_senders` integer optional Example: `32` PostgreSQL maximum WAL senders. Once increased, this parameter cannot be lowered from its set value. `max_worker_processes` integer optional Example: `16` Sets the maximum number of background processes that the system can support. Once increased, this parameter cannot be lowered from its set value. `pg_partman_bgw.interval` integer optional Example: `3600` Sets the time interval to run pg_partman's scheduled tasks. `pg_partman_bgw.role` string optional Example: `myrolename` Controls which role to use for pg_partman's scheduled background tasks. Must consist of alpha-numeric characters, dots, underscores, or dashes. May not start with dash or dot. Maximum of 64 characters. `pg_stat_statements.track` string, one of: all, top, none optional Example: `all` Controls which statements are counted. Specify 'top' to track top-level statements (those issued directly by clients), 'all' to also track nested statements (such as statements invoked within functions), or 'none' to disable statement statistics collection. The default value is top. `pgaudit` object optional System-wide settings for the pgaudit extension. When `feature_enabled` is true, the pgaudit extension is automatically installed. When false, the extension is uninstalled but auditing configurations (such as `log`) are preserved. **Show child properties** `feature_enabled` boolean optional Example: `false` Enable pgaudit extension. When enabled, pgaudit extension will be automatically installed. Otherwise, extension will be uninstalled but auditing configurations will be preserved. `log` array of string (enum) optional Example: `["read","write","ddl"]` Specifies which classes of statements will be logged by session audit logging. Available values are `read` (SELECT and COPY when the source is a relation or query), `write` (INSERT, UPDATE, DELETE, TRUNCATE, and COPY when the destination is a relation), `function` (function calls and DO blocks), `role` (statements related to roles and privileges: GRANT, REVOKE, CREATE/ALTER/DROP ROLE), `ddl` (all DDL that is not included in the role class), `misc` (miscellaneous commands, e.g. DISCARD, FETCH, CHECKPOINT, VACUUM, SET), `misc_set` (miscellaneous SET commands, e.g. SET ROLE), and `all` (include all of the above). `pgbouncer` object optional PGBouncer connection pooling settings **Show child properties** `autodb_idle_timeout` integer optional Example: `3600` If the automatically-created database pools have been unused this many seconds, they are freed. If 0, timeout is disabled. `autodb_max_db_connections` integer optional Example: `1` Only allows a maximum this many server connections per database (regardless of user). If 0, allows unlimited connections. `autodb_pool_mode` string, one of: session, transaction, statement optional Example: `session` PGBouncer pool mode `autodb_pool_size` integer optional Example: `1` If non-zero, automatically creates a pool of that size per user when a pool doesn't exist. `ignore_startup_parameters` array of string, one of: extra_float_digits, search_path optional Example: `["extra_float_digits","search_path"]` List of parameters to ignore when given in startup packet. `min_pool_size` integer optional Example: `1` If current server connections are below this number, adds more. Improves behavior when usual load comes suddenly back after period of total inactivity. The value is effectively capped at the pool size. `server_idle_timeout` integer optional Example: `600` Drops server connections if they have been idle more than this many seconds. If 0, timeout is disabled. `server_lifetime` integer optional Example: `3600` The pooler closes any unused server connection that has been connected longer than this amount of seconds. `server_reset_query_always` boolean optional Example: `false` Run server_reset_query (DISCARD ALL) in all pooling modes. `shared_buffers_percentage` number optional Example: `41.5` Percentage of total RAM that the database server uses for shared memory buffers. Valid range is 20-60 (float), which corresponds to 20% - 60%. This setting adjusts the shared_buffers configuration value. `stat_monitor_enable` boolean optional Example: `false` Enable the pg_stat_monitor extension. **Enabling this extension will cause the cluster to be restarted.** When this extension is enabled, pg_stat_statements results for utility commands are unreliable. `synchronous_replication` string, one of: off, quorum optional Example: `off` Synchronous replication type. Note that the service plan also needs to support synchronous replication. `temp_file_limit` integer optional Example: `5000000` PostgreSQL temporary file limit in KiB. If -1, sets to unlimited. `timescaledb` object optional TimescaleDB extension configuration values **Show child properties** `max_background_workers` integer optional Example: `8` The number of background workers for timescaledb operations. Set to the sum of your number of databases and the total number of concurrent background workers you want running at any given point in time. `timezone` string optional Example: `Europe/Helsinki` PostgreSQL service timezone `track_activity_query_size` integer optional Example: `1024` Specifies the number of bytes reserved to track the currently executing command for each active session. `track_commit_timestamp` string, one of: off, on optional Example: `off` Record commit time of transactions. `track_functions` string, one of: all, pl, none optional Example: `all` Enables tracking of function call counts and time used. `track_io_timing` string, one of: off, on optional Example: `off` Enables timing of database I/O calls. This parameter is off by default, because it will repeatedly query the operating system for the current time, which may cause significant overhead on some platforms. `wal_sender_timeout` integer optional Example: `60000` Terminate replication connections that are inactive for longer than this amount of time, in milliseconds. Setting this value to zero disables the timeout. Must be either 0 or between 5000 and 10800000. `wal_writer_delay` integer optional Example: `50` WAL flush interval in milliseconds. Note that setting this value to lower than the default 200ms may negatively impact performance `work_mem` integer optional Example: `4` The maximum amount of memory, in MB, used by a query operation (such as a sort or hash table) before writing to temporary disk files. Default is 1MB + 0.075% of total RAM (up to 32MB). **Redis Advanced Config** `redis_acl_channels_default` string, one of: allchannels, resetchannels optional Example: `allchannels` Determines default pub/sub channels' ACL for new users if ACL is not supplied. When this option is not defined, all_channels is assumed to keep backward compatibility. This option doesn't affect Caching configuration acl-pubsub-default. `redis_io_threads` integer optional Example: `1` Caching IO thread count `redis_lfu_decay_time` integer optional Example: `1` LFU maxmemory-policy counter decay time in minutes `redis_lfu_log_factor` integer optional Example: `10` Counter logarithm factor for volatile-lfu and allkeys-lfu maxmemory-policies `redis_maxmemory_policy` string (enum) optional Example: `allkeys-lru` A string specifying the desired eviction policy for the Caching cluster. - `noeviction`: Don't evict any data, returns error when memory limit is reached. - `allkeys-lru:` Evict any key, least recently used (LRU) first. - `allkeys-random`: Evict keys in a random order. - `volatile-lru`: Evict keys with expiration only, least recently used (LRU) first. - `volatile-random`: Evict keys with expiration only in a random order. - `volatile-ttl`: Evict keys with expiration only, shortest time-to-live (TTL) first. `redis_notify_keyspace_events` string optional Example: `K` Set notify-keyspace-events option. Requires at least `K` or `E` and accepts any combination of the following options. Setting the parameter to `""` disables notifications. - `K` — Keyspace events - `E` — Keyevent events - `g` — Generic commands (e.g. `DEL`, `EXPIRE`, `RENAME`, ...) - `$` — String commands - `l` — List commands - `s` — Set commands - `h` — Hash commands - `z` — Sorted set commands - `t` — Stream commands - `d` — Module key type events - `x` — Expired events - `e` — Evicted events - `m` — Key miss events - `n` — New key events - `A` — Alias for `"g$lshztxed"` `redis_number_of_databases` integer optional Example: `16` Set number of redis databases. Changing this will cause a restart of redis service. `redis_persistence` string, one of: off, rdb optional Example: `rdb` Creates an RDB dump of the database every 10 minutes that can be used to recover data after a node crash. The database does not create the dump if no keys have changed since the last dump. When set to `off`, the database cannot fork services, and data can be lost if a service is restarted or powered off. DigitalOcean Managed Caching databases do not support the Append Only File (AOF) persistence method. `redis_pubsub_client_output_buffer_limit` integer optional Example: `64` Set output buffer limit for pub / sub clients in MB. The value is the hard limit, the soft limit is 1/4 of the hard limit. When setting the limit, be mindful of the available memory in the selected service plan. `redis_ssl` boolean optional Example: `true` Require SSL to access Caching. - When enabled, Caching accepts only SSL connections on port `25061`. - When disabled, port `25060` is opened for non-SSL connections, while port `25061` remains available for SSL connections. `redis_timeout` integer optional Example: `300` Caching idle connection timeout in seconds **Valkey Advanced Config** `frequent_snapshots` boolean optional Example: `true` Frequent RDB snapshots When enabled, Valkey will create frequent local RDB snapshots. When disabled, Valkey will only take RDB snapshots when a backup is created, based on the backup schedule. This setting is ignored when valkey_persistence is set to off. `valkey_acl_channels_default` string, one of: allchannels, resetchannels optional Example: `allchannels` Determines default pub/sub channels' ACL for new users if ACL is not supplied. When this option is not defined, all_channels is assumed to keep backward compatibility. This option doesn't affect Valkey configuration acl-pubsub-default. `valkey_active_expire_effort` integer optional Example: `1` Active expire effort Valkey reclaims expired keys both when accessed and in the background. The background process scans for expired keys to free memory. Increasing the active-expire-effort setting (default 1, max 10) uses more CPU to reclaim expired keys faster, reducing memory usage but potentially increasing latency. `valkey_io_threads` integer optional Example: `1` Valkey IO thread count `valkey_lfu_decay_time` integer optional Example: `1` LFU maxmemory-policy counter decay time in minutes `valkey_lfu_log_factor` integer optional Example: `10` Counter logarithm factor for volatile-lfu and allkeys-lfu maxmemory-policies `valkey_maxmemory_policy` string (enum) optional Example: `allkeys_lru` A string specifying the desired eviction policy for a Caching or Valkey cluster. - `noeviction`: Don't evict any data, returns error when memory limit is reached. - `allkeys_lru:` Evict any key, least recently used (LRU) first. - `allkeys_random`: Evict keys in a random order. - `volatile_lru`: Evict keys with expiration only, least recently used (LRU) first. - `volatile_random`: Evict keys with expiration only in a random order. - `volatile_ttl`: Evict keys with expiration only, shortest time-to-live (TTL) first. `valkey_notify_keyspace_events` string optional Example: `K` Set notify-keyspace-events option. Requires at least `K` or `E` and accepts any combination of the following options. Setting the parameter to `""` disables notifications. - `K` — Keyspace events - `E` — Keyevent events - `g` — Generic commands (e.g. `DEL`, `EXPIRE`, `RENAME`, ...) - `$` — String commands - `l` — List commands - `s` — Set commands - `h` — Hash commands - `z` — Sorted set commands - `t` — Stream commands - `d` — Module key type events - `x` — Expired events - `e` — Evicted events - `m` — Key miss events - `n` — New key events - `A` — Alias for `"g$lshztxed"` `valkey_number_of_databases` integer optional Example: `16` Set number of valkey databases. Changing this will cause a restart of valkey service. `valkey_persistence` string, one of: off, rdb optional Example: `rdb` When persistence is 'rdb', Valkey does RDB dumps each 10 minutes if any key is changed. Also RDB dumps are done according to backup schedule for backup purposes. When persistence is 'off', no RDB dumps and backups are done, so data can be lost at any moment if service is restarted for any reason, or if service is powered off. Also service can't be forked. `valkey_pubsub_client_output_buffer_limit` integer optional Example: `64` Set output buffer limit for pub / sub clients in MB. The value is the hard limit, the soft limit is 1/4 of the hard limit. When setting the limit, be mindful of the available memory in the selected service plan. `valkey_ssl` boolean optional Example: `true` Require SSL to access Valkey `valkey_timeout` integer optional Example: `300` Valkey idle connection timeout in seconds **Kafka Advanced Config** `auto_create_topics_enable` boolean optional Example: `true` Enable auto creation of topics `compression_type` string (enum) optional Example: `gzip` Specify the final compression type for a given topic. This configuration accepts the standard compression codecs ('gzip', 'snappy', 'lz4', 'zstd'). It additionally accepts 'uncompressed' which is equivalent to no compression; and 'producer' which means retain the original compression codec set by the producer. `connections_max_idle_ms` integer optional Example: `540000` Idle connections timeout: the server socket processor threads close the connections that idle for longer than this. `default_replication_factor` integer optional Example: `2` Replication factor for autocreated topics `group_initial_rebalance_delay_ms` integer optional Example: `3000` The amount of time, in milliseconds, the group coordinator will wait for more consumers to join a new group before performing the first rebalance. A longer delay means potentially fewer rebalances, but increases the time until processing begins. The default value for this is 3 seconds. During development and testing it might be desirable to set this to 0 in order to not delay test execution time. `group_max_session_timeout_ms` integer optional Example: `1800000` The maximum allowed session timeout for registered consumers. Longer timeouts give consumers more time to process messages in between heartbeats at the cost of a longer time to detect failures. `group_min_session_timeout_ms` integer optional Example: `6000` The minimum allowed session timeout for registered consumers. Longer timeouts give consumers more time to process messages in between heartbeats at the cost of a longer time to detect failures. `log_cleaner_delete_retention_ms` integer optional Example: `86400000` How long are delete records retained? `log_cleaner_max_compaction_lag_ms` integer optional Example: `60000` The maximum amount of time message will remain uncompacted. Only applicable for logs that are being compacted `log_cleaner_min_cleanable_ratio` number optional Example: `0.5` Controls log compactor frequency. Larger value means more frequent compactions but also more space wasted for logs. Consider setting log_cleaner_max_compaction_lag_ms to enforce compactions sooner, instead of setting a very high value for this option. `log_cleaner_min_compaction_lag_ms` integer optional Example: `100000` The minimum time a message will remain uncompacted in the log. Only applicable for logs that are being compacted. `log_cleanup_policy` string, one of: delete, compact, compact,delete optional Example: `delete` The default cleanup policy for segments beyond the retention window `log_flush_interval_messages` integer optional Example: `9223372036854776000` The number of messages accumulated on a log partition before messages are flushed to disk `log_flush_interval_ms` integer optional Example: `1000000` The maximum time in ms that a message in any topic is kept in memory before flushed to disk. If not set, the value in log.flush.scheduler.interval.ms is used `log_index_interval_bytes` integer optional Example: `4096` The interval with which Kafka adds an entry to the offset index `log_index_size_max_bytes` integer optional Example: `10485760` The maximum size in bytes of the offset index `log_message_downconversion_enable` boolean optional Example: `true` This configuration controls whether down-conversion of message formats is enabled to satisfy consume requests. `log_message_timestamp_difference_max_ms` integer optional Example: `1000000` The maximum difference allowed between the timestamp when a broker receives a message and the timestamp specified in the message `log_message_timestamp_type` string, one of: CreateTime, LogAppendTime optional Example: `CreateTime` Define whether the timestamp in the message is message create time or log append time. `log_preallocate` boolean optional Example: `false` Controls whether to preallocate a file when creating a new segment `log_retention_bytes` integer optional Example: `1000000` The maximum size of the log before deleting messages `log_retention_hours` integer optional Example: `1000000` The number of hours to keep a log file before deleting it `log_retention_ms` integer optional Example: `100000000` The number of milliseconds to keep a log file before deleting it (in milliseconds), If not set, the value in log.retention.minutes is used. If set to -1, no time limit is applied. `log_roll_jitter_ms` integer optional Example: `10000000` The maximum jitter to subtract from logRollTimeMillis (in milliseconds). If not set, the value in log.roll.jitter.hours is used `log_roll_ms` integer optional Example: `1000000` The maximum time before a new log segment is rolled out (in milliseconds). `log_segment_bytes` integer optional Example: `100000000` The maximum size of a single log file `log_segment_delete_delay_ms` integer optional Example: `60000` The amount of time to wait before deleting a file from the filesystem `max_connections_per_ip` integer optional Example: `512` The maximum number of connections allowed from each ip address (defaults to 2147483647). `max_incremental_fetch_session_cache_slots` integer optional Example: `1000` The maximum number of incremental fetch sessions that the broker will maintain. `message_max_bytes` integer optional Example: `1048588` The maximum size of message that the server can receive. `min_insync_replicas` integer optional Example: `1` When a producer sets acks to 'all' (or '-1'), min_insync_replicas specifies the minimum number of replicas that must acknowledge a write for the write to be considered successful. `num_partitions` integer optional Example: `10` Number of partitions for autocreated topics `offsets_retention_minutes` integer optional Example: `10080` Log retention window in minutes for offsets topic `producer_purgatory_purge_interval_requests` integer optional Example: `100` The purge interval (in number of requests) of the producer request purgatory (defaults to 1000). `replica_fetch_max_bytes` integer optional Example: `2097152` The number of bytes of messages to attempt to fetch for each partition (defaults to 1048576). This is not an absolute maximum, if the first record batch in the first non-empty partition of the fetch is larger than this value, the record batch will still be returned to ensure that progress can be made. `replica_fetch_response_max_bytes` integer optional Example: `20971520` Maximum bytes expected for the entire fetch response (defaults to 10485760). Records are fetched in batches, and if the first record batch in the first non-empty partition of the fetch is larger than this value, the record batch will still be returned to ensure that progress can be made. As such, this is not an absolute maximum. `schema_registry` boolean optional Example: `true` Enable creation of schema registry for the Kafka cluster. Schema_registry only works with General Purpose - Dedicated CPU plans. `socket_request_max_bytes` integer optional Example: `20971520` The maximum number of bytes in a socket request (defaults to 104857600). `transaction_remove_expired_transaction_cleanup_interval_ms` integer optional Example: `3600000` The interval at which to remove transactions that have expired due to transactional.id.expiration.ms passing (defaults to 3600000 (1 hour)). `transaction_state_log_segment_bytes` integer optional Example: `104857600` The transaction topic segment bytes should be kept relatively small in order to facilitate faster log compaction and cache loads (defaults to 104857600 (100 mebibytes)). **Opensearch Advanced Config** `action_auto_create_index_enabled` boolean optional Example: `true` Specifices whether to allow automatic creation of indices. `action_destructive_requires_name` boolean optional Example: `false` Specifies whether to require explicit index names when deleting indices. `cluster_max_shards_per_node` integer optional Example: `100` Maximum number of shards allowed per data node. `cluster_routing_allocation_node_concurrent_recoveries` integer optional Example: `2` Maximum concurrent incoming/outgoing shard recoveries (normally replicas) are allowed to happen per node . `enable_security_audit` boolean optional Example: `false` Specifies whether to allow security audit logging. `http_max_content_length_bytes` integer optional Example: `100000000` Maximum content length for HTTP requests to the OpenSearch HTTP API, in bytes. `http_max_header_size_bytes` integer optional Example: `8192` Maximum size of allowed headers, in bytes. `http_max_initial_line_length_bytes` integer optional Example: `4096` Maximum length of an HTTP URL, in bytes. `indices_fielddata_cache_size_percentage` integer optional Example: `3` Maximum amount of heap memory used for field data cache, expressed as a percentage. Decreasing the value too much will increase overhead of loading field data. Increasing the value too much will decrease amount of heap available for other operations. `indices_memory_index_buffer_size_percentage` integer optional Example: `10` Total amount of heap used for indexing buffer before writing segments to disk, expressed as a percentage. Too low value will slow down indexing; too high value will increase indexing performance but causes performance issues for query performance. `indices_memory_max_index_buffer_size_mb` integer optional Example: `48` Maximum amount of heap used for indexing buffer before writing segments to disk, in mb. Works in conjunction with indices_memory_index_buffer_size_percentage, each being enforced. The default is unbounded. `indices_memory_min_index_buffer_size_mb` integer optional Example: `48` Minimum amount of heap used for indexing buffer before writing segments to disk, in mb. Works in conjunction with indices_memory_index_buffer_size_percentage, each being enforced. `indices_queries_cache_size_percentage` integer optional Example: `10` Maximum amount of heap used for query cache. Too low value will decrease query performance and increase performance for other operations; too high value will cause issues with other functionality. `indices_query_bool_max_clause_count` integer optional Example: `1024` Maximum number of clauses Lucene BooleanQuery can have. Only increase it if necessary, as it may cause performance issues. `indices_recovery_max_concurrent_file_chunks` integer optional Example: `2` Maximum number of file chunks sent in parallel for each recovery. `indices_recovery_max_mb_per_sec` integer optional Example: `40` Limits total inbound and outbound recovery traffic for each node, expressed in mb per second. Applies to both peer recoveries as well as snapshot recoveries (i.e., restores from a snapshot). `ism_enabled` boolean optional Example: `true` Specifies whether ISM is enabled or not. `ism_history_enabled` boolean optional Example: `true` Specifies whether audit history is enabled or not. The logs from ISM are automatically indexed to a logs document. `ism_history_max_age_hours` integer optional Example: `24` Maximum age before rolling over the audit history index, in hours. `ism_history_max_docs` integer optional Example: `2500000` Maximum number of documents before rolling over the audit history index. `ism_history_rollover_check_period_hours` integer optional Example: `8` The time between rollover checks for the audit history index, in hours. `ism_history_rollover_retention_period_days` integer optional Example: `30` Length of time long audit history indices are kept, in days. `keep_index_refresh_interval` boolean optional Example: `true` DigitalOcean automatically resets the `index.refresh_interval` to the default value (once per second) to ensure that new documents are quickly available for search queries. If you are setting your own refresh intervals, you can disable this by setting this field to true. `knn_memory_circuit_breaker_enabled` boolean optional Example: `true` Enable or disable KNN memory circuit breaker. `knn_memory_circuit_breaker_limit` integer optional Example: `60` Maximum amount of memory in percentage that can be used for the KNN index. Defaults to 50% of the JVM heap size. 0 is used to set it to null which can be used to invalidate caches. `override_main_response_version` boolean optional Example: `false` Compatibility mode sets OpenSearch to report its version as 7.10 so clients continue to work. `plugins_alerting_filter_by_backend_roles_enabled` boolean optional Example: `false` Enable or disable filtering of alerting by backend roles. `reindex_remote_whitelist` array of string optional Example: `["255.255.223.233:9200","222.33.222.222:6300"]` Allowlist of remote IP addresses for reindexing. Changing this value will cause all OpenSearch instances to restart. `script_max_compilations_rate` string optional Example: `75/5m` Limits the number of inline script compilations within a period of time. Default is use-context `search_max_buckets` integer optional Example: `10000` Maximum number of aggregation buckets allowed in a single response. `thread_pool_analyze_queue_size` integer optional Example: `10` Size of queue for operations in the analyze thread pool. `thread_pool_analyze_size` integer optional Example: `1` Number of workers in the analyze operation thread pool. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_force_merge_size` integer optional Example: `1` Number of workers in the force merge operation thread pool. This pool is used for forcing a merge between shards of one or more indices. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_get_queue_size` integer optional Example: `10` Size of queue for operations in the get thread pool. `thread_pool_get_size` integer optional Example: `1` Number of workers in the get operation thread pool. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_search_queue_size` integer optional Example: `10` Size of queue for operations in the search thread pool. `thread_pool_search_size` integer optional Example: `1` Number of workers in the search operation thread pool. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_search_throttled_queue_size` integer optional Example: `10` Size of queue for operations in the search throttled thread pool. `thread_pool_search_throttled_size` integer optional Example: `1` Number of workers in the search throttled operation thread pool. This pool is used for searching frozen indices. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_write_queue_size` integer optional Example: `10` Size of queue for operations in the write thread pool. `thread_pool_write_size` integer optional Example: `1` Number of workers in the write operation thread pool. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. **Mongo Advanced Config** `default_read_concern` string, one of: local, available, majority optional Example: `local` Specifies the default consistency behavior of reads from the database. Data that is returned from the query with may or may not have been acknowledged by all nodes in the replicaset depending on this value. Learn more [here](https://www.mongodb.com/docs/manual/reference/read-concern/). `default_write_concern` string optional Example: `majority` Describes the level of acknowledgment requested from MongoDB for write operations clusters. This field can set to either `majority` or a number `0...n` which will describe the number of nodes that must acknowledge the write operation before it is fully accepted. Setting to `0` will request no acknowledgement of the write operation. Learn more [here](https://www.mongodb.com/docs/manual/reference/write-concern/). `slow_op_threshold_ms` integer optional Example: `200` Operations that run for longer than this threshold are considered slow which are then recorded to the diagnostic logs. Higher log levels (verbosity) will record all operations regardless of this threshold on the primary node. *Changing this parameter will lead to a restart of the MongoDB service.* Learn more [here](https://www.mongodb.com/docs/manual/reference/configuration-options/#mongodb-setting-operationProfiling.slowOpThresholdMs). `transaction_lifetime_limit_seconds` integer optional Example: `100` Specifies the lifetime of multi-document transactions. Transactions that exceed this limit are considered expired and will be aborted by a periodic cleanup process. The cleanup process runs every `transactionLifetimeLimitSeconds/2 seconds` or at least once every 60 seconds. *Changing this parameter will lead to a restart of the MongoDB service.* Learn more [here](https://www.mongodb.com/docs/manual/reference/parameters/#mongodb-parameter-param.transactionLifetimeLimitSeconds). `verbosity` integer optional Example: `3` The log message verbosity level. The verbosity level determines the amount of Informational and Debug messages MongoDB outputs. 0 includes informational messages while 1...5 increases the level to include debug messages. *Changing this parameter will lead to a restart of the MongoDB service.* Learn more [here](https://www.mongodb.com/docs/manual/reference/configuration-options/#mongodb-setting-systemLog.verbosity). **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "config": { "sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES", "sql_require_primary_key": true } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PATCH Update the Database Configuration for an Existing Database `/v2/databases/{database_cluster_uuid}/config` To update the configuration for an existing database cluster, send a PATCH request to `/v2/databases/$DATABASE_ID/config`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `config` anyOf optional One of: **Mysql Advanced Config** `automatic_sp_privileges` boolean optional Example: `true` When enabled, grants `EXECUTE` and `ALTER ROUTINE` privileges to the creator of a stored routine. When disabled, these privileges are not granted automatically. `backup_hour` integer optional Example: `3` The hour of day (in UTC) when backup for the service starts. New backup only starts if previous backup has already completed. `backup_minute` integer optional Example: `30` The minute of the backup hour when backup for the service starts. New backup only starts if previous backup has already completed. `binlog_retention_period` number optional Example: `600` The minimum amount of time, in seconds, to keep binlog entries before deletion. This may be extended for services that require binlog entries for longer than the default, for example if using the MySQL Debezium Kafka connector. `connect_timeout` integer optional Example: `10` The number of seconds that the mysqld server waits for a connect packet before responding with bad handshake. `default_time_zone` string optional Example: `+03:00` Default server time zone, in the form of an offset from UTC (from -12:00 to +12:00), a time zone name (EST), or 'SYSTEM' to use the MySQL server default. `div_precision_increment` integer optional Example: `4` The number of digits by which to increase the scale of the result of division operations performed with the `/` operator. `end_markers_in_json` boolean optional Example: `false` When enabled, the JSON output of `EXPLAIN FORMAT=JSON` includes end markers for nested structures. `eq_range_index_dive_limit` integer optional Example: `200` The number of equality ranges in an equality comparison condition when the optimizer should switch from using index dives to index statistics. `group_concat_max_len` integer optional Example: `1024` The maximum permitted result length, in bytes, for the GROUP_CONCAT() function. `information_schema_stats_expiry` integer optional Example: `86400` The time, in seconds, before cached statistics expire. `innodb_change_buffer_max_size` integer optional Example: `25` Specifies the maximum size of the InnoDB change buffer as a percentage of the buffer pool. `innodb_flush_neighbors` integer, one of: 0, 1, 2 optional Example: `0` Specifies whether flushing a page from the InnoDB buffer pool also flushes other dirty pages in the same extent. - 0 — disables this functionality, dirty pages in the same extent are not flushed. - 1 — flushes contiguous dirty pages in the same extent. - 2 — flushes dirty pages in the same extent. `innodb_ft_enable_stopword` boolean optional Example: `true` When enabled, the InnoDB FULLTEXT index stopword list is used. Disabled by default when a custom stopword table is configured. `innodb_ft_max_token_size` integer optional Example: `20` The maximum length of words that an InnoDB FULLTEXT index stores. Changing this parameter will lead to a restart of the MySQL service. `innodb_ft_min_token_size` integer optional Example: `3` The minimum length of words that an InnoDB FULLTEXT index stores. `innodb_ft_num_word_optimize` integer optional Example: `2000` The number of words to process during each OPTIMIZE TABLE operation on an InnoDB FULLTEXT index. `innodb_ft_result_cache_limit` integer optional Example: `2000000000` The InnoDB FULLTEXT index query result cache size limit, in bytes. `innodb_ft_server_stopword_table` string optional Example: `db_name/table_name` The InnoDB FULLTEXT index stopword list for all InnoDB tables. `innodb_ft_user_stopword_table` string optional Nullable Example: `db_name/table_name` The InnoDB FULLTEXT index stopword list for user-created FULLTEXT indexes. Must be in the form `db_name/table_name`. Set to `null` to clear a previously configured value. `innodb_lock_wait_timeout` integer optional Example: `50` The time, in seconds, that an InnoDB transaction waits for a row lock. before giving up. `innodb_log_buffer_size` integer optional Example: `16777216` The size of the buffer, in bytes, that InnoDB uses to write to the log files. on disk. `innodb_online_alter_log_max_size` integer optional Example: `134217728` The upper limit, in bytes, of the size of the temporary log files used during online DDL operations for InnoDB tables. `innodb_optimize_fulltext_only` boolean optional Example: `false` When enabled, OPTIMIZE TABLE rebuilds only the InnoDB FULLTEXT index, not the table itself. `innodb_print_all_deadlocks` boolean optional Example: `true` When enabled, records information about all deadlocks in InnoDB user transactions in the error log. Disabled by default. `innodb_read_io_threads` integer optional Example: `16` The number of I/O threads for read operations in InnoDB. Changing this parameter will lead to a restart of the MySQL service. `innodb_rollback_on_timeout` boolean optional Example: `true` When enabled, transaction timeouts cause InnoDB to abort and roll back the entire transaction. `innodb_thread_concurrency` integer optional Example: `0` Defines the maximum number of threads permitted inside of InnoDB. A value of 0 (the default) is interpreted as infinite concurrency (no limit). This variable is intended for performance tuning on high concurrency systems. `innodb_write_io_threads` integer optional Example: `16` The number of I/O threads for write operations in InnoDB. Changing this parameter will lead to a restart of the MySQL service. `interactive_timeout` integer optional Example: `3600` The time, in seconds, the server waits for activity on an interactive. connection before closing it. `internal_tmp_mem_storage_engine` string, one of: TempTable, MEMORY optional Example: `TempTable` The storage engine for in-memory internal temporary tables. `log_output` string, one of: INSIGHTS, TABLE, INSIGHTS,TABLE, NONE optional Example: `INSIGHTS` Defines the destination for logs. Can be `INSIGHTS`, `TABLE`, or both (`INSIGHTS,TABLE`), or `NONE` to disable logs. To specify both destinations, use `INSIGHTS,TABLE` (order matters). Default is NONE. `long_query_time` number optional Example: `10` The time, in seconds, for a query to take to execute before being captured by slow_query_logs. Default is 10 seconds. `max_allowed_packet` integer optional Example: `67108864` The size of the largest message, in bytes, that can be received by the server. Default is 67108864 (64M). `max_execution_time` integer optional Example: `0` The execution timeout for `SELECT` statements, in milliseconds. A value of `0` disables the timeout (no limit). `max_heap_table_size` integer optional Example: `16777216` The maximum size, in bytes, of internal in-memory tables. Also set tmp_table_size. Default is 16777216 (16M) `max_seeks_for_key` integer optional Example: `1000` Limits the assumed maximum number of seeks when looking up rows based on a key. Lower values cause the query optimizer to prefer indexes over table scans for non-covering indexes. `mysql_incremental_backup` object optional MySQL Incremental Backup configuration settings **Show child properties** `enabled` boolean optional Enable periodic incremental backups. When enabled, full_backup_week_schedule must be set. Incremental backups only store changes since the last backup, making them faster and more storage-efficient than full backups. This is particularly useful for large databases where daily full backups would be too time-consuming or expensive. `full_backup_week_schedule` string optional Example: `mon,thu` Comma-separated list of days of the week when full backups should be created. Valid values: mon, tue, wed, thu, fri, sat, sun. Default is null. Example : "mon,fri,sun". `net_buffer_length` integer optional Example: `4096` Start sizes of connection buffer and result buffer, must be multiple of 1024. Changing this parameter will lead to a restart of the MySQL service. `net_read_timeout` integer optional Example: `30` The time, in seconds, to wait for more data from an existing connection. aborting the read. `net_write_timeout` integer optional Example: `30` The number of seconds to wait for a block to be written to a connection before aborting the write. `optimizer_prune_level` integer optional Example: `1` Controls the heuristics applied during query optimization to prune less promising partial plans from the optimizer search space. `0` disables pruning and `1` enables it. `optimizer_search_depth` integer optional Example: `62` The maximum depth of search performed by the query optimizer. Smaller values can reduce compilation time for large joins; a value of `0` lets the server automatically pick a reasonable value. `optimizer_switch` string optional Example: `batched_key_access=on,hash_join=off` Controls query optimizer behavior as a comma-separated list of `option=value` pairs, or `default` to restore server defaults. Each value must be `on`, `off`, or `default`. `slow_query_log` boolean optional Example: `true` When enabled, captures slow queries. When disabled, also truncates the mysql.slow_log table. Default is false. `sort_buffer_size` integer optional Example: `262144` The sort buffer size, in bytes, for ORDER BY optimization. Default is 262144. (256K). `sql_mode` string optional Example: `ANSI,TRADITIONAL` Global SQL mode. If empty, uses MySQL server defaults. Must only include uppercase alphabetic characters, underscores, and commas. `sql_require_primary_key` boolean optional Example: `true` Require primary key to be defined for new tables or old tables modified with ALTER TABLE and fail if missing. It is recommended to always have primary keys because various functionality may break if any large table is missing them. `tmp_table_size` integer optional Example: `16777216` The maximum size, in bytes, of internal in-memory tables. Also set max_heap_table_size. Default is 16777216 (16M). `wait_timeout` integer optional Example: `28800` The number of seconds the server waits for activity on a noninteractive connection before closing it. `windowing_use_high_precision` boolean optional Example: `true` When enabled, window functions use a higher precision for internal calculations, which can be more accurate but slower. **Postgres Advanced Config** `autovacuum_analyze_scale_factor` number optional Example: `0.2` Specifies a fraction, in a decimal value, of the table size to add to autovacuum_analyze_threshold when deciding whether to trigger an ANALYZE. The default is 0.2 (20% of table size). `autovacuum_analyze_threshold` integer optional Example: `50` Specifies the minimum number of inserted, updated, or deleted tuples needed to trigger an ANALYZE in any one table. The default is 50 tuples. `autovacuum_freeze_max_age` integer optional Example: `200000000` Specifies the maximum age (in transactions) that a table's pg_class.relfrozenxid field can attain before a VACUUM operation is forced to prevent transaction ID wraparound within the table. Note that the system will launch autovacuum processes to prevent wraparound even when autovacuum is otherwise disabled. This parameter will cause the server to be restarted. `autovacuum_max_workers` integer optional Example: `5` Specifies the maximum number of autovacuum processes (other than the autovacuum launcher) that may be running at any one time. The default is three. This parameter can only be set at server start. `autovacuum_naptime` integer optional Example: `43200` Specifies the minimum delay, in seconds, between autovacuum runs on any given database. The default is one minute. `autovacuum_vacuum_cost_delay` integer optional Example: `20` Specifies the cost delay value, in milliseconds, that will be used in automatic VACUUM operations. If -1, uses the regular vacuum_cost_delay value, which is 20 milliseconds. `autovacuum_vacuum_cost_limit` integer optional Example: `-1` Specifies the cost limit value that will be used in automatic VACUUM operations. If -1 is specified (which is the default), the regular vacuum_cost_limit value will be used. `autovacuum_vacuum_scale_factor` number optional Example: `0.2` Specifies a fraction, in a decimal value, of the table size to add to autovacuum_vacuum_threshold when deciding whether to trigger a VACUUM. The default is 0.2 (20% of table size). `autovacuum_vacuum_threshold` integer optional Example: `50` Specifies the minimum number of updated or deleted tuples needed to trigger a VACUUM in any one table. The default is 50 tuples. `backup_hour` integer optional Example: `3` The hour of day (in UTC) when backup for the service starts. New backup only starts if previous backup has already completed. `backup_minute` integer optional Example: `30` The minute of the backup hour when backup for the service starts. New backup is only started if previous backup has already completed. `bgwriter_delay` integer optional Example: `200` Specifies the delay, in milliseconds, between activity rounds for the background writer. Default is 200 ms. `bgwriter_flush_after` integer optional Example: `512` The amount of kilobytes that need to be written by the background writer before attempting to force the OS to issue these writes to underlying storage. Specified in kilobytes, default is 512. Setting of 0 disables forced writeback. `bgwriter_lru_maxpages` integer optional Example: `100` The maximum number of buffers that the background writer can write. Setting this to zero disables background writing. Default is 100. `bgwriter_lru_multiplier` number optional Example: `2` The average recent need for new buffers is multiplied by bgwriter_lru_multiplier to arrive at an estimate of the number that will be needed during the next round, (up to bgwriter_lru_maxpages). 1.0 represents a “just in time” policy of writing exactly the number of buffers predicted to be needed. Larger values provide some cushion against spikes in demand, while smaller values intentionally leave writes to be done by server processes. The default is 2.0. `deadlock_timeout` integer optional Example: `1000` The amount of time, in milliseconds, to wait on a lock before checking to see if there is a deadlock condition. `default_toast_compression` string, one of: lz4, pglz optional Example: `lz4` Specifies the default TOAST compression method for values of compressible columns (the default is lz4). `idle_in_transaction_session_timeout` integer optional Example: `10000` Time out sessions with open transactions after this number of milliseconds `jit` boolean optional Example: `true` Activates, in a boolean, the system-wide use of Just-in-Time Compilation (JIT). `log_autovacuum_min_duration` integer optional Example: `-1` Causes each action executed by autovacuum to be logged if it ran for at least the specified number of milliseconds. Setting this to zero logs all autovacuum actions. Minus-one (the default) disables logging autovacuum actions. `log_error_verbosity` string, one of: TERSE, DEFAULT, VERBOSE optional Example: `VERBOSE` Controls the amount of detail written in the server log for each message that is logged. `log_line_prefix` string, one of: pid=%p,user=%u,db=%d,app=%a,client=%h, %m \[%p] %q\[user=%u,db=%d,app=%a], %t \[%p]: \[%l-1] user=%u,db=%d,app=%a,client=%h optional Example: `pid=%p,user=%u,db=%d,app=%a,client=%h` Selects one of the available log-formats. These can support popular log analyzers like pgbadger, pganalyze, etc. `log_min_duration_statement` integer optional Example: `-1` Log statements that take more than this number of milliseconds to run. If -1, disables. `max_connections` integer optional Example: `75` Sets the PostgreSQL maximum number of concurrent connections to the database server. This is a limited-release parameter. Contact your account team to confirm your eligibility. You cannot decrease this parameter value when set. For services with a read replica, first increase the read replica's value. After the change is applied to the replica, you can increase the primary service's value. Changing this parameter causes a service restart. `max_failover_replication_time_lag` integer optional Example: `50` Number of seconds of master unavailability before triggering database failover to standby. The default value is 60. `max_files_per_process` integer optional Example: `2048` PostgreSQL maximum number of files that can be open per process. `max_locks_per_transaction` integer optional Example: `128` PostgreSQL maximum locks per transaction. Once increased, this parameter cannot be lowered from its set value. `max_logical_replication_workers` integer optional Example: `16` PostgreSQL maximum logical replication workers (taken from the pool of max_parallel_workers). `max_parallel_workers` integer optional Example: `12` Sets the maximum number of workers that the system can support for parallel queries. `max_parallel_workers_per_gather` integer optional Example: `16` Sets the maximum number of workers that can be started by a single Gather or Gather Merge node. `max_pred_locks_per_transaction` integer optional Example: `128` PostgreSQL maximum predicate locks per transaction. `max_prepared_transactions` integer optional Example: `20` PostgreSQL maximum prepared transactions. Once increased, this parameter cannot be lowered from its set value. `max_replication_slots` integer optional Example: `16` PostgreSQL maximum replication slots. `max_slot_wal_keep_size` integer optional Example: `100` PostgreSQL maximum WAL size (MB) reserved for replication slots. If -1 is specified, replication slots may retain an unlimited amount of WAL files. The default is -1 (upstream default). wal_keep_size minimum WAL size setting takes precedence over this. `max_stack_depth` integer optional Example: `2097152` Maximum depth of the stack in bytes. `max_standby_archive_delay` integer optional Example: `43200` Max standby archive delay in milliseconds. `max_standby_streaming_delay` integer optional Example: `43200` Max standby streaming delay in milliseconds. `max_wal_senders` integer optional Example: `32` PostgreSQL maximum WAL senders. Once increased, this parameter cannot be lowered from its set value. `max_worker_processes` integer optional Example: `16` Sets the maximum number of background processes that the system can support. Once increased, this parameter cannot be lowered from its set value. `pg_partman_bgw.interval` integer optional Example: `3600` Sets the time interval to run pg_partman's scheduled tasks. `pg_partman_bgw.role` string optional Example: `myrolename` Controls which role to use for pg_partman's scheduled background tasks. Must consist of alpha-numeric characters, dots, underscores, or dashes. May not start with dash or dot. Maximum of 64 characters. `pg_stat_statements.track` string, one of: all, top, none optional Example: `all` Controls which statements are counted. Specify 'top' to track top-level statements (those issued directly by clients), 'all' to also track nested statements (such as statements invoked within functions), or 'none' to disable statement statistics collection. The default value is top. `pgaudit` object optional System-wide settings for the pgaudit extension. When `feature_enabled` is true, the pgaudit extension is automatically installed. When false, the extension is uninstalled but auditing configurations (such as `log`) are preserved. **Show child properties** `feature_enabled` boolean optional Example: `false` Enable pgaudit extension. When enabled, pgaudit extension will be automatically installed. Otherwise, extension will be uninstalled but auditing configurations will be preserved. `log` array of string (enum) optional Example: `["read","write","ddl"]` Specifies which classes of statements will be logged by session audit logging. Available values are `read` (SELECT and COPY when the source is a relation or query), `write` (INSERT, UPDATE, DELETE, TRUNCATE, and COPY when the destination is a relation), `function` (function calls and DO blocks), `role` (statements related to roles and privileges: GRANT, REVOKE, CREATE/ALTER/DROP ROLE), `ddl` (all DDL that is not included in the role class), `misc` (miscellaneous commands, e.g. DISCARD, FETCH, CHECKPOINT, VACUUM, SET), `misc_set` (miscellaneous SET commands, e.g. SET ROLE), and `all` (include all of the above). `pgbouncer` object optional PGBouncer connection pooling settings **Show child properties** `autodb_idle_timeout` integer optional Example: `3600` If the automatically-created database pools have been unused this many seconds, they are freed. If 0, timeout is disabled. `autodb_max_db_connections` integer optional Example: `1` Only allows a maximum this many server connections per database (regardless of user). If 0, allows unlimited connections. `autodb_pool_mode` string, one of: session, transaction, statement optional Example: `session` PGBouncer pool mode `autodb_pool_size` integer optional Example: `1` If non-zero, automatically creates a pool of that size per user when a pool doesn't exist. `ignore_startup_parameters` array of string, one of: extra_float_digits, search_path optional Example: `["extra_float_digits","search_path"]` List of parameters to ignore when given in startup packet. `min_pool_size` integer optional Example: `1` If current server connections are below this number, adds more. Improves behavior when usual load comes suddenly back after period of total inactivity. The value is effectively capped at the pool size. `server_idle_timeout` integer optional Example: `600` Drops server connections if they have been idle more than this many seconds. If 0, timeout is disabled. `server_lifetime` integer optional Example: `3600` The pooler closes any unused server connection that has been connected longer than this amount of seconds. `server_reset_query_always` boolean optional Example: `false` Run server_reset_query (DISCARD ALL) in all pooling modes. `shared_buffers_percentage` number optional Example: `41.5` Percentage of total RAM that the database server uses for shared memory buffers. Valid range is 20-60 (float), which corresponds to 20% - 60%. This setting adjusts the shared_buffers configuration value. `stat_monitor_enable` boolean optional Example: `false` Enable the pg_stat_monitor extension. **Enabling this extension will cause the cluster to be restarted.** When this extension is enabled, pg_stat_statements results for utility commands are unreliable. `synchronous_replication` string, one of: off, quorum optional Example: `off` Synchronous replication type. Note that the service plan also needs to support synchronous replication. `temp_file_limit` integer optional Example: `5000000` PostgreSQL temporary file limit in KiB. If -1, sets to unlimited. `timescaledb` object optional TimescaleDB extension configuration values **Show child properties** `max_background_workers` integer optional Example: `8` The number of background workers for timescaledb operations. Set to the sum of your number of databases and the total number of concurrent background workers you want running at any given point in time. `timezone` string optional Example: `Europe/Helsinki` PostgreSQL service timezone `track_activity_query_size` integer optional Example: `1024` Specifies the number of bytes reserved to track the currently executing command for each active session. `track_commit_timestamp` string, one of: off, on optional Example: `off` Record commit time of transactions. `track_functions` string, one of: all, pl, none optional Example: `all` Enables tracking of function call counts and time used. `track_io_timing` string, one of: off, on optional Example: `off` Enables timing of database I/O calls. This parameter is off by default, because it will repeatedly query the operating system for the current time, which may cause significant overhead on some platforms. `wal_sender_timeout` integer optional Example: `60000` Terminate replication connections that are inactive for longer than this amount of time, in milliseconds. Setting this value to zero disables the timeout. Must be either 0 or between 5000 and 10800000. `wal_writer_delay` integer optional Example: `50` WAL flush interval in milliseconds. Note that setting this value to lower than the default 200ms may negatively impact performance `work_mem` integer optional Example: `4` The maximum amount of memory, in MB, used by a query operation (such as a sort or hash table) before writing to temporary disk files. Default is 1MB + 0.075% of total RAM (up to 32MB). **Redis Advanced Config** `redis_acl_channels_default` string, one of: allchannels, resetchannels optional Example: `allchannels` Determines default pub/sub channels' ACL for new users if ACL is not supplied. When this option is not defined, all_channels is assumed to keep backward compatibility. This option doesn't affect Caching configuration acl-pubsub-default. `redis_io_threads` integer optional Example: `1` Caching IO thread count `redis_lfu_decay_time` integer optional Example: `1` LFU maxmemory-policy counter decay time in minutes `redis_lfu_log_factor` integer optional Example: `10` Counter logarithm factor for volatile-lfu and allkeys-lfu maxmemory-policies `redis_maxmemory_policy` string (enum) optional Example: `allkeys-lru` A string specifying the desired eviction policy for the Caching cluster. - `noeviction`: Don't evict any data, returns error when memory limit is reached. - `allkeys-lru:` Evict any key, least recently used (LRU) first. - `allkeys-random`: Evict keys in a random order. - `volatile-lru`: Evict keys with expiration only, least recently used (LRU) first. - `volatile-random`: Evict keys with expiration only in a random order. - `volatile-ttl`: Evict keys with expiration only, shortest time-to-live (TTL) first. `redis_notify_keyspace_events` string optional Example: `K` Set notify-keyspace-events option. Requires at least `K` or `E` and accepts any combination of the following options. Setting the parameter to `""` disables notifications. - `K` — Keyspace events - `E` — Keyevent events - `g` — Generic commands (e.g. `DEL`, `EXPIRE`, `RENAME`, ...) - `$` — String commands - `l` — List commands - `s` — Set commands - `h` — Hash commands - `z` — Sorted set commands - `t` — Stream commands - `d` — Module key type events - `x` — Expired events - `e` — Evicted events - `m` — Key miss events - `n` — New key events - `A` — Alias for `"g$lshztxed"` `redis_number_of_databases` integer optional Example: `16` Set number of redis databases. Changing this will cause a restart of redis service. `redis_persistence` string, one of: off, rdb optional Example: `rdb` Creates an RDB dump of the database every 10 minutes that can be used to recover data after a node crash. The database does not create the dump if no keys have changed since the last dump. When set to `off`, the database cannot fork services, and data can be lost if a service is restarted or powered off. DigitalOcean Managed Caching databases do not support the Append Only File (AOF) persistence method. `redis_pubsub_client_output_buffer_limit` integer optional Example: `64` Set output buffer limit for pub / sub clients in MB. The value is the hard limit, the soft limit is 1/4 of the hard limit. When setting the limit, be mindful of the available memory in the selected service plan. `redis_ssl` boolean optional Example: `true` Require SSL to access Caching. - When enabled, Caching accepts only SSL connections on port `25061`. - When disabled, port `25060` is opened for non-SSL connections, while port `25061` remains available for SSL connections. `redis_timeout` integer optional Example: `300` Caching idle connection timeout in seconds **Valkey Advanced Config** `frequent_snapshots` boolean optional Example: `true` Frequent RDB snapshots When enabled, Valkey will create frequent local RDB snapshots. When disabled, Valkey will only take RDB snapshots when a backup is created, based on the backup schedule. This setting is ignored when valkey_persistence is set to off. `valkey_acl_channels_default` string, one of: allchannels, resetchannels optional Example: `allchannels` Determines default pub/sub channels' ACL for new users if ACL is not supplied. When this option is not defined, all_channels is assumed to keep backward compatibility. This option doesn't affect Valkey configuration acl-pubsub-default. `valkey_active_expire_effort` integer optional Example: `1` Active expire effort Valkey reclaims expired keys both when accessed and in the background. The background process scans for expired keys to free memory. Increasing the active-expire-effort setting (default 1, max 10) uses more CPU to reclaim expired keys faster, reducing memory usage but potentially increasing latency. `valkey_io_threads` integer optional Example: `1` Valkey IO thread count `valkey_lfu_decay_time` integer optional Example: `1` LFU maxmemory-policy counter decay time in minutes `valkey_lfu_log_factor` integer optional Example: `10` Counter logarithm factor for volatile-lfu and allkeys-lfu maxmemory-policies `valkey_maxmemory_policy` string (enum) optional Example: `allkeys_lru` A string specifying the desired eviction policy for a Caching or Valkey cluster. - `noeviction`: Don't evict any data, returns error when memory limit is reached. - `allkeys_lru:` Evict any key, least recently used (LRU) first. - `allkeys_random`: Evict keys in a random order. - `volatile_lru`: Evict keys with expiration only, least recently used (LRU) first. - `volatile_random`: Evict keys with expiration only in a random order. - `volatile_ttl`: Evict keys with expiration only, shortest time-to-live (TTL) first. `valkey_notify_keyspace_events` string optional Example: `K` Set notify-keyspace-events option. Requires at least `K` or `E` and accepts any combination of the following options. Setting the parameter to `""` disables notifications. - `K` — Keyspace events - `E` — Keyevent events - `g` — Generic commands (e.g. `DEL`, `EXPIRE`, `RENAME`, ...) - `$` — String commands - `l` — List commands - `s` — Set commands - `h` — Hash commands - `z` — Sorted set commands - `t` — Stream commands - `d` — Module key type events - `x` — Expired events - `e` — Evicted events - `m` — Key miss events - `n` — New key events - `A` — Alias for `"g$lshztxed"` `valkey_number_of_databases` integer optional Example: `16` Set number of valkey databases. Changing this will cause a restart of valkey service. `valkey_persistence` string, one of: off, rdb optional Example: `rdb` When persistence is 'rdb', Valkey does RDB dumps each 10 minutes if any key is changed. Also RDB dumps are done according to backup schedule for backup purposes. When persistence is 'off', no RDB dumps and backups are done, so data can be lost at any moment if service is restarted for any reason, or if service is powered off. Also service can't be forked. `valkey_pubsub_client_output_buffer_limit` integer optional Example: `64` Set output buffer limit for pub / sub clients in MB. The value is the hard limit, the soft limit is 1/4 of the hard limit. When setting the limit, be mindful of the available memory in the selected service plan. `valkey_ssl` boolean optional Example: `true` Require SSL to access Valkey `valkey_timeout` integer optional Example: `300` Valkey idle connection timeout in seconds **Mongo Advanced Config** `default_read_concern` string, one of: local, available, majority optional Example: `local` Specifies the default consistency behavior of reads from the database. Data that is returned from the query with may or may not have been acknowledged by all nodes in the replicaset depending on this value. Learn more [here](https://www.mongodb.com/docs/manual/reference/read-concern/). `default_write_concern` string optional Example: `majority` Describes the level of acknowledgment requested from MongoDB for write operations clusters. This field can set to either `majority` or a number `0...n` which will describe the number of nodes that must acknowledge the write operation before it is fully accepted. Setting to `0` will request no acknowledgement of the write operation. Learn more [here](https://www.mongodb.com/docs/manual/reference/write-concern/). `slow_op_threshold_ms` integer optional Example: `200` Operations that run for longer than this threshold are considered slow which are then recorded to the diagnostic logs. Higher log levels (verbosity) will record all operations regardless of this threshold on the primary node. *Changing this parameter will lead to a restart of the MongoDB service.* Learn more [here](https://www.mongodb.com/docs/manual/reference/configuration-options/#mongodb-setting-operationProfiling.slowOpThresholdMs). `transaction_lifetime_limit_seconds` integer optional Example: `100` Specifies the lifetime of multi-document transactions. Transactions that exceed this limit are considered expired and will be aborted by a periodic cleanup process. The cleanup process runs every `transactionLifetimeLimitSeconds/2 seconds` or at least once every 60 seconds. *Changing this parameter will lead to a restart of the MongoDB service.* Learn more [here](https://www.mongodb.com/docs/manual/reference/parameters/#mongodb-parameter-param.transactionLifetimeLimitSeconds). `verbosity` integer optional Example: `3` The log message verbosity level. The verbosity level determines the amount of Informational and Debug messages MongoDB outputs. 0 includes informational messages while 1...5 increases the level to include debug messages. *Changing this parameter will lead to a restart of the MongoDB service.* Learn more [here](https://www.mongodb.com/docs/manual/reference/configuration-options/#mongodb-setting-systemLog.verbosity). **Kafka Advanced Config** `auto_create_topics_enable` boolean optional Example: `true` Enable auto creation of topics `compression_type` string (enum) optional Example: `gzip` Specify the final compression type for a given topic. This configuration accepts the standard compression codecs ('gzip', 'snappy', 'lz4', 'zstd'). It additionally accepts 'uncompressed' which is equivalent to no compression; and 'producer' which means retain the original compression codec set by the producer. `connections_max_idle_ms` integer optional Example: `540000` Idle connections timeout: the server socket processor threads close the connections that idle for longer than this. `default_replication_factor` integer optional Example: `2` Replication factor for autocreated topics `group_initial_rebalance_delay_ms` integer optional Example: `3000` The amount of time, in milliseconds, the group coordinator will wait for more consumers to join a new group before performing the first rebalance. A longer delay means potentially fewer rebalances, but increases the time until processing begins. The default value for this is 3 seconds. During development and testing it might be desirable to set this to 0 in order to not delay test execution time. `group_max_session_timeout_ms` integer optional Example: `1800000` The maximum allowed session timeout for registered consumers. Longer timeouts give consumers more time to process messages in between heartbeats at the cost of a longer time to detect failures. `group_min_session_timeout_ms` integer optional Example: `6000` The minimum allowed session timeout for registered consumers. Longer timeouts give consumers more time to process messages in between heartbeats at the cost of a longer time to detect failures. `log_cleaner_delete_retention_ms` integer optional Example: `86400000` How long are delete records retained? `log_cleaner_max_compaction_lag_ms` integer optional Example: `60000` The maximum amount of time message will remain uncompacted. Only applicable for logs that are being compacted `log_cleaner_min_cleanable_ratio` number optional Example: `0.5` Controls log compactor frequency. Larger value means more frequent compactions but also more space wasted for logs. Consider setting log_cleaner_max_compaction_lag_ms to enforce compactions sooner, instead of setting a very high value for this option. `log_cleaner_min_compaction_lag_ms` integer optional Example: `100000` The minimum time a message will remain uncompacted in the log. Only applicable for logs that are being compacted. `log_cleanup_policy` string, one of: delete, compact, compact,delete optional Example: `delete` The default cleanup policy for segments beyond the retention window `log_flush_interval_messages` integer optional Example: `9223372036854776000` The number of messages accumulated on a log partition before messages are flushed to disk `log_flush_interval_ms` integer optional Example: `1000000` The maximum time in ms that a message in any topic is kept in memory before flushed to disk. If not set, the value in log.flush.scheduler.interval.ms is used `log_index_interval_bytes` integer optional Example: `4096` The interval with which Kafka adds an entry to the offset index `log_index_size_max_bytes` integer optional Example: `10485760` The maximum size in bytes of the offset index `log_message_downconversion_enable` boolean optional Example: `true` This configuration controls whether down-conversion of message formats is enabled to satisfy consume requests. `log_message_timestamp_difference_max_ms` integer optional Example: `1000000` The maximum difference allowed between the timestamp when a broker receives a message and the timestamp specified in the message `log_message_timestamp_type` string, one of: CreateTime, LogAppendTime optional Example: `CreateTime` Define whether the timestamp in the message is message create time or log append time. `log_preallocate` boolean optional Example: `false` Controls whether to preallocate a file when creating a new segment `log_retention_bytes` integer optional Example: `1000000` The maximum size of the log before deleting messages `log_retention_hours` integer optional Example: `1000000` The number of hours to keep a log file before deleting it `log_retention_ms` integer optional Example: `100000000` The number of milliseconds to keep a log file before deleting it (in milliseconds), If not set, the value in log.retention.minutes is used. If set to -1, no time limit is applied. `log_roll_jitter_ms` integer optional Example: `10000000` The maximum jitter to subtract from logRollTimeMillis (in milliseconds). If not set, the value in log.roll.jitter.hours is used `log_roll_ms` integer optional Example: `1000000` The maximum time before a new log segment is rolled out (in milliseconds). `log_segment_bytes` integer optional Example: `100000000` The maximum size of a single log file `log_segment_delete_delay_ms` integer optional Example: `60000` The amount of time to wait before deleting a file from the filesystem `max_connections_per_ip` integer optional Example: `512` The maximum number of connections allowed from each ip address (defaults to 2147483647). `max_incremental_fetch_session_cache_slots` integer optional Example: `1000` The maximum number of incremental fetch sessions that the broker will maintain. `message_max_bytes` integer optional Example: `1048588` The maximum size of message that the server can receive. `min_insync_replicas` integer optional Example: `1` When a producer sets acks to 'all' (or '-1'), min_insync_replicas specifies the minimum number of replicas that must acknowledge a write for the write to be considered successful. `num_partitions` integer optional Example: `10` Number of partitions for autocreated topics `offsets_retention_minutes` integer optional Example: `10080` Log retention window in minutes for offsets topic `producer_purgatory_purge_interval_requests` integer optional Example: `100` The purge interval (in number of requests) of the producer request purgatory (defaults to 1000). `replica_fetch_max_bytes` integer optional Example: `2097152` The number of bytes of messages to attempt to fetch for each partition (defaults to 1048576). This is not an absolute maximum, if the first record batch in the first non-empty partition of the fetch is larger than this value, the record batch will still be returned to ensure that progress can be made. `replica_fetch_response_max_bytes` integer optional Example: `20971520` Maximum bytes expected for the entire fetch response (defaults to 10485760). Records are fetched in batches, and if the first record batch in the first non-empty partition of the fetch is larger than this value, the record batch will still be returned to ensure that progress can be made. As such, this is not an absolute maximum. `schema_registry` boolean optional Example: `true` Enable creation of schema registry for the Kafka cluster. Schema_registry only works with General Purpose - Dedicated CPU plans. `socket_request_max_bytes` integer optional Example: `20971520` The maximum number of bytes in a socket request (defaults to 104857600). `transaction_remove_expired_transaction_cleanup_interval_ms` integer optional Example: `3600000` The interval at which to remove transactions that have expired due to transactional.id.expiration.ms passing (defaults to 3600000 (1 hour)). `transaction_state_log_segment_bytes` integer optional Example: `104857600` The transaction topic segment bytes should be kept relatively small in order to facilitate faster log compaction and cache loads (defaults to 104857600 (100 mebibytes)). **Opensearch Advanced Config** `action_auto_create_index_enabled` boolean optional Example: `true` Specifices whether to allow automatic creation of indices. `action_destructive_requires_name` boolean optional Example: `false` Specifies whether to require explicit index names when deleting indices. `cluster_max_shards_per_node` integer optional Example: `100` Maximum number of shards allowed per data node. `cluster_routing_allocation_node_concurrent_recoveries` integer optional Example: `2` Maximum concurrent incoming/outgoing shard recoveries (normally replicas) are allowed to happen per node . `enable_security_audit` boolean optional Example: `false` Specifies whether to allow security audit logging. `http_max_content_length_bytes` integer optional Example: `100000000` Maximum content length for HTTP requests to the OpenSearch HTTP API, in bytes. `http_max_header_size_bytes` integer optional Example: `8192` Maximum size of allowed headers, in bytes. `http_max_initial_line_length_bytes` integer optional Example: `4096` Maximum length of an HTTP URL, in bytes. `indices_fielddata_cache_size_percentage` integer optional Example: `3` Maximum amount of heap memory used for field data cache, expressed as a percentage. Decreasing the value too much will increase overhead of loading field data. Increasing the value too much will decrease amount of heap available for other operations. `indices_memory_index_buffer_size_percentage` integer optional Example: `10` Total amount of heap used for indexing buffer before writing segments to disk, expressed as a percentage. Too low value will slow down indexing; too high value will increase indexing performance but causes performance issues for query performance. `indices_memory_max_index_buffer_size_mb` integer optional Example: `48` Maximum amount of heap used for indexing buffer before writing segments to disk, in mb. Works in conjunction with indices_memory_index_buffer_size_percentage, each being enforced. The default is unbounded. `indices_memory_min_index_buffer_size_mb` integer optional Example: `48` Minimum amount of heap used for indexing buffer before writing segments to disk, in mb. Works in conjunction with indices_memory_index_buffer_size_percentage, each being enforced. `indices_queries_cache_size_percentage` integer optional Example: `10` Maximum amount of heap used for query cache. Too low value will decrease query performance and increase performance for other operations; too high value will cause issues with other functionality. `indices_query_bool_max_clause_count` integer optional Example: `1024` Maximum number of clauses Lucene BooleanQuery can have. Only increase it if necessary, as it may cause performance issues. `indices_recovery_max_concurrent_file_chunks` integer optional Example: `2` Maximum number of file chunks sent in parallel for each recovery. `indices_recovery_max_mb_per_sec` integer optional Example: `40` Limits total inbound and outbound recovery traffic for each node, expressed in mb per second. Applies to both peer recoveries as well as snapshot recoveries (i.e., restores from a snapshot). `ism_enabled` boolean optional Example: `true` Specifies whether ISM is enabled or not. `ism_history_enabled` boolean optional Example: `true` Specifies whether audit history is enabled or not. The logs from ISM are automatically indexed to a logs document. `ism_history_max_age_hours` integer optional Example: `24` Maximum age before rolling over the audit history index, in hours. `ism_history_max_docs` integer optional Example: `2500000` Maximum number of documents before rolling over the audit history index. `ism_history_rollover_check_period_hours` integer optional Example: `8` The time between rollover checks for the audit history index, in hours. `ism_history_rollover_retention_period_days` integer optional Example: `30` Length of time long audit history indices are kept, in days. `keep_index_refresh_interval` boolean optional Example: `true` DigitalOcean automatically resets the `index.refresh_interval` to the default value (once per second) to ensure that new documents are quickly available for search queries. If you are setting your own refresh intervals, you can disable this by setting this field to true. `knn_memory_circuit_breaker_enabled` boolean optional Example: `true` Enable or disable KNN memory circuit breaker. `knn_memory_circuit_breaker_limit` integer optional Example: `60` Maximum amount of memory in percentage that can be used for the KNN index. Defaults to 50% of the JVM heap size. 0 is used to set it to null which can be used to invalidate caches. `override_main_response_version` boolean optional Example: `false` Compatibility mode sets OpenSearch to report its version as 7.10 so clients continue to work. `plugins_alerting_filter_by_backend_roles_enabled` boolean optional Example: `false` Enable or disable filtering of alerting by backend roles. `reindex_remote_whitelist` array of string optional Example: `["255.255.223.233:9200","222.33.222.222:6300"]` Allowlist of remote IP addresses for reindexing. Changing this value will cause all OpenSearch instances to restart. `script_max_compilations_rate` string optional Example: `75/5m` Limits the number of inline script compilations within a period of time. Default is use-context `search_max_buckets` integer optional Example: `10000` Maximum number of aggregation buckets allowed in a single response. `thread_pool_analyze_queue_size` integer optional Example: `10` Size of queue for operations in the analyze thread pool. `thread_pool_analyze_size` integer optional Example: `1` Number of workers in the analyze operation thread pool. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_force_merge_size` integer optional Example: `1` Number of workers in the force merge operation thread pool. This pool is used for forcing a merge between shards of one or more indices. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_get_queue_size` integer optional Example: `10` Size of queue for operations in the get thread pool. `thread_pool_get_size` integer optional Example: `1` Number of workers in the get operation thread pool. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_search_queue_size` integer optional Example: `10` Size of queue for operations in the search thread pool. `thread_pool_search_size` integer optional Example: `1` Number of workers in the search operation thread pool. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_search_throttled_queue_size` integer optional Example: `10` Size of queue for operations in the search throttled thread pool. `thread_pool_search_throttled_size` integer optional Example: `1` Number of workers in the search throttled operation thread pool. This pool is used for searching frozen indices. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. `thread_pool_write_queue_size` integer optional Example: `10` Size of queue for operations in the write thread pool. `thread_pool_write_size` integer optional Example: `1` Number of workers in the write operation thread pool. Do note this may have maximum value depending on CPU count - value is automatically lowered if set to higher than maximum value. ##### Request: `/v2/databases/{database_cluster_uuid}/config` ### Payload Content type `application/json` ```json { "config": { "sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES", "sql_require_primary_key": true } } ``` ### cURL ```bash curl -X PATCH \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"config": {"sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES","sql_require_primary_key": true}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/config" ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.databases.patch_config(database_cluster_uuid="a7aba9d") ``` #### Responses **200** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve the Public Certificate `/v2/databases/{database_cluster_uuid}/ca` To retrieve the public certificate used to secure the connection to the database cluster send a GET request to `/v2/databases/$DATABASE_ID/ca`. The response will be a JSON object with a `ca` key. This will be set to an object containing the base64 encoding of the public key certificate. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/ca` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/ca" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() ca, _, err := client.Databases.GetCA(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_ca(database_cluster_uuid="aba77ada") ``` #### Responses **200** A JSON object with a key of ca. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `ca` object required **Show child properties** `certificate` string required read-only base64 encoding of the certificate used to secure database connections **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "ca": { "certificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVRVENDQXFtZ0F3SUJBZ0lVRUZZWTdBWFZQS0Raam9jb1lpMk00Y0dvcU0wd0RRWUpLb1pJaHZjTkFRRU0KQlFBd09qRTRNRFlHQTFVRUF3d3ZOek0zT1RaaE1XRXRaamhrTUMwME9HSmpMV0V4Wm1NdFpqbGhNVFZsWXprdwpORGhsSUZCeWIycGxZM1FnUTBFd0hoY05NakF3TnpFM01UVTFNREEyV2hjTk16QXdOekUxTVRVMU1EQTJXakE2Ck1UZ3dOZ1lEVlFRRERDODNNemM1Tm1FeFlTMW1PR1F3TFRRNFltTXRZVEZtWXkxbU9XRXhOV1ZqT1RBME9HVWcKVUhKdmFtVmpkQ0JEUVRDQ0FhSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnR1BBRENDQVlvQ2dnR0JBTVdScXhycwpMZnpNdHZyUmxKVEw4MldYMVBLZkhKbitvYjNYcmVBY3FZd1dBUUp2Q3IycmhxSXZieVZzMGlaU0NzOHI4c3RGClljQ0R1bkxJNmUwTy9laERZYTBIT2RrMkFFRzE1ckVOVmNha2NSczcyQWlHVHNrdkNXS2VkUjFTUWswVWt0WCsKQUg4S1ExS3F5bzNtZ2Y2cVV1WUpzc3JNTXFselk3YTN1RVpEb2ZqTjN5Q3MvM21pTVJKcVcyNm1JV0IrUUlEbAo5YzdLRVF5MTZvdCtjeHVnd0lLMm9oZHMzaFY1bjBKMFVBM0I3QWRBdXY5aUl5L3JHaHlTNm5CNTdaWm9JZnAyCnFybXdOY0UrVjlIdXhQSGtRVjFOQjUwOFFudWZ4Z0E5VCtqU2VrdGVUbWFORkxqNjFXL3BtcndrTytOaWFXUTIKaGgzVXBKOEozY1BoNkErbHRnUmpSV2NEb2lsYVNwRVVpU09WemNNYVFvalZKYVJlNk9NbnZYc29NaSs3ZzdneApWcittQ0lUcGcvck9DaXpBWWQ2UFAxLzdYTjk1ZXNmU2tBQnM5c3hJakpjTUFqbDBYTEFzRmtGZVdyeHNIajlVCmJnaDNWYXdtcnpUeXhZT0RQcXV1cS9JcGlwc0RRT3Fpb2ZsUStkWEJJL3NUT0NNbVp6K0pNcG5HYXdJREFRQUIKb3o4d1BUQWRCZ05WSFE0RUZnUVVSekdDRlE3WEtUdHRDN3JzNS8ydFlQcExTZGN3RHdZRFZSMFRCQWd3QmdFQgovd0lCQURBTEJnTlZIUThFQkFNQ0FRWXdEUVlKS29aSWh2Y05BUUVNQlFBRGdnR0JBSWFKQ0dSVVNxUExtcmcvCmk3MW10b0NHUDdzeG1BVXVCek1oOEdrU25uaVdaZnZGMTRwSUtqTlkwbzVkWmpHKzZqK1VjalZtK0RIdGE1RjYKOWJPeEk5S0NFeEI1blBjRXpMWjNZYitNOTcrellxbm9zUm85S21DVFJBb2JrNTZ0WU1FS1h1aVJja2tkMm1yUQo4cGw2N2xxdThjM1V4c0dHZEZVT01wMkk3ZTNpdUdWVm5UR0ZWM3JQZUdaQ0J3WGVyUUQyY0F4UjkzS3BnWVZ2ClhUUzk5dnpSbm1HOHhhUm9EVy9FbEdXZ2xWd0Q5a1JrbXhUUkdoYTdDWVZCcjFQVWY2dVVFVjhmVFIxc1hFZnIKLytMR1JoSVVsSUhWT3l2Yzk3YnZYQURPbWF1MWZDVE5lWGtRdTNyZnZFSlBmaFlLeVIwT0V3eWVvdlhRNzl0LwpTV2ZGTjBreU1Pc1UrNVNIdHJKSEh1eWNWcU0yQlVVK083VjM1UnNwOU9MZGRZMFFVbTZldFpEVEhhSUhYYzRRCnl1Rm1OL1NhSFZtNE0wL3BTVlJQdVd6TmpxMnZyRllvSDRtbGhIZk95TUNJMjc2elE2aWhGNkdDSHlkOUJqajcKUm1UWGEyNHM3NWhmSi9YTDV2bnJSdEtpVHJlVHF6V21EOVhnUmNMQ0gyS1hJaVRtSWc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve the Status of an Online Migration `/v2/databases/{database_cluster_uuid}/online-migration` To retrieve the status of the most recent online migration, send a GET request to `/v2/databases/$DATABASE_ID/online-migration`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/online-migration` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/online-migration" ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_migration_status(database_cluster_uuid="a7a7ab90") ``` #### Responses **200** A JSON object. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `created_at` string optional Example: `2020-10-29T15:57:38Z` The time the migration was initiated, in ISO 8601 format. `id` string optional Example: `77b28fc8-19ff-11eb-8c9c-c68e24557488` The ID of the most recent migration. `status` string, one of: running, syncing, canceled, error, done optional Example: `running` The current status of the migration. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "created_at": "2020-10-29T15:57:38Z", "id": "77b28fc8-19ff-11eb-8c9c-c68e24557488", "status": "running" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Start an Online Migration `/v2/databases/{database_cluster_uuid}/online-migration` To start an online migration, send a PUT request to `/v2/databases/$DATABASE_ID/online-migration` endpoint. Migrating a cluster establishes a connection with an existing cluster and replicates its contents to the target cluster. Online migration is only available for MySQL, PostgreSQL, Caching, and Valkey clusters. If the existing database is continuously being written to, the migration process will continue for up to two weeks unless it is manually stopped. Online migration is only available for [MySQL](https://docs.digitalocean.com/products/databases/mysql/how-to/migrate/index.html.md#:~:text=To%20migrate%20a%20MySQL%20database,then%20select%20Set%20Up%20Migration), [PostgreSQL](https://docs.digitalocean.com/products/databases/postgresql/how-to/migrate/index.html.md), [Caching](https://docs.digitalocean.com/products/databases/redis/how-to/migrate/index.html.md), and [Valkey](https://docs.digitalocean.com/products/databases/valkey/how-to/migrate/index.html.md) clusters. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `disable_ssl` boolean optional Example: `false` Enables SSL encryption when connecting to the source database. `ignore_dbs` array of string optional Example: `["db0","db1"]` List of databases that should be ignored during migration. `source` object required **Show child properties** `dbname` string optional Example: `defaultdb` The name of the default database. `host` string optional Example: `db.example.com` The FQDN pointing to the database cluster's current primary node. `password` string optional Example: `example_password` The randomly generated password for the default user. `port` integer optional Example: `25060` The port on which the database cluster is listening. `username` string optional Example: `doadmin` The default user for the database. ##### Request: `/v2/databases/{database_cluster_uuid}/online-migration` ### Payload Content type `application/json` ```json { "disable_ssl": false, "ignore_dbs": [ "db0", "db1" ], "source": { "dbname": "defaultdb", "host": "source-db.example.com", "password": "example_password", "port": 25060, "username": "doadmin" } } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"source":{"host":"source-db.example.com","dbname":"defaultdb","port":25060,"username":"doadmin","password":"example_password"},"disable_ssl":false,"ignore_dbs":["db0","db1"]}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/online-migration" ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "source": { "host": "source-db.example.com", "dbname": "defaultdb", "port": 25060, "username": "doadmin", "password": "example_password" }, "disable_ssl": False "ignore_dbs": ["db0","db1"] } update_resp = client.databases.update_online_migration(database_cluster_uuid="a7a8bas", body=req) ``` #### Responses **200** A JSON object. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `created_at` string optional Example: `2020-10-29T15:57:38Z` The time the migration was initiated, in ISO 8601 format. `id` string optional Example: `77b28fc8-19ff-11eb-8c9c-c68e24557488` The ID of the most recent migration. `status` string, one of: running, syncing, canceled, error, done optional Example: `running` The current status of the migration. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "created_at": "2020-10-29T15:57:38Z", "id": "77b28fc8-19ff-11eb-8c9c-c68e24557488", "status": "running" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Stop an Online Migration `/v2/databases/{database_cluster_uuid}/online-migration/{migration_id}` To stop an online migration, send a DELETE request to `/v2/databases/$DATABASE_ID/online-migration/$MIGRATION_ID`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `migration_id` string required Example: `77b28fc8-19ff-11eb-8c9c-c68e24557488` A unique identifier assigned to the online migration. ##### Request: `/v2/databases/{database_cluster_uuid}/online-migration/{migration_id}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/online-migration/77b28fc8-19ff-11eb-8c9c-c68e24557488" ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) delete_resp = client.databases.delete_online_migration(database_cluster_uuid="9cc10173", migration="77b28fc8") ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Migrate a Database Cluster to a New Region `/v2/databases/{database_cluster_uuid}/migrate` To migrate a database cluster to a new region, send a `PUT` request to `/v2/databases/$DATABASE_ID/migrate`. The body of the request must specify a `region` attribute. A successful request will receive a 202 Accepted status code with no body in response. Querying the database cluster will show that its `status` attribute will now be set to `migrating`. This will transition back to `online` when the migration has completed. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `region` string required Example: `lon1` A slug identifier for the region to which the database cluster will be migrated. ##### Request: `/v2/databases/{database_cluster_uuid}/migrate` ### Payload Content type `application/json` ```json { "region": "lon1" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"region":"lon1"}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/migrate" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() migrateRequest := &godo.DatabaseMigrateRequest{ Region: "lon1", } _, err := client.Databases.Migrate(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", migrateRequest) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "region": "lon1" } update_resp = client.databases.update_region(database_cluster_uuid="a7a8bas", body=req) ``` #### Responses **202** This does not indicate the success or failure of any operation, just that the request has been accepted for processing. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Resize a Database Cluster `/v2/databases/{database_cluster_uuid}/resize` To resize a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/resize`. The body of the request must specify both the size and num_nodes attributes. A successful request will receive a 202 Accepted status code with no body in response. Querying the database cluster will show that its status attribute will now be set to resizing. This will transition back to online when the resize operation has completed. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `num_nodes` integer (int32) required Example: `3` The number of nodes in the database cluster. Valid values are are 1-3. In addition to the primary node, up to two standby nodes may be added for highly available configurations. `size` string required Example: `db-s-4vcpu-8gb` A slug identifier representing desired the size of the nodes in the database cluster. `storage_size_mib` integer optional Example: `61440` Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage. ##### Request: `/v2/databases/{database_cluster_uuid}/resize` ### Payload Content type `application/json` ```json { "num_nodes": 3, "size": "db-s-4vcpu-8gb", "storage_size_mib": 163840 } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"size":"db-s-4vcpu-8gb", "num_nodes":3, "storage_size_mib":163840}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/resize" ``` ### Go ```go import ( "context" "github.com/digitalocean/godo" ) func main() { pat := "mytoken" client := godo.NewFromToken(pat) ctx := context.TODO() resizeRequest := &godo.DatabaseResizeRequest{ SizeSlug: "db-s-4vcpu-8gb", NumNodes: 3, StorageSizeMib: 163840, } } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "size": "db-s-4vcpu-8gb", "num_nodes": 3, "storage_size_mib": 163840 } update_resp = client.databases.update_cluster_size(database_cluster_uuid="a7a8bas", body=req) ``` #### Responses **202** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Firewall Rules (Trusted Sources) for a Database Cluster `/v2/databases/{database_cluster_uuid}/firewall` To list all of a database cluster's firewall rules (known as "trusted sources" in the control panel), send a GET request to `/v2/databases/$DATABASE_ID/firewall`. The result will be a JSON object with a `rules` key. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/firewall` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/firewall" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() rules, _, err := client.Databases.GetFirewallRules(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.list_firewall_rules(database_cluster_uuid="a7aab9a") ``` #### Responses **200** A JSON object with a key of rules. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `rules` array of object optional **Show child properties** `cluster_uuid` string optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID for the database cluster to which the rule is applied. `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the firewall rule was created. `description` string optional Example: `an IP address for local development` A human-readable description of the rule. `type` string, one of: droplet, k8s, ip_addr, tag, app required Example: `droplet` The type of resource that the firewall rule allows to access the database cluster. `uuid` string optional Example: `79f26d28-ea8a-41f2-8ad8-8cfcdd020095` A unique ID for the firewall rule itself. `value` string required Example: `ff2a6c52-5a44-4b63-b99c-0e98e7a63d61` The ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "rules": [ { "cluster_uuid": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "created_at": "2019-11-14T20:30:28Z", "type": "k8s", "uuid": "79f26d28-ea8a-41f2-8ad8-8cfcdd020095", "value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61" }, { "cluster_uuid": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "created_at": "2019-11-14T20:30:28Z", "description": "a development IP address", "type": "ip_addr", "uuid": "adfe81a8-0fa1-4e2d-973f-06aa5af19b44", "value": "192.168.1.1" }, { "cluster_uuid": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "created_at": "2019-11-14T20:30:28Z", "type": "droplet", "uuid": "b9b42276-8295-4313-b40f-74173a7f46e6", "value": "163973392" }, { "cluster_uuid": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "created_at": "2019-11-14T20:30:28Z", "type": "tag", "uuid": "718d23e0-13d7-4129-8a00-47fb72ee0deb", "value": "backend" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Firewall Rules (Trusted Sources) for a Database `/v2/databases/{database_cluster_uuid}/firewall` To update a database cluster's firewall rules (known as "trusted sources" in the control panel), send a PUT request to `/v2/databases/$DATABASE_ID/firewall` specifying which resources should be able to open connections to the database. You may limit connections to specific Droplets, Kubernetes clusters, or IP addresses. When a tag is provided, any Droplet or Kubernetes node with that tag applied to it will have access. The firewall is limited to 100 rules (or trusted sources). You cannot add IPv6 addresses as trusted sources. For additional limits, see your database engine's limits page. When possible, we recommend [placing your databases into a VPC network](https://docs.digitalocean.com/products/networking/vpc/index.html.md) to limit access to them instead of using a firewall. A successful request returns a 204 status code with no content. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `rules` array of object optional **Show child properties** `cluster_uuid` string optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID for the database cluster to which the rule is applied. `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the firewall rule was created. `description` string optional Example: `an IP address for local development` A human-readable description of the rule. `type` string, one of: droplet, k8s, ip_addr, tag, app required Example: `droplet` The type of resource that the firewall rule allows to access the database cluster. `uuid` string optional Example: `79f26d28-ea8a-41f2-8ad8-8cfcdd020095` A unique ID for the firewall rule itself. `value` string required Example: `ff2a6c52-5a44-4b63-b99c-0e98e7a63d61` The ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/firewall` ### Payload Content type `application/json` ```json { "rules": [ { "type": "ip_addr", "value": "192.168.1.1" }, { "type": "k8s", "value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61" }, { "type": "droplet", "value": "163973392" }, { "description": "a backend tag", "type": "tag", "value": "backend" } ] } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"rules": [{"type": "ip_addr","value": "192.168.1.1"},{"type": "droplet","value": "163973392"},{"type": "k8s","value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61"},{"type": "tag","value": "backend"}]}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/firewall" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() req := godo.DatabaseUpdateFirewallRulesRequest{ Rules: []*godo.DatabaseFirewallRule{ { Type: "ip_addr", Value: "192.168.1.1", Description: "a development IP address", }, { Type: "droplet", Value: "163973392", }, { Type: "k8s", Value: "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61", }, }, } _, err := client.Databases.UpdateFirewallRules(ctx, dbID, &req) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "rules": [ { "type": "ip_addr", "value": "192.168.1.1", "description": "a development IP address", }, { "type": "k8s", "value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61" }, { "type": "droplet", "value": "163973392" }, { "type": "tag", "value": "backend" } ] } update_resp = client.databases.update_firewall_rules(database_cluster_uuid="a7a8bas", body=req) ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve DO Settings for a Database Cluster `/v2/databases/{database_cluster_uuid}/do_settings` To retrieve the DigitalOcean-specific settings for a database cluster, send a GET request to `/v2/databases/$DATABASE_ID/do_settings`. The response will include the current `service_cnames` configuration. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/do_settings` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/do_settings" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() doSettings, _, err := client.Databases.GetDOSettings(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.databases.get_do_settings(database_cluster_uuid="9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") ``` #### Responses **200** A JSON object with a key of do_settings. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `do_settings` object required DigitalOcean-specific settings for the database cluster. **Show child properties** `service_cnames` array of string optional Example: `["db.example.com","database.myapp.io"]` An array of custom CNAMEs for the database cluster. Each CNAME must be a valid RFC 1123 hostname (e.g., "db.example.com"). Maximum of 16 CNAMEs allowed, each up to 253 characters. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "do_settings": { "service_cnames": [ "db.example.com", "api.myapp.io" ] } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update DO Settings for a Database Cluster `/v2/databases/{database_cluster_uuid}/do_settings` To update the DigitalOcean-specific settings for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/do_settings`. Currently, the only supported setting is `service_cnames`, which allows you to specify custom DNS names (CNAMEs) to be included in the TLS certificate Subject Alternative Names (SANs) for the database cluster nodes. This enables TLS verification when connecting via a custom hostname. After updating, the database nodes will be replaced to apply the new certificate. This process is performed as a rolling replacement and does not cause downtime. To clear all custom CNAMEs, send an empty array or omit the field. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `do_settings` object required DigitalOcean-specific settings for the database cluster. **Show child properties** `service_cnames` array of string optional Example: `["db.example.com","database.myapp.io"]` An array of custom CNAMEs for the database cluster. Each CNAME must be a valid RFC 1123 hostname (e.g., "db.example.com"). Maximum of 16 CNAMEs allowed, each up to 253 characters. ##### Request: `/v2/databases/{database_cluster_uuid}/do_settings` ### Payload Content type `application/json` ```json { "do_settings": { "service_cnames": [ "db.example.com", "db-replica.example.com" ] } } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"do_settings": {"service_cnames": ["db.example.com", "db-replica.example.com"]}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/do_settings" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() dbID := "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30" req := godo.DatabaseUpdateDOSettingsRequest{ DOSettings: &godo.DOSettings{ ServiceCnames: []string{ "db.example.com", "db-replica.example.com", }, }, } _, err := client.Databases.UpdateDOSettings(ctx, dbID, &req) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "do_settings": { "service_cnames": ["db.example.com", "db-replica.example.com"] } } resp = client.databases.update_do_settings( database_cluster_uuid="9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", body=req ) ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **400** There was an error parsing the request body. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **422** Unprocessable Entity Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **400** ```json { "id": "bad_request", "message": "error parsing request body", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **422** ```json { "id": "unprocessable_entity", "message": "request payload validation failed", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Configure a Database Cluster's Maintenance Window `/v2/databases/{database_cluster_uuid}/maintenance` To configure the window when automatic maintenance should be performed for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/maintenance`. A successful request will receive a 204 No Content status code with no body in response. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `day` string required Example: `tuesday` The day of the week on which to apply maintenance updates. `description` array of string optional read-only Example: `["Update TimescaleDB to version 1.2.1","Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases"]` A list of strings, each containing information about a pending maintenance update. `hour` string required Example: `14:00` The hour in UTC at which maintenance updates will be applied in 24 hour format. `pending` boolean optional read-only Example: `true` A boolean value indicating whether any maintenance is scheduled to be performed in the next window. ##### Request: `/v2/databases/{database_cluster_uuid}/maintenance` ### Payload Content type `application/json` ```json { "day": "tuesday", "hour": "14:00" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"day": "tuesday", "hour": "14:00"}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/maintenance" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() maintenanceRequest := &godo.DatabaseUpdateMaintenanceRequest{ Day: "thursday", Hour: "16:00", } _, err := client.Databases.UpdateMaintenance(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", maintenanceRequest) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "day": "tuesday", "hour": "14:00" } update_resp = client.databases.update_maintenance_window(database_cluster_uuid="a7a8bas", body=req) ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Start Database Maintenance `/v2/databases/{database_cluster_uuid}/install_update` To start the installation of updates for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/install_update`. A successful request will receive a 204 No Content status code with no body in response. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/install_update` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/install_update" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() _, err := client.Databases.InstallUpdate(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) update_resp = client.databases.install_update(database_cluster_uuid="a7a8bas") ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Backups for a Database Cluster `/v2/databases/{database_cluster_uuid}/backups` To list all of the available backups of a PostgreSQL or MySQL database cluster, send a GET request to `/v2/databases/$DATABASE_ID/backups`. **Note**: Backups are not supported for Caching or Valkey clusters. The result will be a JSON object with a `backups key`. This will be set to an array of backup objects, each of which will contain the size of the backup and the timestamp at which it was created. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/backups` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/backups" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() backups, _, err := client.Databases.ListBackups(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.list_backups(database_cluster_uuid="a9a8a77") ``` #### Responses **200** A JSON object with a key of backups. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `backup_progress` string optional Example: `36` If a backup is currently in progress, this attribute shows the percentage of completion. If no backup is in progress, this attribute will be hidden. `backups` array of object required **Show child properties** `created_at` string (date-time) required Example: `2019-01-31T19:25:22Z` A time value given in ISO8601 combined date and time format at which the backup was created. `incremental` boolean optional Example: `false` Indicates if this backup is a full or an incremental one (available only for MySQL). `size_gigabytes` number required Example: `0.03364864` The size of the database backup in GBs. `scheduled_backup_time` object optional **Show child properties** `backup_hour` integer optional Example: `20` The hour of the day when the backup is scheduled (in UTC). `backup_interval_hours` integer optional Example: `24` The frequency, in hours, at which backups are taken. `backup_minute` integer optional Example: `40` The minute of the hour when the backup is scheduled. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "backup_progress": "36", "backups": [ { "created_at": "2019-01-11T18:42:27Z", "incremental": false, "size_gigabytes": 0.03357696 }, { "created_at": "2019-01-12T18:42:29Z", "incremental": true, "size_gigabytes": 0.03364864 } ], "scheduled_backup_time": { "backup_hour": 20, "backup_interval_hours": 24, "backup_minute": 40 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List All Read-only Replicas `/v2/databases/{database_cluster_uuid}/replicas` To list all of the read-only replicas associated with a database cluster, send a GET request to `/v2/databases/$DATABASE_ID/replicas`. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. The result will be a JSON object with a `replicas` key. This will be set to an array of database replica objects, each of which will contain the standard database replica attributes. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/replicas` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() replicas, _, err := client.Databases.ListReplicas(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.list_replicas(database_cluster_uuid="a7aba3") ``` #### Responses **200** A JSON object with a key of replicas. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `replicas` array of object optional **Show child properties** `connection` object optional `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the database cluster was created. `do_settings` object optional `id` string (uuid) optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID that can be used to identify and reference a database replica. `name` string required Example: `read-nyc3-01` The name to give the read-only replicating `private_connection` object optional `private_network_uuid` string optional Example: `9423cbad-9211-442f-820b-ef6915e99b5f` A string specifying the UUID of the VPC to which the read-only replica will be assigned. If excluded, the replica will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. `region` string optional Example: `nyc3` A slug identifier for the region where the read-only replica will be located. If excluded, the replica will be placed in the same region as the cluster. `size` string optional Example: `db-s-2vcpu-4gb` A slug identifier representing the size of the node for the read-only replica. The size of the replica must be at least as large as the node size for the database cluster from which it is replicating. `status` string, one of: creating, online, resizing, migrating, forking optional read-only Example: `creating` A string representing the current status of the database cluster. `storage_size_mib` integer optional Example: `61440` Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage. `tags` array of string optional Example: `["production"]` A flat array of tag names as strings applied to the read-only replica. Requires `tag:read` scope. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "replicas": [ { "connection": { "database": "defaultdb", "host": "read-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "", "user": "doadmin" }, "created_at": "2019-01-11T18:37:36Z", "name": "read-nyc3-01", "private_connection": { "database": "", "host": "private-read-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@private-read-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "region": "nyc3", "status": "online" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create a Read-only Replica `/v2/databases/{database_cluster_uuid}/replicas` To create a read-only replica for a PostgreSQL or MySQL database cluster, send a POST request to `/v2/databases/$DATABASE_ID/replicas` specifying the name it should be given, the size of the node to be used, and the region where it will be located. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. The response will be a JSON object with a key called `replica`. The value of this will be an object that contains the standard attributes associated with a database replica. The initial value of the read-only replica's `status` attribute will be `forking`. When the replica is ready to receive traffic, this will transition to `active`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `connection` object optional `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the database cluster was created. `do_settings` object optional `id` string (uuid) optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID that can be used to identify and reference a database replica. `name` string required Example: `read-nyc3-01` The name to give the read-only replicating `private_connection` object optional `private_network_uuid` string optional Example: `9423cbad-9211-442f-820b-ef6915e99b5f` A string specifying the UUID of the VPC to which the read-only replica will be assigned. If excluded, the replica will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. `region` string optional Example: `nyc3` A slug identifier for the region where the read-only replica will be located. If excluded, the replica will be placed in the same region as the cluster. `size` string optional Example: `db-s-2vcpu-4gb` A slug identifier representing the size of the node for the read-only replica. The size of the replica must be at least as large as the node size for the database cluster from which it is replicating. `status` string, one of: creating, online, resizing, migrating, forking optional read-only Example: `creating` A string representing the current status of the database cluster. `storage_size_mib` integer optional Example: `61440` Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage. `tags` array of string optional Example: `["production"]` A flat array of tag names as strings to apply to the read-only replica after it is created. Tag names can either be existing or new tags. Requires `tag:create` scope. ##### Request: `/v2/databases/{database_cluster_uuid}/replicas` ### Payload Content type `application/json` Example ```json { "name": "read-nyc3-01", "region": "nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440 } ``` ```json { "do_settings": { "service_cnames": [ "replica-db.example.com", "read-replica.myapp.io" ] }, "name": "read-nyc3-01", "region": "nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440 } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"name":"read-nyc3-01", "region":"nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440, "do_settings": {"service_cnames": ["replica-db.example.com", "read-replica.myapp.io"]}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() replicaRequest := &godo.DatabaseCreateReplicaRequest{ Name: "read-nyc3-01", Region: "nyc3", Size: "db-s-2vcpu-4gb", StorageSizeMiB: 61440, DOSettings: &godo.DOSettings{ ServiceCnames: []string{"replica-db.example.com", "read-replica.myapp.io"}, }, } replica, _, err := client.Databases.CreateReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", replicaRequest) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) create_req = { "name": "read-nyc3-01", "region": "nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440, "do_settings": { "service_cnames": [ "replica-db.example.com", "read-replica.myapp.io" ] } } create_resp = client.databases.create_replica(database_cluster_uuid="9cc10173", body=create_req) ``` #### Responses **201** A JSON object with a key of replica. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `replica` object optional **Show child properties** `connection` object optional `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the database cluster was created. `do_settings` object optional `id` string (uuid) optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID that can be used to identify and reference a database replica. `name` string required Example: `read-nyc3-01` The name to give the read-only replicating `private_connection` object optional `private_network_uuid` string optional Example: `9423cbad-9211-442f-820b-ef6915e99b5f` A string specifying the UUID of the VPC to which the read-only replica will be assigned. If excluded, the replica will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. `region` string optional Example: `nyc3` A slug identifier for the region where the read-only replica will be located. If excluded, the replica will be placed in the same region as the cluster. `size` string optional Example: `db-s-2vcpu-4gb` A slug identifier representing the size of the node for the read-only replica. The size of the replica must be at least as large as the node size for the database cluster from which it is replicating. `status` string, one of: creating, online, resizing, migrating, forking optional read-only Example: `creating` A string representing the current status of the database cluster. `storage_size_mib` integer optional Example: `61440` Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage. `tags` array of string optional Example: `["production"]` A flat array of tag names as strings applied to the read-only replica. Requires `tag:read` scope. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **201** ```json { "replica": { "connection": { "database": "defaultdb", "host": "read-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "", "user": "doadmin" }, "created_at": "2019-01-11T18:37:36Z", "do_settings": { "service_cnames": [ "replica-db.example.com", "read-replica.myapp.io" ] }, "name": "read-nyc3-01", "private_connection": { "database": "", "host": "private-read-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@private-read-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "region": "nyc3", "status": "online" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List all Events Logs `/v2/databases/{database_cluster_uuid}/events` To list all of the cluster events, send a GET request to `/v2/databases/$DATABASE_ID/events`. The result will be a JSON object with a `events` key. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/events` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/events" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() replicas, _, err := client.Databases.ListProjectEvents(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) } ``` #### Responses **200** A JSON object with a key of events. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `events` array of object optional **Show child properties** `cluster_name` string optional Example: `sample_cluster` The name of cluster. `create_time` string optional Example: `2020-10-29T15:57:38Z` The time of the generation of a event. `event_type` string (enum) optional Example: `cluster_create` Type of the event. `id` string optional Example: `pe8u2huh` ID of the particular event. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "events": [ { "cluster_name": "customer-events", "create_time": "2020-10-29T15:57:38Z", "event_type": "cluster_create", "id": "pe8u2huh" }, { "cluster_name": "customer-events", "create_time": "2023-10-30T15:57:38Z", "event_type": "cluster_update", "id": "pe8ufefuh" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Existing Read-only Replica `/v2/databases/{database_cluster_uuid}/replicas/{replica_name}` To show information about an existing database replica, send a GET request to `/v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME`. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. The response will be a JSON object with a `replica key`. This will be set to an object containing the standard database replica attributes. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `replica_name` string required Example: `read-nyc3-01` The name of the database replica. ##### Request: `/v2/databases/{database_cluster_uuid}/replicas/{replica_name}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas/read-nyc3-01" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() replica, _, err := client.Databases.GetReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "read-nyc3-01") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_replica(database_cluster_uuid="a7a90a", replica_name="backend-replica") ``` #### Responses **200** A JSON object with a key of replica. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `replica` object optional **Show child properties** `connection` object optional `created_at` string (date-time) optional read-only Example: `2019-01-11T18:37:36Z` A time value given in ISO8601 combined date and time format that represents when the database cluster was created. `do_settings` object optional `id` string (uuid) optional read-only Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique ID that can be used to identify and reference a database replica. `name` string required Example: `read-nyc3-01` The name to give the read-only replicating `private_connection` object optional `private_network_uuid` string optional Example: `9423cbad-9211-442f-820b-ef6915e99b5f` A string specifying the UUID of the VPC to which the read-only replica will be assigned. If excluded, the replica will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. `region` string optional Example: `nyc3` A slug identifier for the region where the read-only replica will be located. If excluded, the replica will be placed in the same region as the cluster. `size` string optional Example: `db-s-2vcpu-4gb` A slug identifier representing the size of the node for the read-only replica. The size of the replica must be at least as large as the node size for the database cluster from which it is replicating. `status` string, one of: creating, online, resizing, migrating, forking optional read-only Example: `creating` A string representing the current status of the database cluster. `storage_size_mib` integer optional Example: `61440` Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage. `tags` array of string optional Example: `["production"]` A flat array of tag names as strings applied to the read-only replica. Requires `tag:read` scope. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "replica": { "connection": { "database": "defaultdb", "host": "read-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "", "user": "doadmin" }, "created_at": "2019-01-11T18:37:36Z", "do_settings": { "service_cnames": [ "replica-db.example.com", "read-replica.myapp.io" ] }, "name": "read-nyc3-01", "private_connection": { "database": "", "host": "private-read-db.example.com", "password": "example_password", "port": 25060, "ssl": true, "uri": "postgres://doadmin:example_password@private-read-db.example.com:25060/defaultdb?sslmode=require", "user": "doadmin" }, "region": "nyc3", "status": "online" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Destroy a Read-only Replica `/v2/databases/{database_cluster_uuid}/replicas/{replica_name}` To destroy a specific read-only replica, send a DELETE request to `/v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME`. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `replica_name` string required Example: `read-nyc3-01` The name of the database replica. ##### Request: `/v2/databases/{database_cluster_uuid}/replicas/{replica_name}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas/read-nyc3-01" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() _, err := client.Databases.DeleteReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "read-nyc3-01") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) delete_resp = client.databases.destroy_replica(database_cluster_uuid="ba88aab", replica_name="read_nyc_3") ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Promote a Read-only Replica to become a Primary Cluster `/v2/databases/{database_cluster_uuid}/replicas/{replica_name}/promote` To promote a specific read-only replica, send a PUT request to `/v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME/promote`. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `replica_name` string required Example: `read-nyc3-01` The name of the database replica. ##### Request: `/v2/databases/{database_cluster_uuid}/replicas/{replica_name}/promote` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas/read-nyc3-01/promote" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() _, err := client.Databases.PromoteReplicaToPrimary(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "read-nyc3-01") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.databases.promote_replica(database_cluster_uuid="a7a8bas", replica_name="ba8ab22") ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List all Database Users `/v2/databases/{database_cluster_uuid}/users` To list all of the users for your database cluster, send a GET request to `/v2/databases/$DATABASE_ID/users`. Note: User management is not supported for Caching or Valkey clusters. The result will be a JSON object with a `users` key. This will be set to an array of database user objects, each of which will contain the standard database user attributes. User passwords will not show without the `database:view_credentials` scope. For MySQL clusters, additional options will be contained in the mysql_settings object. For PostgreSQL clusters, additional options will be contained in the `settings` object (for example, `pg_allow_replication`). For Kafka clusters, additional options will be contained in the `settings` object. For MongoDB clusters, additional information will be contained in the mongo_user_settings object #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/users` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() users, _, err := client.Databases.ListUsers(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", nil) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.list_users(database_cluster_uuid="a7aba3") ``` #### Responses **200** A JSON object with a key of users. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `users` array of object optional **Show child properties** `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. **Show child properties** `id` string optional Example: `aaa` An identifier for the ACL. Will be computed after the ACL is created/updated. `permission` string, one of: admin, consume, produce, produceconsume required Example: `consume` Permission set applied to the ACL. 'consume' allows for messages to be consumed from the topic. 'produce' allows for messages to be published to the topic. 'produceconsume' allows for both 'consume' and 'produce' permission. 'admin' allows for 'produceconsume' as well as any operations to administer the topic (delete, update). `topic` string required Example: `topic-abc.*` A regex for matching the topic(s) that this ACL should apply to. `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. **Show child properties** `databases` array of string optional Example: `["my-db","my-db-2"]` A list of databases to which the user should have access. When the database is set to `admin`, the user will have access to all databases based on the user's role i.e. a user with the role `readOnly` assigned to the `admin` database will have read access to all databases. `role` string, one of: readOnly, readWrite, dbAdmin optional Example: `readOnly` The role to assign to the user with each role mapping to a MongoDB built-in role. `readOnly` maps to a [read](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) role. `readWrite` maps to a [readWrite](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) role. `dbAdmin` maps to a [dbAdmin](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) role. `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. **Show child properties** `index` string optional Example: `index-abc.*` A regex for matching the indexes that this ACL should apply to. `permission` string, one of: deny, admin, read, readwrite, write optional Example: `read` Permission set applied to the ACL. 'read' allows user to read from the index. 'write' allows for user to write to the index. 'readwrite' allows for both 'read' and 'write' permission. 'deny'(default) restricts user from performing any operation over an index. 'admin' allows for 'readwrite' as well as any operations to administer the index. `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "users": [ { "name": "app-01", "password": "example_password", "role": "normal" }, { "name": "app-02", "password": "example_password_2", "role": "normal", "settings": { "pg_allow_replication": true } }, { "name": "doadmin", "password": "example_password", "role": "primary" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Add a Database User `/v2/databases/{database_cluster_uuid}/users` To add a new database user, send a POST request to `/v2/databases/$DATABASE_ID/users` with the desired username. Note: User management is not supported for Caching or Valkey clusters. When adding a user to a MySQL cluster, additional options can be configured in the `mysql_settings` object. When adding a user to a PostgreSQL cluster, additional options can be configured in the `settings` object (for example, `pg_allow_replication`). When `pg_allow_replication` is omitted, it defaults to `false`. When adding a user to a Kafka cluster, additional options can be configured in the `settings` object. When adding a user to a MongoDB cluster, additional options can be configured in the `settings.mongo_user_settings` object. The response will be a JSON object with a key called `user`. The value of this will be an object that contains the standard attributes associated with a database user including its randomly generated password. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. **Show child properties** `id` string optional Example: `aaa` An identifier for the ACL. Will be computed after the ACL is created/updated. `permission` string, one of: admin, consume, produce, produceconsume required Example: `consume` Permission set applied to the ACL. 'consume' allows for messages to be consumed from the topic. 'produce' allows for messages to be published to the topic. 'produceconsume' allows for both 'consume' and 'produce' permission. 'admin' allows for 'produceconsume' as well as any operations to administer the topic (delete, update). `topic` string required Example: `topic-abc.*` A regex for matching the topic(s) that this ACL should apply to. `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. **Show child properties** `databases` array of string optional Example: `["my-db","my-db-2"]` A list of databases to which the user should have access. When the database is set to `admin`, the user will have access to all databases based on the user's role i.e. a user with the role `readOnly` assigned to the `admin` database will have read access to all databases. `role` string, one of: readOnly, readWrite, dbAdmin optional Example: `readOnly` The role to assign to the user with each role mapping to a MongoDB built-in role. `readOnly` maps to a [read](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) role. `readWrite` maps to a [readWrite](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) role. `dbAdmin` maps to a [dbAdmin](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) role. `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. **Show child properties** `index` string optional Example: `index-abc.*` A regex for matching the indexes that this ACL should apply to. `permission` string, one of: deny, admin, read, readwrite, write optional Example: `read` Permission set applied to the ACL. 'read' allows user to read from the index. 'write' allows for user to write to the index. 'readwrite' allows for both 'read' and 'write' permission. 'deny'(default) restricts user from performing any operation over an index. 'admin' allows for 'readwrite' as well as any operations to administer the index. `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. `readonly` boolean optional Example: `true` (To be deprecated: use settings.mongo_user_settings.role instead for access controls to MongoDB databases). For MongoDB clusters, set to `true` to create a read-only user. This option is not currently supported for other database engines. ##### Request: `/v2/databases/{database_cluster_uuid}/users` ### Payload Content type `application/json` Example ```json { "name": "my-readonly", "readonly": true } ``` ```json { "name": "app-01" } ``` ```json { "name": "app-02", "settings": { "pg_allow_replication": true } } ``` ```json { "name": "my-readWrite", "settings": { "mongo_user_settings": { "databases": [ "my-db", "my-db-2" ], "role": "readWrite" } } } ``` ```json { "name": "app-03", "settings": { "acl": [ { "permission": "produceconsume", "topic": "customer-events" }, { "permission": "produce", "topic": "customer-events.*" }, { "permission": "consume", "topic": "customer-events" } ] } } ``` ```json { "mysql_settings": { "auth_plugin": "mysql_native_password" }, "name": "app-02" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"name": "app-01"}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() addUserRequest := &godo.DatabaseCreateUserRequest{ Name: "app-01", } user, _, err := client.Databases.CreateUser(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", addUserRequest) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) add_user_resp = client.databases.add_user(database_cluster_uuid="ab7bb7a", body={"name": "app-01"}) ``` #### Responses **201** A JSON object with a key of user. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `user` object required **Show child properties** `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. **Show child properties** `id` string optional Example: `aaa` An identifier for the ACL. Will be computed after the ACL is created/updated. `permission` string, one of: admin, consume, produce, produceconsume required Example: `consume` Permission set applied to the ACL. 'consume' allows for messages to be consumed from the topic. 'produce' allows for messages to be published to the topic. 'produceconsume' allows for both 'consume' and 'produce' permission. 'admin' allows for 'produceconsume' as well as any operations to administer the topic (delete, update). `topic` string required Example: `topic-abc.*` A regex for matching the topic(s) that this ACL should apply to. `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. **Show child properties** `databases` array of string optional Example: `["my-db","my-db-2"]` A list of databases to which the user should have access. When the database is set to `admin`, the user will have access to all databases based on the user's role i.e. a user with the role `readOnly` assigned to the `admin` database will have read access to all databases. `role` string, one of: readOnly, readWrite, dbAdmin optional Example: `readOnly` The role to assign to the user with each role mapping to a MongoDB built-in role. `readOnly` maps to a [read](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) role. `readWrite` maps to a [readWrite](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) role. `dbAdmin` maps to a [dbAdmin](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) role. `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. **Show child properties** `index` string optional Example: `index-abc.*` A regex for matching the indexes that this ACL should apply to. `permission` string, one of: deny, admin, read, readwrite, write optional Example: `read` Permission set applied to the ACL. 'read' allows user to read from the index. 'write' allows for user to write to the index. 'readwrite' allows for both 'read' and 'write' permission. 'deny'(default) restricts user from performing any operation over an index. 'admin' allows for 'readwrite' as well as any operations to administer the index. `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **201** Example ```json { "user": { "access_cert": "-----BEGIN CERTIFICATE-----\nMIIEexampleCertificateNotForProductionUseOnly\n-----END CERTIFICATE-----", "access_key": "-----BEGIN PRIVATE KEY-----\nMIIEexamplePrivateKeyNotForProductionUseOnly\n-----END PRIVATE KEY-----", "name": "app-03", "password": "example_password", "role": "normal", "settings": { "acl": [ { "id": "acl128aaaa99239", "permission": "produceconsume", "topic": "customer-events" }, { "id": "acl293098flskdf", "permission": "produce", "topic": "customer-events.*" }, { "id": "acl128ajei20123", "permission": "consume", "topic": "customer-events" } ] } } } ``` ```json { "user": { "name": "app-01", "password": "example_password", "role": "normal" } } ``` ```json { "user": { "name": "app-02", "password": "example_password", "role": "normal", "settings": { "pg_allow_replication": true } } } ``` ```json { "user": { "mysql_settings": { "auth_plugin": "mysql_native_password" }, "name": "app-02", "password": "example_password", "role": "normal" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Existing Database User `/v2/databases/{database_cluster_uuid}/users/{username}` To show information about an existing database user, send a GET request to `/v2/databases/$DATABASE_ID/users/$USERNAME`. Note: User management is not supported for Caching or Valkey clusters. The response will be a JSON object with a `user` key. This will be set to an object containing the standard database user attributes. The user's password will not show up unless the `database:view_credentials` scope is present. For MySQL clusters, additional options will be contained in the `mysql_settings` object. For PostgreSQL clusters, additional options will be contained in the `settings` object (for example, `pg_allow_replication`). For Kafka clusters, additional options will be contained in the `settings` object. For MongoDB clusters, additional information will be contained in the mongo_user_settings object #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `username` string required Example: `app-01` The name of the database user. ##### Request: `/v2/databases/{database_cluster_uuid}/users/{username}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users/app-01" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() user, _, err := client.Databases.GetUser(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "app-01") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_user(database_cluster_uuid="9a9aba", username="admin") ``` #### Responses **200** A JSON object with a key of user. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `user` object required **Show child properties** `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. **Show child properties** `id` string optional Example: `aaa` An identifier for the ACL. Will be computed after the ACL is created/updated. `permission` string, one of: admin, consume, produce, produceconsume required Example: `consume` Permission set applied to the ACL. 'consume' allows for messages to be consumed from the topic. 'produce' allows for messages to be published to the topic. 'produceconsume' allows for both 'consume' and 'produce' permission. 'admin' allows for 'produceconsume' as well as any operations to administer the topic (delete, update). `topic` string required Example: `topic-abc.*` A regex for matching the topic(s) that this ACL should apply to. `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. **Show child properties** `databases` array of string optional Example: `["my-db","my-db-2"]` A list of databases to which the user should have access. When the database is set to `admin`, the user will have access to all databases based on the user's role i.e. a user with the role `readOnly` assigned to the `admin` database will have read access to all databases. `role` string, one of: readOnly, readWrite, dbAdmin optional Example: `readOnly` The role to assign to the user with each role mapping to a MongoDB built-in role. `readOnly` maps to a [read](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) role. `readWrite` maps to a [readWrite](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) role. `dbAdmin` maps to a [dbAdmin](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) role. `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. **Show child properties** `index` string optional Example: `index-abc.*` A regex for matching the indexes that this ACL should apply to. `permission` string, one of: deny, admin, read, readwrite, write optional Example: `read` Permission set applied to the ACL. 'read' allows user to read from the index. 'write' allows for user to write to the index. 'readwrite' allows for both 'read' and 'write' permission. 'deny'(default) restricts user from performing any operation over an index. 'admin' allows for 'readwrite' as well as any operations to administer the index. `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** Example ```json { "user": { "access_cert": "-----BEGIN CERTIFICATE-----\nMIIEexampleCertificateNotForProductionUseOnly\n-----END CERTIFICATE-----", "access_key": "-----BEGIN PRIVATE KEY-----\nMIIEexamplePrivateKeyNotForProductionUseOnly\n-----END PRIVATE KEY-----", "name": "app-03", "password": "example_password", "role": "normal", "settings": { "acl": [ { "id": "acl128aaaa99239", "permission": "produceconsume", "topic": "customer-events" }, { "id": "acl293098flskdf", "permission": "produce", "topic": "customer-events.*" }, { "id": "acl128ajei20123", "permission": "consume", "topic": "customer-events" } ] } } } ``` ```json { "user": { "name": "app-01", "password": "example_password", "role": "normal" } } ``` ```json { "user": { "name": "app-02", "password": "example_password", "role": "normal", "settings": { "pg_allow_replication": true } } } ``` ```json { "user": { "mysql_settings": { "auth_plugin": "mysql_native_password" }, "name": "app-02", "password": "example_password", "role": "normal" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update a Database User `/v2/databases/{database_cluster_uuid}/users/{username}` To update an existing database user, send a PUT request to `/v2/databases/$DATABASE_ID/users/$USERNAME` with the desired settings. **Note**: only `settings` can be updated via this type of request. If you wish to change the name of a user, you must recreate a new user. For PostgreSQL clusters, you can update `settings.pg_allow_replication` to enable or disable replication privileges for the user. When omitted, the value defaults to `false`. For Kafka and OpenSearch clusters, additional options can be configured in the `settings` object (for example, topic or index ACLs). Updating users is supported for PostgreSQL, Kafka, and OpenSearch clusters. For other engines, the request returns a 422. MongoDB roles and database access are set with `settings.mongo_user_settings` when creating a user and cannot be changed afterward; recreate the user to apply different roles or databases. The response will be a JSON object with a key called `user`. The value of this will be an object that contains the name of the updated database user, along with the `settings` object that has been updated. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `username` string required Example: `app-01` The name of the database user. #### Request Body: `application/json` `settings` object optional User settings that can be updated via the Update a Database User endpoint. Supported for PostgreSQL, Kafka, and OpenSearch clusters. For other engines, the request returns a 422. MongoDB user roles and database access (`mongo_user_settings`) cannot be updated after creation; recreate the user to change them. **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. **Show child properties** `id` string optional Example: `aaa` An identifier for the ACL. Will be computed after the ACL is created/updated. `permission` string, one of: admin, consume, produce, produceconsume required Example: `consume` Permission set applied to the ACL. 'consume' allows for messages to be consumed from the topic. 'produce' allows for messages to be published to the topic. 'produceconsume' allows for both 'consume' and 'produce' permission. 'admin' allows for 'produceconsume' as well as any operations to administer the topic (delete, update). `topic` string required Example: `topic-abc.*` A regex for matching the topic(s) that this ACL should apply to. `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. **Show child properties** `index` string optional Example: `index-abc.*` A regex for matching the indexes that this ACL should apply to. `permission` string, one of: deny, admin, read, readwrite, write optional Example: `read` Permission set applied to the ACL. 'read' allows user to read from the index. 'write' allows for user to write to the index. 'readwrite' allows for both 'read' and 'write' permission. 'deny'(default) restricts user from performing any operation over an index. 'admin' allows for 'readwrite' as well as any operations to administer the index. `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. ##### Request: `/v2/databases/{database_cluster_uuid}/users/{username}` ### Payload Content type `application/json` Example ```json { "settings": { "acl": [ { "id": "acl128aaaa99239", "permission": "produceconsume", "topic": "customer-events" }, { "id": "acl293098flskdf", "permission": "produce", "topic": "customer-events.*" }, { "id": "acl128ajei20123", "permission": "consume", "topic": "customer-events" } ] } } ``` ```json { "settings": { "pg_allow_replication": true } } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"settings": {"acl": [{"topic": "events", "permission": "produce"}]}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() userName := "test-user" updateUserRequest := &godo.DatabaseUpdateUserRequest{ Settings: { ACL: [ { Permssion: "consume", Topic: "events", } { Permission: "produce", Topic: "metrics", } ] } } user, _, err := client.Databases.UpdateUser(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", userName, updateUserRequest) } ``` #### Responses **201** A JSON object with a key of user. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `user` object required **Show child properties** `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. **Show child properties** `id` string optional Example: `aaa` An identifier for the ACL. Will be computed after the ACL is created/updated. `permission` string, one of: admin, consume, produce, produceconsume required Example: `consume` Permission set applied to the ACL. 'consume' allows for messages to be consumed from the topic. 'produce' allows for messages to be published to the topic. 'produceconsume' allows for both 'consume' and 'produce' permission. 'admin' allows for 'produceconsume' as well as any operations to administer the topic (delete, update). `topic` string required Example: `topic-abc.*` A regex for matching the topic(s) that this ACL should apply to. `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. **Show child properties** `databases` array of string optional Example: `["my-db","my-db-2"]` A list of databases to which the user should have access. When the database is set to `admin`, the user will have access to all databases based on the user's role i.e. a user with the role `readOnly` assigned to the `admin` database will have read access to all databases. `role` string, one of: readOnly, readWrite, dbAdmin optional Example: `readOnly` The role to assign to the user with each role mapping to a MongoDB built-in role. `readOnly` maps to a [read](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) role. `readWrite` maps to a [readWrite](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) role. `dbAdmin` maps to a [dbAdmin](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) role. `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. **Show child properties** `index` string optional Example: `index-abc.*` A regex for matching the indexes that this ACL should apply to. `permission` string, one of: deny, admin, read, readwrite, write optional Example: `read` Permission set applied to the ACL. 'read' allows user to read from the index. 'write' allows for user to write to the index. 'readwrite' allows for both 'read' and 'write' permission. 'deny'(default) restricts user from performing any operation over an index. 'admin' allows for 'readwrite' as well as any operations to administer the index. `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **422** Unprocessable Entity Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **201** Example ```json { "user": { "access_cert": "-----BEGIN CERTIFICATE-----\nMIIEexampleCertificateNotForProductionUseOnly\n-----END CERTIFICATE-----", "access_key": "-----BEGIN PRIVATE KEY-----\nMIIEexamplePrivateKeyNotForProductionUseOnly\n-----END PRIVATE KEY-----", "name": "app-03", "password": "example_password", "role": "normal", "settings": { "acl": [ { "id": "acl128aaaa99239", "permission": "produceconsume", "topic": "customer-events" }, { "id": "acl293098flskdf", "permission": "produce", "topic": "customer-events.*" }, { "id": "acl128ajei20123", "permission": "consume", "topic": "customer-events" } ] } } } ``` ```json { "user": { "name": "app-01", "password": "example_password", "role": "normal" } } ``` ```json { "user": { "name": "app-02", "password": "example_password", "role": "normal", "settings": { "pg_allow_replication": true } } } ``` ```json { "user": { "mysql_settings": { "auth_plugin": "mysql_native_password" }, "name": "app-02", "password": "example_password", "role": "normal" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **422** ```json { "id": "unprocessable_entity", "message": "request payload validation failed", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Remove a Database User `/v2/databases/{database_cluster_uuid}/users/{username}` To remove a specific database user, send a DELETE request to `/v2/databases/$DATABASE_ID/users/$USERNAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. Note: User management is not supported for Caching or Valkey clusters. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `username` string required Example: `app-01` The name of the database user. ##### Request: `/v2/databases/{database_cluster_uuid}/users/{username}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users/app-01" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() _, err := client.Databases.DeleteUser(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "app-01") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) delete_resp = client.databases.delete_user(database_cluster_uuid="aba134a", username="backend_user1") ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Reset a Database User's Password or Authentication Method `/v2/databases/{database_cluster_uuid}/users/{username}/reset_auth` To reset the password for a database user, send a POST request to `/v2/databases/$DATABASE_ID/users/$USERNAME/reset_auth`. For `mysql` databases, the authentication method can be specifying by including a key in the JSON body called `mysql_settings` with the `auth_plugin` value specified. The response will be a JSON object with a `user` key. This will be set to an object containing the standard database user attributes. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `username` string required Example: `app-01` The name of the database user. #### Request Body: `application/json` `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. ##### Request: `/v2/databases/{database_cluster_uuid}/users/{username}/reset_auth` ### Payload Content type `application/json` ```json { "mysql_settings": { "auth_plugin": "caching_sha2_password" } } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"mysql_settings":{"auth_plugin": "caching_sha2_password"}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users/app-01/reset_auth" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() resetUserAuthRequest := &godo.DatabaseResetUserAuthRequest{ MySQLSettings: &DatabaseMySQLUserSettings{ AuthPlugin: "caching_sha2_password", }, } user, _, err := client.Databases.ResetUserAuth(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", "app-01", resetuserAuthRequest) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "mysql_settings": { "auth_plugin": "caching_sha2_password" } } get_resp = client.databases.reset_auth(database_cluster_uuid="a7a8bas", username="admin", body=req) ``` #### Responses **200** A JSON object with a key of user. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `user` object required **Show child properties** `access_cert` string optional read-only Access certificate for TLS client authentication. (Kafka only) `access_key` string optional read-only Access key for TLS client authentication. (Kafka only) `mysql_settings` object optional **Show child properties** `auth_plugin` string, one of: mysql_native_password, caching_sha2_password required Example: `mysql_native_password` A string specifying the authentication method to be used for connections to the MySQL user account. The valid values are `mysql_native_password` or `caching_sha2_password`. If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is `caching_sha2_password`. `name` string required Example: `app-01` The name of a database user. `password` string optional read-only Example: `example_password` A randomly generated password for the database user. Requires `database:view_credentials` scope. `role` string, one of: primary, normal optional read-only Example: `normal` A string representing the database user's role. The value will be either "primary" or "normal". `settings` object optional **Show child properties** `acl` array of object optional ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster. **Show child properties** `id` string optional Example: `aaa` An identifier for the ACL. Will be computed after the ACL is created/updated. `permission` string, one of: admin, consume, produce, produceconsume required Example: `consume` Permission set applied to the ACL. 'consume' allows for messages to be consumed from the topic. 'produce' allows for messages to be published to the topic. 'produceconsume' allows for both 'consume' and 'produce' permission. 'admin' allows for 'produceconsume' as well as any operations to administer the topic (delete, update). `topic` string required Example: `topic-abc.*` A regex for matching the topic(s) that this ACL should apply to. `mongo_user_settings` object optional MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines. **Show child properties** `databases` array of string optional Example: `["my-db","my-db-2"]` A list of databases to which the user should have access. When the database is set to `admin`, the user will have access to all databases based on the user's role i.e. a user with the role `readOnly` assigned to the `admin` database will have read access to all databases. `role` string, one of: readOnly, readWrite, dbAdmin optional Example: `readOnly` The role to assign to the user with each role mapping to a MongoDB built-in role. `readOnly` maps to a [read](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) role. `readWrite` maps to a [readWrite](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) role. `dbAdmin` maps to a [dbAdmin](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) role. `opensearch_acl` array of object optional ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster. **Show child properties** `index` string optional Example: `index-abc.*` A regex for matching the indexes that this ACL should apply to. `permission` string, one of: deny, admin, read, readwrite, write optional Example: `read` Permission set applied to the ACL. 'read' allows user to read from the index. 'write' allows for user to write to the index. 'readwrite' allows for both 'read' and 'write' permission. 'deny'(default) restricts user from performing any operation over an index. 'admin' allows for 'readwrite' as well as any operations to administer the index. `pg_allow_replication` boolean optional Example: `true` For PostgreSQL clusters, set to `true` to grant the user replication privileges. When omitted on create or update, the value defaults to `false` and replication privileges are not granted. This option is not currently supported for other database engines. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** Example ```json { "user": { "access_cert": "-----BEGIN CERTIFICATE-----\nMIIEexampleCertificateNotForProductionUseOnly\n-----END CERTIFICATE-----", "access_key": "-----BEGIN PRIVATE KEY-----\nMIIEexamplePrivateKeyNotForProductionUseOnly\n-----END PRIVATE KEY-----", "name": "app-03", "password": "example_password", "role": "normal", "settings": { "acl": [ { "id": "acl128aaaa99239", "permission": "produceconsume", "topic": "customer-events" }, { "id": "acl293098flskdf", "permission": "produce", "topic": "customer-events.*" }, { "id": "acl128ajei20123", "permission": "consume", "topic": "customer-events" } ] } } } ``` ```json { "user": { "name": "app-01", "password": "example_password", "role": "normal" } } ``` ```json { "user": { "name": "app-02", "password": "example_password", "role": "normal", "settings": { "pg_allow_replication": true } } } ``` ```json { "user": { "mysql_settings": { "auth_plugin": "mysql_native_password" }, "name": "app-02", "password": "example_password", "role": "normal" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List All Databases `/v2/databases/{database_cluster_uuid}/dbs` To list all of the databases in a clusters, send a GET request to `/v2/databases/$DATABASE_ID/dbs`. The result will be a JSON object with a `dbs` key. This will be set to an array of database objects, each of which will contain the standard database attributes. Note: Database management is not supported for Caching or Valkey clusters. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/dbs` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() dbs, _, err := client.Databases.ListDBs(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.list(database_cluster_uuid="a7aba9d") ``` #### Responses **200** A JSON object with a key of databases. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `dbs` array of object optional **Show child properties** `name` string required Example: `alpha` The name of the database. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "dbs": [ { "name": "alpha" }, { "name": "defaultdb" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Add a New Database `/v2/databases/{database_cluster_uuid}/dbs` To add a new database to an existing cluster, send a POST request to `/v2/databases/$DATABASE_ID/dbs`. Note: Database management is not supported for Caching or Valkey clusters. The response will be a JSON object with a key called `db`. The value of this will be an object that contains the standard attributes associated with a database. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `name` string required Example: `alpha` The name of the database. ##### Request: `/v2/databases/{database_cluster_uuid}/dbs` ### Payload Content type `application/json` ```json { "name": "alpha" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"name": "alpha"}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() createDBReq := &godo.DatabaseCreateDBRequest{ Name: "alpha", } db, _, err := client.Databases.CreateDB(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", createDBReq) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) add_resp = client.databases.add(database_cluster_uuid="9cc10173", body={"name": "alpha"}) ``` #### Responses **201** A JSON object with a key of db. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `db` object required **Show child properties** `name` string required Example: `alpha` The name of the database. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **201** ```json { "db": { "name": "alpha" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Existing Database `/v2/databases/{database_cluster_uuid}/dbs/{database_name}` To show information about an existing database cluster, send a GET request to `/v2/databases/$DATABASE_ID/dbs/$DB_NAME`. Note: Database management is not supported for Caching or Valkey clusters. The response will be a JSON object with a `db` key. This will be set to an object containing the standard database attributes. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `database_name` string required Example: `alpha` The name of the database. ##### Request: `/v2/databases/{database_cluster_uuid}/dbs/{database_name}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs/alpha" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() db, _, err := client.Databases.GetDB(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "alpha") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get(database_cluster_uuid="a9a8a77", database_name="admin") ``` #### Responses **200** A JSON object with a key of db. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `db` object required **Show child properties** `name` string required Example: `alpha` The name of the database. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "db": { "name": "alpha" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete a Database `/v2/databases/{database_cluster_uuid}/dbs/{database_name}` To delete a specific database, send a DELETE request to `/v2/databases/$DATABASE_ID/dbs/$DB_NAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. Note: Database management is not supported for Caching or Valkey clusters. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `database_name` string required Example: `alpha` The name of the database. ##### Request: `/v2/databases/{database_cluster_uuid}/dbs/{database_name}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs/alpha" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() _, err := client.Databases.DeleteDB(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "alpha") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) delete_resp = client.databases.delete(database_cluster_uuid="a7abda", database_name="ba1341") ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Connection Pools (PostgreSQL) `/v2/databases/{database_cluster_uuid}/pools` To list all of the connection pools available to a PostgreSQL database cluster, send a GET request to `/v2/databases/$DATABASE_ID/pools`. The result will be a JSON object with a `pools` key. This will be set to an array of connection pool objects. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/pools` ### cURL ```bash curl -X GET / -H "Content-Type: application/json" / -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" / "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools" ``` ### Go ```go import ( "context" "github.com/digitalocean/godo" ) func main() { pat := "mytoken" client := godo.NewFromToken(pat) ctx := context.TODO() pools, _, err := client.Databases.ListPools(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.list_connection_pools(database_cluster_uuid="a7aab9a") ``` #### Responses **200** A JSON object with a key of pools. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `pools` array of object optional read-only An array of connection pool objects. **Show child properties** `connection` object optional `db` string required Example: `defaultdb` The database for use with the connection pool. `mode` string required Example: `transaction` The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement. `name` string required Example: `backend-pool` A unique name for the connection pool. Must be between 3 and 60 characters. `private_connection` object optional `size` integer (int32) required Example: `10` The desired size of the PGBouncer connection pool. The maximum allowed size is determined by the size of the cluster's primary node. 25 backend server connections are allowed for every 1GB of RAM. Three are reserved for maintenance. For example, a primary node with 1 GB of RAM allows for a maximum of 22 backend server connections while one with 4 GB would allow for 97. Note that these are shared across all connection pools in a cluster. `standby_connection` object optional `standby_private_connection` object optional `user` string optional Example: `doadmin` The name of the user for use with the connection pool. When excluded, all sessions connect to the database as the inbound user. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "pools": [ { "connection": { "database": "foo", "host": "db.example.com", "password": "example_password", "port": 25061, "ssl": true, "uri": "postgres://doadmin:example_password@db.example.com:25061/foo?sslmode=require", "user": "doadmin" }, "db": "defaultdb", "mode": "session", "name": "reporting-pool", "size": 10, "user": "doadmin" }, { "connection": { "database": "backend-pool", "host": "db.example.com", "password": "example_password", "port": 25061, "ssl": true, "uri": "postgres://doadmin:example_password@db.example.com:25061/backend-pool?sslmode=require", "user": "doadmin" }, "db": "defaultdb", "mode": "transaction", "name": "backend-pool", "size": 10, "user": "doadmin" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Add a New Connection Pool (PostgreSQL) `/v2/databases/{database_cluster_uuid}/pools` For PostgreSQL database clusters, connection pools can be used to allow a database to share its idle connections. The popular PostgreSQL connection pooling utility PgBouncer is used to provide this service. [See here for more information](https://docs.digitalocean.com/products/databases/postgresql/how-to/manage-connection-pools/index.html.md) about how and why to use PgBouncer connection pooling including details about the available transaction modes. To add a new connection pool to a PostgreSQL database cluster, send a POST request to `/v2/databases/$DATABASE_ID/pools` specifying a name for the pool, the user to connect with, the database to connect to, as well as its desired size and transaction mode. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `connection` object optional `db` string required Example: `defaultdb` The database for use with the connection pool. `mode` string required Example: `transaction` The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement. `name` string required Example: `backend-pool` A unique name for the connection pool. Must be between 3 and 60 characters. `private_connection` object optional `size` integer (int32) required Example: `10` The desired size of the PGBouncer connection pool. The maximum allowed size is determined by the size of the cluster's primary node. 25 backend server connections are allowed for every 1GB of RAM. Three are reserved for maintenance. For example, a primary node with 1 GB of RAM allows for a maximum of 22 backend server connections while one with 4 GB would allow for 97. Note that these are shared across all connection pools in a cluster. `standby_connection` object optional `standby_private_connection` object optional `user` string optional Example: `doadmin` The name of the user for use with the connection pool. When excluded, all sessions connect to the database as the inbound user. ##### Request: `/v2/databases/{database_cluster_uuid}/pools` ### Payload Content type `application/json` ```json { "db": "defaultdb", "mode": "transaction", "name": "backend-pool", "size": 10, "user": "doadmin" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"name": "backend-pool","mode": "transaction","size": 10,"db": "defaultdb","user": "doadmin"}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools" ``` ### Go ```go import ( "context" "github.com/digitalocean/godo" ) func main() { pat := "mytoken" client := godo.NewFromToken(pat) ctx := context.TODO() createPoolReq := &godo.DatabaseCreatePoolRequest{ Name: "backend-pool", Database: "defaultdb", Size: 10, User: "doadmin", Mode: "transaction", } pool, _, err := client.Databases.CreatePool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", createPoolReq) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) add_conn_pool_req = { "name": "backend-pool", "mode": "transaction", "size": 10, "db": "defaultdb", "user": "doadmin" } add_conn_pool_resp = client.databases.add_connection_pool(database_cluster_uuid="9cc10173", body=add_conn_pool_req) ``` #### Responses **201** A JSON object with a key of pool. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `pool` object required **Show child properties** `connection` object optional `db` string required Example: `defaultdb` The database for use with the connection pool. `mode` string required Example: `transaction` The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement. `name` string required Example: `backend-pool` A unique name for the connection pool. Must be between 3 and 60 characters. `private_connection` object optional `size` integer (int32) required Example: `10` The desired size of the PGBouncer connection pool. The maximum allowed size is determined by the size of the cluster's primary node. 25 backend server connections are allowed for every 1GB of RAM. Three are reserved for maintenance. For example, a primary node with 1 GB of RAM allows for a maximum of 22 backend server connections while one with 4 GB would allow for 97. Note that these are shared across all connection pools in a cluster. `standby_connection` object optional `standby_private_connection` object optional `user` string optional Example: `doadmin` The name of the user for use with the connection pool. When excluded, all sessions connect to the database as the inbound user. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **201** ```json { "pool": { "connection": { "database": "backend-pool", "host": "db.example.com", "password": "example_password", "port": 25061, "ssl": true, "uri": "postgres://doadmin:example_password@db.example.com:25061/backend-pool?sslmode=require", "user": "doadmin" }, "db": "defaultdb", "mode": "transaction", "name": "backend-pool", "size": 10, "user": "doadmin" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Existing Connection Pool (PostgreSQL) `/v2/databases/{database_cluster_uuid}/pools/{pool_name}` To show information about an existing connection pool for a PostgreSQL database cluster, send a GET request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`. The response will be a JSON object with a `pool` key. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `pool_name` string required Example: `backend-pool` The name used to identify the connection pool. ##### Request: `/v2/databases/{database_cluster_uuid}/pools/{pool_name}` ### cURL ```bash curl -X GET / -H "Content-Type: application/json" / -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" / "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools/backend-pool" ``` ### Go ```go import ( "context" "github.com/digitalocean/godo" ) func main() { pat := "mytoken" client := godo.NewFromToken(pat) ctx := context.TODO() pool, _, err := client.Databases.GetPool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "backend-pool") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_connection_pool(database_cluster_uuid="a7aba8a", pool_name="backend-pool") ``` #### Responses **200** A JSON object with a key of pool. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `pool` object required **Show child properties** `connection` object optional `db` string required Example: `defaultdb` The database for use with the connection pool. `mode` string required Example: `transaction` The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement. `name` string required Example: `backend-pool` A unique name for the connection pool. Must be between 3 and 60 characters. `private_connection` object optional `size` integer (int32) required Example: `10` The desired size of the PGBouncer connection pool. The maximum allowed size is determined by the size of the cluster's primary node. 25 backend server connections are allowed for every 1GB of RAM. Three are reserved for maintenance. For example, a primary node with 1 GB of RAM allows for a maximum of 22 backend server connections while one with 4 GB would allow for 97. Note that these are shared across all connection pools in a cluster. `standby_connection` object optional `standby_private_connection` object optional `user` string optional Example: `doadmin` The name of the user for use with the connection pool. When excluded, all sessions connect to the database as the inbound user. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "pool": { "connection": { "database": "backend-pool", "host": "db.example.com", "password": "example_password", "port": 25061, "ssl": true, "uri": "postgres://doadmin:example_password@db.example.com:25061/backend-pool?sslmode=require", "user": "doadmin" }, "db": "defaultdb", "mode": "transaction", "name": "backend-pool", "size": 10, "user": "doadmin" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Connection Pools (PostgreSQL) `/v2/databases/{database_cluster_uuid}/pools/{pool_name}` To update a connection pool for a PostgreSQL database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `pool_name` string required Example: `backend-pool` The name used to identify the connection pool. #### Request Body: `application/json` `db` string required Example: `defaultdb` The database for use with the connection pool. `mode` string required Example: `transaction` The PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement. `size` integer (int32) required Example: `10` The desired size of the PGBouncer connection pool. The maximum allowed size is determined by the size of the cluster's primary node. 25 backend server connections are allowed for every 1GB of RAM. Three are reserved for maintenance. For example, a primary node with 1 GB of RAM allows for a maximum of 22 backend server connections while one with 4 GB would allow for 97. Note that these are shared across all connection pools in a cluster. `user` string optional Example: `doadmin` The name of the user for use with the connection pool. When excluded, all sessions connect to the database as the inbound user. ##### Request: `/v2/databases/{database_cluster_uuid}/pools/{pool_name}` ### Payload Content type `application/json` ```json { "db": "defaultdb", "mode": "transaction", "size": 10, "user": "doadmin" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"mode": "transaction", "size": 15, "db": "defaultdb", "user": "doadmin"}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools/backend-pool" ``` ### Go ```go import ( "context" "github.com/digitalocean/godo" ) func main() { pat := "mytoken" client := godo.NewFromToken(pat) ctx := context.TODO() updateReq := &godo.DatabaseUpdatePoolRequest{ User: "doadmin", Size: 15, Database: "defaultdb", Mode: "transaction", } _, err := client.Databases.UpdatePool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "backend-pool", updateReq) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "mode": "transaction", "size": 10, "db": "defaultdb", "user": "doadmin" } update_resp = client.databases.update_connection_pool(database_cluster_uuid="a7a8bas", pool_name="conn_pool", body=req) ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete a Connection Pool (PostgreSQL) `/v2/databases/{database_cluster_uuid}/pools/{pool_name}` To delete a specific connection pool for a PostgreSQL database cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `pool_name` string required Example: `backend-pool` The name used to identify the connection pool. ##### Request: `/v2/databases/{database_cluster_uuid}/pools/{pool_name}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools/backend-pool" ``` ### Go ```go import ( "context" "github.com/digitalocean/godo" ) func main() { pat := "mytoken" client := godo.NewFromToken(pat) ctx := context.TODO() _, err := client.Databases.DeletePool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "backend-pool") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) delete_conn_pool = client.databases.delete_connection_pool(database_cluster_uuid="9cc10173", pool_name="backend-pool") ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve the Eviction Policy for a Caching or Valkey Cluster `/v2/databases/{database_cluster_uuid}/eviction_policy` To retrieve the configured eviction policy for an existing Caching or Valkey cluster, send a GET request to `/v2/databases/$DATABASE_ID/eviction_policy`. The response will be a JSON object with an `eviction_policy` key. This will be set to a string representing the eviction policy. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/eviction_policy` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/eviction_policy" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() db, _, err := client.Databases.GetEvictionPolicy(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_eviction_policy(database_cluster_uuid="a7aa89a") ``` #### Responses **200** A JSON string with a key of eviction_policy. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `eviction_policy` string (enum) required Example: `allkeys_lru` A string specifying the desired eviction policy for a Caching or Valkey cluster. - `noeviction`: Don't evict any data, returns error when memory limit is reached. - `allkeys_lru:` Evict any key, least recently used (LRU) first. - `allkeys_random`: Evict keys in a random order. - `volatile_lru`: Evict keys with expiration only, least recently used (LRU) first. - `volatile_random`: Evict keys with expiration only in a random order. - `volatile_ttl`: Evict keys with expiration only, shortest time-to-live (TTL) first. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "eviction_policy": "allkeys_lru" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Configure the Eviction Policy for a Caching or Valkey Cluster `/v2/databases/{database_cluster_uuid}/eviction_policy` To configure an eviction policy for an existing Caching or Valkey cluster, send a PUT request to `/v2/databases/$DATABASE_ID/eviction_policy` specifying the desired policy. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `eviction_policy` string (enum) required Example: `allkeys_lru` A string specifying the desired eviction policy for a Caching or Valkey cluster. - `noeviction`: Don't evict any data, returns error when memory limit is reached. - `allkeys_lru:` Evict any key, least recently used (LRU) first. - `allkeys_random`: Evict keys in a random order. - `volatile_lru`: Evict keys with expiration only, least recently used (LRU) first. - `volatile_random`: Evict keys with expiration only in a random order. - `volatile_ttl`: Evict keys with expiration only, shortest time-to-live (TTL) first. ##### Request: `/v2/databases/{database_cluster_uuid}/eviction_policy` ### Payload Content type `application/json` ```json { "eviction_policy": "allkeys_lru" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"eviction_policy":"allkeys_lru"}' \ "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/eviction_policy" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() db, _, err := client.Databases.SetEvictionPolicy(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "allkeys_lru") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "eviction_policy": "allkeys_lru" } update_resp = client.databases.update_eviction_policy(database_cluster_uuid="a7a8bas", body=req) ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve the SQL Modes for a MySQL Cluster `/v2/databases/{database_cluster_uuid}/sql_mode` To retrieve the configured SQL modes for an existing MySQL cluster, send a GET request to `/v2/databases/$DATABASE_ID/sql_mode`. The response will be a JSON object with a `sql_mode` key. This will be set to a string representing the configured SQL modes. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/sql_mode` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/sql_mode" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() sqlMode, _, err := client.Databases.GetSQLMode(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_sql_mode(database_cluster_uuid="90abaa8") ``` #### Responses **200** A JSON string with a key of sql_mode. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `sql_mode` string required A string specifying the configured SQL modes for the MySQL cluster. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update SQL Mode for a Cluster `/v2/databases/{database_cluster_uuid}/sql_mode` To configure the SQL modes for an existing MySQL cluster, send a PUT request to `/v2/databases/$DATABASE_ID/sql_mode` specifying the desired modes. See the official MySQL 8 documentation for a [full list of supported SQL modes](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sql-mode-full). A successful request will receive a 204 No Content status code with no body in response. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `sql_mode` string required A string specifying the configured SQL modes for the MySQL cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/sql_mode` ### Payload Content type `application/json` ```json { "sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"sql_mode":"ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE"}' \ "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/sql_mode" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() sqlMode := "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE" _, err := client.Databases.SetSQLMode(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", sqlMode) } ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE" } update_resp = client.databases.update_sql_mode(database_cluster_uuid="a7a8bas", body=req) ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Upgrade Major Version for a Database `/v2/databases/{database_cluster_uuid}/upgrade` To upgrade the major version of a database, send a PUT request to `/v2/databases/$DATABASE_ID/upgrade`, specifying the target version. A successful request will receive a 204 No Content status code with no body in response. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `version` string optional Example: `8` A string representing the version of the database engine in use for the cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/upgrade` ### Payload Content type `application/json` ```json { "version": "14" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"version":"14"}' \ "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/upgrade" ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "version": "14" } update_resp = client.databases.update_major_version(database_cluster_uuid="a7a8bas", body=req) ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Autoscale Configuration for a Database Cluster `/v2/databases/{database_cluster_uuid}/autoscale` To retrieve the autoscale configuration for an existing database cluster, send a GET request to `/v2/databases/$DATABASE_ID/autoscale`. The response will be a JSON object with autoscaling configuration details. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/autoscale` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/autoscale" ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) get_resp = client.databases.get_autoscale(database_cluster_uuid="a7a89a") ``` #### Responses **200** A JSON object with autoscale configuration details. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `autoscale` object optional Contains all autoscaling configuration for a database cluster **Show child properties** `storage` object optional **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "autoscale": { "storage": { "enabled": true, "increment_gib": 10, "threshold_percent": 80 } } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Configure Autoscale Settings for a Database Cluster `/v2/databases/{database_cluster_uuid}/autoscale` To configure autoscale settings for an existing database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/autoscale`, specifying the autoscale configuration. A successful request will receive a 204 No Content status code with no body in response. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `storage` object optional ##### Request: `/v2/databases/{database_cluster_uuid}/autoscale` ### Payload Content type `application/json` ```json { "storage": { "enabled": true, "increment_gib": 10, "threshold_percent": 80 } } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"storage":{"enabled":true,"threshold_percent":80,"increment_gib":10}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/autoscale" ``` ### Python ```python import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) req = { "storage": { "enabled": True, "threshold_percent": 80, "increment_gib": 10 } } update_resp = client.databases.update_autoscale(database_cluster_uuid="a7a89a", body=req) ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **422** Unprocessable Entity Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **422** ```json { "id": "unprocessable_entity", "message": "request payload validation failed", "request_id": "4851a473-1621-42ea-b2f9-5071c0ea8414" } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Topics for a Kafka Cluster `/v2/databases/{database_cluster_uuid}/topics` To list all of a Kafka cluster's topics, send a GET request to `/v2/databases/$DATABASE_ID/topics`. The result will be a JSON object with a `topics` key. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/topics` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() replicas, _, err := client.Databases.ListTopics(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) } ``` #### Responses **200** A JSON object with a key of topics. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `topics` array of object optional **Show child properties** `name` string optional Example: `events` The name of the Kafka topic. `partition_count` integer optional Example: `3` The number of partitions available for the topic. On update, this value can only be increased. `replication_factor` integer optional Example: `2` The number of nodes to replicate data across the cluster. `state` string, one of: active, configuring, deleting, unknown optional Example: `active` The state of the Kafka topic. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "topics": [ { "name": "customer-events", "partition_count": 3, "replication_factor": 2, "state": "active" }, { "name": "engineering-events", "partition_count": 10, "replication_factor": 2, "state": "configuring" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Topic for a Kafka Cluster `/v2/databases/{database_cluster_uuid}/topics` To create a topic attached to a Kafka cluster, send a POST request to `/v2/databases/$DATABASE_ID/topics`. The result will be a JSON object with a `topic` key. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `name` string optional Example: `events` The name of the Kafka topic. `partition_count` integer optional Example: `3` The number of partitions available for the topic. On update, this value can only be increased. `replication_factor` integer optional Example: `2` The number of nodes to replicate data across the cluster. `config` object optional **Show child properties** `cleanup_policy` string, one of: delete, compact, compact_delete optional Example: `delete` The cleanup_policy sets the retention policy to use on log segments. 'delete' will discard old segments when retention time/size limits are reached. 'compact' will enable log compaction, resulting in retention of the latest value for each key. `compression_type` string (enum) optional Example: `producer` The compression_type specifies the compression type of the topic. `delete_retention_ms` integer optional Example: `86400000` The delete_retention_ms specifies how long (in ms) to retain delete tombstone markers for topics. `file_delete_delay_ms` integer optional Example: `60000` The file_delete_delay_ms specifies the time (in ms) to wait before deleting a file from the filesystem. `flush_messages` integer optional Example: `9223372036854776000` The flush_messages specifies the number of messages to accumulate on a log partition before messages are flushed to disk. `flush_ms` integer optional Example: `9223372036854776000` The flush_ms specifies the maximum time (in ms) that a message is kept in memory before being flushed to disk. `index_interval_bytes` integer optional Example: `4096` The index_interval_bytes specifies the number of bytes between entries being added into te offset index. `max_compaction_lag_ms` integer optional Example: `9223372036854776000` The max_compaction_lag_ms specifies the maximum amount of time (in ms) that a message will remain uncompacted. This is only applicable if the logs are have compaction enabled. `max_message_bytes` integer optional Example: `1048588` The max_messages_bytes specifies the largest record batch size (in bytes) that can be sent to the server. This is calculated after compression if compression is enabled. `message_down_conversion_enable` boolean optional Example: `true` The message_down_conversion_enable specifies whether down-conversion of message formats is enabled to satisfy consumer requests. When 'false', the broker will not perform conversion for consumers expecting older message formats. The broker will respond with an `UNSUPPORTED_VERSION` error for consume requests from these older clients. `message_format_version` string (enum) optional Example: `3.0-IV1` The message_format_version specifies the message format version used by the broker to append messages to the logs. The value of this setting is assumed to be 3.0-IV1 if the broker protocol version is 3.0 or higher. By setting a particular message format version, all existing messages on disk must be smaller or equal to the specified version. `message_timestamp_type` string, one of: create_time, log_append_time optional Example: `create_time` The message_timestamp_type specifies whether to use the message create time or log append time as the timestamp on a message. `min_cleanable_dirty_ratio` number (float) optional Example: `0.5` The min_cleanable_dirty_ratio specifies the frequency of log compaction (if enabled) in relation to duplicates present in the logs. For example, at 0.5, at most 50% of the log could be duplicates before compaction would begin. `min_compaction_lag_ms` integer optional Example: `0` The min_compaction_lag_ms specifies the minimum time (in ms) that a message will remain uncompacted in the log. Only relevant if log compaction is enabled. `min_insync_replicas` integer optional Example: `1` The min_insync_replicas specifies the number of replicas that must ACK a write for the write to be considered successful. `preallocate` boolean optional Example: `false` The preallocate specifies whether a file should be preallocated on disk when creating a new log segment. `retention_bytes` integer optional Example: `1000000` The retention_bytes specifies the maximum size of the log (in bytes) before deleting messages. -1 indicates that there is no limit. `retention_ms` integer optional Example: `604800000` The retention_ms specifies the maximum amount of time (in ms) to keep a message before deleting it. `segment_bytes` integer optional Example: `209715200` The segment_bytes specifies the maximum size of a single log file (in bytes). `segment_jitter_ms` integer optional Example: `0` The segment_jitter_ms specifies the maximum random jitter subtracted from the scheduled segment roll time to avoid thundering herds of segment rolling. `segment_ms` integer optional Example: `604800000` The segment_ms specifies the period of time after which the log will be forced to roll if the segment file isn't full. This ensures that retention can delete or compact old data. ##### Request: `/v2/databases/{database_cluster_uuid}/topics` ### Payload Content type `application/json` ```json { "config": { "retention_bytes": -1, "retention_ms": 100000 }, "name": "customer-events", "partitions": 3, "replication": 2 } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"name":"customer-events", "partition_count":3, "replication_factor": 3, "config": {"retentionMS": 1000000}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() createRequest := &DatabaseCreateTopicRequest{ Name: "events", PartitionCount: 3, ReplicationFactor: 2, Config: &TopicConfig{ RetentionMS: 60000, } }, cluster, _, err := client.Databases.CreateTopic(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", createRequest) } ``` #### Responses **201** A JSON object with a key of topic. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `topic` object optional **Show child properties** `config` object optional **Show child properties** `cleanup_policy` string, one of: delete, compact, compact_delete optional Example: `delete` The cleanup_policy sets the retention policy to use on log segments. 'delete' will discard old segments when retention time/size limits are reached. 'compact' will enable log compaction, resulting in retention of the latest value for each key. `compression_type` string (enum) optional Example: `producer` The compression_type specifies the compression type of the topic. `delete_retention_ms` integer optional Example: `86400000` The delete_retention_ms specifies how long (in ms) to retain delete tombstone markers for topics. `file_delete_delay_ms` integer optional Example: `60000` The file_delete_delay_ms specifies the time (in ms) to wait before deleting a file from the filesystem. `flush_messages` integer optional Example: `9223372036854776000` The flush_messages specifies the number of messages to accumulate on a log partition before messages are flushed to disk. `flush_ms` integer optional Example: `9223372036854776000` The flush_ms specifies the maximum time (in ms) that a message is kept in memory before being flushed to disk. `index_interval_bytes` integer optional Example: `4096` The index_interval_bytes specifies the number of bytes between entries being added into te offset index. `max_compaction_lag_ms` integer optional Example: `9223372036854776000` The max_compaction_lag_ms specifies the maximum amount of time (in ms) that a message will remain uncompacted. This is only applicable if the logs are have compaction enabled. `max_message_bytes` integer optional Example: `1048588` The max_messages_bytes specifies the largest record batch size (in bytes) that can be sent to the server. This is calculated after compression if compression is enabled. `message_down_conversion_enable` boolean optional Example: `true` The message_down_conversion_enable specifies whether down-conversion of message formats is enabled to satisfy consumer requests. When 'false', the broker will not perform conversion for consumers expecting older message formats. The broker will respond with an `UNSUPPORTED_VERSION` error for consume requests from these older clients. `message_format_version` string (enum) optional Example: `3.0-IV1` The message_format_version specifies the message format version used by the broker to append messages to the logs. The value of this setting is assumed to be 3.0-IV1 if the broker protocol version is 3.0 or higher. By setting a particular message format version, all existing messages on disk must be smaller or equal to the specified version. `message_timestamp_type` string, one of: create_time, log_append_time optional Example: `create_time` The message_timestamp_type specifies whether to use the message create time or log append time as the timestamp on a message. `min_cleanable_dirty_ratio` number (float) optional Example: `0.5` The min_cleanable_dirty_ratio specifies the frequency of log compaction (if enabled) in relation to duplicates present in the logs. For example, at 0.5, at most 50% of the log could be duplicates before compaction would begin. `min_compaction_lag_ms` integer optional Example: `0` The min_compaction_lag_ms specifies the minimum time (in ms) that a message will remain uncompacted in the log. Only relevant if log compaction is enabled. `min_insync_replicas` integer optional Example: `1` The min_insync_replicas specifies the number of replicas that must ACK a write for the write to be considered successful. `preallocate` boolean optional Example: `false` The preallocate specifies whether a file should be preallocated on disk when creating a new log segment. `retention_bytes` integer optional Example: `1000000` The retention_bytes specifies the maximum size of the log (in bytes) before deleting messages. -1 indicates that there is no limit. `retention_ms` integer optional Example: `604800000` The retention_ms specifies the maximum amount of time (in ms) to keep a message before deleting it. `segment_bytes` integer optional Example: `209715200` The segment_bytes specifies the maximum size of a single log file (in bytes). `segment_jitter_ms` integer optional Example: `0` The segment_jitter_ms specifies the maximum random jitter subtracted from the scheduled segment roll time to avoid thundering herds of segment rolling. `segment_ms` integer optional Example: `604800000` The segment_ms specifies the period of time after which the log will be forced to roll if the segment file isn't full. This ensures that retention can delete or compact old data. `name` string optional Example: `events` The name of the Kafka topic. `partitions` array of object optional **Show child properties** `consumer_groups` array of object optional Nullable **Show child properties** `group_name` string optional Example: `consumer` Name of the consumer group. `offset` integer optional Example: `0` The current offset of the consumer group. `earliest_offset` integer optional Example: `0` The earliest consumer offset amongst consumer groups. `id` integer optional Example: `1` An identifier for the partition. `in_sync_replicas` integer optional Example: `3` The number of nodes that are in-sync (have the latest data) for the given partition `size` integer optional Example: `4096` Size of the topic partition in bytes. `replication_factor` integer optional Example: `2` The number of nodes to replicate data across the cluster. `state` string, one of: active, configuring, deleting, unknown optional Example: `active` The state of the Kafka topic. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **201** ```json { "topic": { "config": { "cleanup_policy": "delete", "compression_type": "producer", "delete_retention_ms": 86400000, "file_delete_delay_ms": 60000, "flush_messages": "9223372036854776000", "flush_ms": "9223372036854776000", "index_interval_bytes": 4096, "max_compaction_lag_ms": "9223372036854776000", "max_message_bytes": 1048588, "message_down_conversion_enable": true, "message_format_version": "3.0-IV1", "message_timestamp_difference_max_ms": "9223372036854776000", "message_timestamp_type": "create_time", "min_cleanable_dirty_ratio": 0.5, "min_compaction_lag_ms": 0, "min_insync_replicas": 1, "preallocate": false, "retention_bytes": -1, "retention_ms": 604800000, "segment_bytes": 209715200, "segment_index_bytes": 10485760, "segment_jitter_ms": 0, "segment_ms": 604800000 }, "name": "customer-events", "partitions": [ { "consumer_groups": [ { "name": "consumer-group-1", "offset": 0 }, { "name": "consumer-group-2", "offset": 1 } ], "earliest_offset": 0, "id": 0, "in_sync_replicas": 3, "size": 4096 }, { "consumer_groups": null, "earliest_offset": 0, "id": 1, "in_sync_replicas": 3, "size": 4096 } ], "replication_factor": 3, "state": "active" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get Topic for a Kafka Cluster `/v2/databases/{database_cluster_uuid}/topics/{topic_name}` To retrieve a given topic by name from the set of a Kafka cluster's topics, send a GET request to `/v2/databases/$DATABASE_ID/topics/$TOPIC_NAME`. The result will be a JSON object with a `topic` key. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `topic_name` string required Example: `customer-events` The name used to identify the Kafka topic. ##### Request: `/v2/databases/{database_cluster_uuid}/topics/{topic_name}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics/customer-events" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() topicName := "events" user, _, err := client.Databases.GetTopic(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", topicName) } ``` #### Responses **200** A JSON object with a key of topic. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `topic` object optional **Show child properties** `config` object optional **Show child properties** `cleanup_policy` string, one of: delete, compact, compact_delete optional Example: `delete` The cleanup_policy sets the retention policy to use on log segments. 'delete' will discard old segments when retention time/size limits are reached. 'compact' will enable log compaction, resulting in retention of the latest value for each key. `compression_type` string (enum) optional Example: `producer` The compression_type specifies the compression type of the topic. `delete_retention_ms` integer optional Example: `86400000` The delete_retention_ms specifies how long (in ms) to retain delete tombstone markers for topics. `file_delete_delay_ms` integer optional Example: `60000` The file_delete_delay_ms specifies the time (in ms) to wait before deleting a file from the filesystem. `flush_messages` integer optional Example: `9223372036854776000` The flush_messages specifies the number of messages to accumulate on a log partition before messages are flushed to disk. `flush_ms` integer optional Example: `9223372036854776000` The flush_ms specifies the maximum time (in ms) that a message is kept in memory before being flushed to disk. `index_interval_bytes` integer optional Example: `4096` The index_interval_bytes specifies the number of bytes between entries being added into te offset index. `max_compaction_lag_ms` integer optional Example: `9223372036854776000` The max_compaction_lag_ms specifies the maximum amount of time (in ms) that a message will remain uncompacted. This is only applicable if the logs are have compaction enabled. `max_message_bytes` integer optional Example: `1048588` The max_messages_bytes specifies the largest record batch size (in bytes) that can be sent to the server. This is calculated after compression if compression is enabled. `message_down_conversion_enable` boolean optional Example: `true` The message_down_conversion_enable specifies whether down-conversion of message formats is enabled to satisfy consumer requests. When 'false', the broker will not perform conversion for consumers expecting older message formats. The broker will respond with an `UNSUPPORTED_VERSION` error for consume requests from these older clients. `message_format_version` string (enum) optional Example: `3.0-IV1` The message_format_version specifies the message format version used by the broker to append messages to the logs. The value of this setting is assumed to be 3.0-IV1 if the broker protocol version is 3.0 or higher. By setting a particular message format version, all existing messages on disk must be smaller or equal to the specified version. `message_timestamp_type` string, one of: create_time, log_append_time optional Example: `create_time` The message_timestamp_type specifies whether to use the message create time or log append time as the timestamp on a message. `min_cleanable_dirty_ratio` number (float) optional Example: `0.5` The min_cleanable_dirty_ratio specifies the frequency of log compaction (if enabled) in relation to duplicates present in the logs. For example, at 0.5, at most 50% of the log could be duplicates before compaction would begin. `min_compaction_lag_ms` integer optional Example: `0` The min_compaction_lag_ms specifies the minimum time (in ms) that a message will remain uncompacted in the log. Only relevant if log compaction is enabled. `min_insync_replicas` integer optional Example: `1` The min_insync_replicas specifies the number of replicas that must ACK a write for the write to be considered successful. `preallocate` boolean optional Example: `false` The preallocate specifies whether a file should be preallocated on disk when creating a new log segment. `retention_bytes` integer optional Example: `1000000` The retention_bytes specifies the maximum size of the log (in bytes) before deleting messages. -1 indicates that there is no limit. `retention_ms` integer optional Example: `604800000` The retention_ms specifies the maximum amount of time (in ms) to keep a message before deleting it. `segment_bytes` integer optional Example: `209715200` The segment_bytes specifies the maximum size of a single log file (in bytes). `segment_jitter_ms` integer optional Example: `0` The segment_jitter_ms specifies the maximum random jitter subtracted from the scheduled segment roll time to avoid thundering herds of segment rolling. `segment_ms` integer optional Example: `604800000` The segment_ms specifies the period of time after which the log will be forced to roll if the segment file isn't full. This ensures that retention can delete or compact old data. `name` string optional Example: `events` The name of the Kafka topic. `partitions` array of object optional **Show child properties** `consumer_groups` array of object optional Nullable **Show child properties** `group_name` string optional Example: `consumer` Name of the consumer group. `offset` integer optional Example: `0` The current offset of the consumer group. `earliest_offset` integer optional Example: `0` The earliest consumer offset amongst consumer groups. `id` integer optional Example: `1` An identifier for the partition. `in_sync_replicas` integer optional Example: `3` The number of nodes that are in-sync (have the latest data) for the given partition `size` integer optional Example: `4096` Size of the topic partition in bytes. `replication_factor` integer optional Example: `2` The number of nodes to replicate data across the cluster. `state` string, one of: active, configuring, deleting, unknown optional Example: `active` The state of the Kafka topic. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "topic": { "config": { "cleanup_policy": "delete", "compression_type": "producer", "delete_retention_ms": 86400000, "file_delete_delay_ms": 60000, "flush_messages": "9223372036854776000", "flush_ms": "9223372036854776000", "index_interval_bytes": 4096, "max_compaction_lag_ms": "9223372036854776000", "max_message_bytes": 1048588, "message_down_conversion_enable": true, "message_format_version": "3.0-IV1", "message_timestamp_difference_max_ms": "9223372036854776000", "message_timestamp_type": "create_time", "min_cleanable_dirty_ratio": 0.5, "min_compaction_lag_ms": 0, "min_insync_replicas": 1, "preallocate": false, "retention_bytes": -1, "retention_ms": 604800000, "segment_bytes": 209715200, "segment_index_bytes": 10485760, "segment_jitter_ms": 0, "segment_ms": 604800000 }, "name": "customer-events", "partitions": [ { "consumer_groups": [ { "name": "consumer-group-1", "offset": 0 }, { "name": "consumer-group-2", "offset": 1 } ], "earliest_offset": 0, "id": 0, "in_sync_replicas": 3, "size": 4096 }, { "consumer_groups": null, "earliest_offset": 0, "id": 1, "in_sync_replicas": 3, "size": 4096 } ], "replication_factor": 3, "state": "active" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Topic for a Kafka Cluster `/v2/databases/{database_cluster_uuid}/topics/{topic_name}` To update a topic attached to a Kafka cluster, send a PUT request to `/v2/databases/$DATABASE_ID/topics/$TOPIC_NAME`. The result will be a JSON object with a `topic` key. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `topic_name` string required Example: `customer-events` The name used to identify the Kafka topic. #### Request Body: `application/json` `config` object optional **Show child properties** `cleanup_policy` string, one of: delete, compact, compact_delete optional Example: `delete` The cleanup_policy sets the retention policy to use on log segments. 'delete' will discard old segments when retention time/size limits are reached. 'compact' will enable log compaction, resulting in retention of the latest value for each key. `compression_type` string (enum) optional Example: `producer` The compression_type specifies the compression type of the topic. `delete_retention_ms` integer optional Example: `86400000` The delete_retention_ms specifies how long (in ms) to retain delete tombstone markers for topics. `file_delete_delay_ms` integer optional Example: `60000` The file_delete_delay_ms specifies the time (in ms) to wait before deleting a file from the filesystem. `flush_messages` integer optional Example: `9223372036854776000` The flush_messages specifies the number of messages to accumulate on a log partition before messages are flushed to disk. `flush_ms` integer optional Example: `9223372036854776000` The flush_ms specifies the maximum time (in ms) that a message is kept in memory before being flushed to disk. `index_interval_bytes` integer optional Example: `4096` The index_interval_bytes specifies the number of bytes between entries being added into te offset index. `max_compaction_lag_ms` integer optional Example: `9223372036854776000` The max_compaction_lag_ms specifies the maximum amount of time (in ms) that a message will remain uncompacted. This is only applicable if the logs are have compaction enabled. `max_message_bytes` integer optional Example: `1048588` The max_messages_bytes specifies the largest record batch size (in bytes) that can be sent to the server. This is calculated after compression if compression is enabled. `message_down_conversion_enable` boolean optional Example: `true` The message_down_conversion_enable specifies whether down-conversion of message formats is enabled to satisfy consumer requests. When 'false', the broker will not perform conversion for consumers expecting older message formats. The broker will respond with an `UNSUPPORTED_VERSION` error for consume requests from these older clients. `message_format_version` string (enum) optional Example: `3.0-IV1` The message_format_version specifies the message format version used by the broker to append messages to the logs. The value of this setting is assumed to be 3.0-IV1 if the broker protocol version is 3.0 or higher. By setting a particular message format version, all existing messages on disk must be smaller or equal to the specified version. `message_timestamp_type` string, one of: create_time, log_append_time optional Example: `create_time` The message_timestamp_type specifies whether to use the message create time or log append time as the timestamp on a message. `min_cleanable_dirty_ratio` number (float) optional Example: `0.5` The min_cleanable_dirty_ratio specifies the frequency of log compaction (if enabled) in relation to duplicates present in the logs. For example, at 0.5, at most 50% of the log could be duplicates before compaction would begin. `min_compaction_lag_ms` integer optional Example: `0` The min_compaction_lag_ms specifies the minimum time (in ms) that a message will remain uncompacted in the log. Only relevant if log compaction is enabled. `min_insync_replicas` integer optional Example: `1` The min_insync_replicas specifies the number of replicas that must ACK a write for the write to be considered successful. `preallocate` boolean optional Example: `false` The preallocate specifies whether a file should be preallocated on disk when creating a new log segment. `retention_bytes` integer optional Example: `1000000` The retention_bytes specifies the maximum size of the log (in bytes) before deleting messages. -1 indicates that there is no limit. `retention_ms` integer optional Example: `604800000` The retention_ms specifies the maximum amount of time (in ms) to keep a message before deleting it. `segment_bytes` integer optional Example: `209715200` The segment_bytes specifies the maximum size of a single log file (in bytes). `segment_jitter_ms` integer optional Example: `0` The segment_jitter_ms specifies the maximum random jitter subtracted from the scheduled segment roll time to avoid thundering herds of segment rolling. `segment_ms` integer optional Example: `604800000` The segment_ms specifies the period of time after which the log will be forced to roll if the segment file isn't full. This ensures that retention can delete or compact old data. `partition_count` integer optional Example: `3` The number of partitions available for the topic. On update, this value can only be increased. `replication_factor` integer optional Example: `2` The number of nodes to replicate data across the cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/topics/{topic_name}` ### Payload Content type `application/json` ```json { "config": { "retention_bytes": -1, "retention_ms": 100000 }, "partitions": 3, "replication": 2 } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"partition_count":3, "replication_factor": 3, "config": {"retentionMS": 1000000}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics/customer-events" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() topicName := "events" updateRequest := &DatabaseUpdateTopicRequest{ PartitionCount: 3, ReplicationFactor: 2, Config: &TopicConfig{ RetentionMS: 60000, }, } _, err := client.Databases.UpdateTopic(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", topicName, updateRequest) } ``` #### Responses **200** A JSON object with a key of topic. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `topic` object optional **Show child properties** `config` object optional **Show child properties** `cleanup_policy` string, one of: delete, compact, compact_delete optional Example: `delete` The cleanup_policy sets the retention policy to use on log segments. 'delete' will discard old segments when retention time/size limits are reached. 'compact' will enable log compaction, resulting in retention of the latest value for each key. `compression_type` string (enum) optional Example: `producer` The compression_type specifies the compression type of the topic. `delete_retention_ms` integer optional Example: `86400000` The delete_retention_ms specifies how long (in ms) to retain delete tombstone markers for topics. `file_delete_delay_ms` integer optional Example: `60000` The file_delete_delay_ms specifies the time (in ms) to wait before deleting a file from the filesystem. `flush_messages` integer optional Example: `9223372036854776000` The flush_messages specifies the number of messages to accumulate on a log partition before messages are flushed to disk. `flush_ms` integer optional Example: `9223372036854776000` The flush_ms specifies the maximum time (in ms) that a message is kept in memory before being flushed to disk. `index_interval_bytes` integer optional Example: `4096` The index_interval_bytes specifies the number of bytes between entries being added into te offset index. `max_compaction_lag_ms` integer optional Example: `9223372036854776000` The max_compaction_lag_ms specifies the maximum amount of time (in ms) that a message will remain uncompacted. This is only applicable if the logs are have compaction enabled. `max_message_bytes` integer optional Example: `1048588` The max_messages_bytes specifies the largest record batch size (in bytes) that can be sent to the server. This is calculated after compression if compression is enabled. `message_down_conversion_enable` boolean optional Example: `true` The message_down_conversion_enable specifies whether down-conversion of message formats is enabled to satisfy consumer requests. When 'false', the broker will not perform conversion for consumers expecting older message formats. The broker will respond with an `UNSUPPORTED_VERSION` error for consume requests from these older clients. `message_format_version` string (enum) optional Example: `3.0-IV1` The message_format_version specifies the message format version used by the broker to append messages to the logs. The value of this setting is assumed to be 3.0-IV1 if the broker protocol version is 3.0 or higher. By setting a particular message format version, all existing messages on disk must be smaller or equal to the specified version. `message_timestamp_type` string, one of: create_time, log_append_time optional Example: `create_time` The message_timestamp_type specifies whether to use the message create time or log append time as the timestamp on a message. `min_cleanable_dirty_ratio` number (float) optional Example: `0.5` The min_cleanable_dirty_ratio specifies the frequency of log compaction (if enabled) in relation to duplicates present in the logs. For example, at 0.5, at most 50% of the log could be duplicates before compaction would begin. `min_compaction_lag_ms` integer optional Example: `0` The min_compaction_lag_ms specifies the minimum time (in ms) that a message will remain uncompacted in the log. Only relevant if log compaction is enabled. `min_insync_replicas` integer optional Example: `1` The min_insync_replicas specifies the number of replicas that must ACK a write for the write to be considered successful. `preallocate` boolean optional Example: `false` The preallocate specifies whether a file should be preallocated on disk when creating a new log segment. `retention_bytes` integer optional Example: `1000000` The retention_bytes specifies the maximum size of the log (in bytes) before deleting messages. -1 indicates that there is no limit. `retention_ms` integer optional Example: `604800000` The retention_ms specifies the maximum amount of time (in ms) to keep a message before deleting it. `segment_bytes` integer optional Example: `209715200` The segment_bytes specifies the maximum size of a single log file (in bytes). `segment_jitter_ms` integer optional Example: `0` The segment_jitter_ms specifies the maximum random jitter subtracted from the scheduled segment roll time to avoid thundering herds of segment rolling. `segment_ms` integer optional Example: `604800000` The segment_ms specifies the period of time after which the log will be forced to roll if the segment file isn't full. This ensures that retention can delete or compact old data. `name` string optional Example: `events` The name of the Kafka topic. `partitions` array of object optional **Show child properties** `consumer_groups` array of object optional Nullable **Show child properties** `group_name` string optional Example: `consumer` Name of the consumer group. `offset` integer optional Example: `0` The current offset of the consumer group. `earliest_offset` integer optional Example: `0` The earliest consumer offset amongst consumer groups. `id` integer optional Example: `1` An identifier for the partition. `in_sync_replicas` integer optional Example: `3` The number of nodes that are in-sync (have the latest data) for the given partition `size` integer optional Example: `4096` Size of the topic partition in bytes. `replication_factor` integer optional Example: `2` The number of nodes to replicate data across the cluster. `state` string, one of: active, configuring, deleting, unknown optional Example: `active` The state of the Kafka topic. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "topic": { "config": { "cleanup_policy": "delete", "compression_type": "producer", "delete_retention_ms": 86400000, "file_delete_delay_ms": 60000, "flush_messages": "9223372036854776000", "flush_ms": "9223372036854776000", "index_interval_bytes": 4096, "max_compaction_lag_ms": "9223372036854776000", "max_message_bytes": 1048588, "message_down_conversion_enable": true, "message_format_version": "3.0-IV1", "message_timestamp_difference_max_ms": "9223372036854776000", "message_timestamp_type": "create_time", "min_cleanable_dirty_ratio": 0.5, "min_compaction_lag_ms": 0, "min_insync_replicas": 1, "preallocate": false, "retention_bytes": -1, "retention_ms": 604800000, "segment_bytes": 209715200, "segment_index_bytes": 10485760, "segment_jitter_ms": 0, "segment_ms": 604800000 }, "name": "customer-events", "partitions": [ { "consumer_groups": [ { "name": "consumer-group-1", "offset": 0 }, { "name": "consumer-group-2", "offset": 1 } ], "earliest_offset": 0, "id": 0, "in_sync_replicas": 3, "size": 4096 }, { "consumer_groups": null, "earliest_offset": 0, "id": 1, "in_sync_replicas": 3, "size": 4096 } ], "replication_factor": 3, "state": "active" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Topic for a Kafka Cluster `/v2/databases/{database_cluster_uuid}/topics/{topic_name}` To delete a single topic within a Kafka cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/topics/$TOPIC_NAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `topic_name` string required Example: `customer-events` The name used to identify the Kafka topic. ##### Request: `/v2/databases/{database_cluster_uuid}/topics/{topic_name}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics/customer-events" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() topicName := "events" _, err := client.Databases.DeleteTopic(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", topicName) } ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Logsinks for a Database Cluster `/v2/databases/{database_cluster_uuid}/logsink` To list logsinks for a database cluster, send a GET request to `/v2/databases/$DATABASE_ID/logsink`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/logsink` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink" ``` #### Responses **200** A JSON object with a key of sinks. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `sinks` array of object optional **Show child properties** `sink_id` string optional Example: `dfcc9f57d86bf58e321c2c6c31c7a971be244ac7` A unique identifier for Logsink `sink_name` string optional Example: `prod-logsink` The name of the Logsink `sink_type` string, one of: rsyslog, elasticsearch, opensearch optional Example: `rsyslog` `config` anyOf optional Example: `{"config":{"format":"rfc5424","port":514,"server":"192.168.0.1","tls":false}}` One of: **Rsyslog Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `cert` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` (PEM format) client cert to use `format` string, one of: rfc5424, rfc3164, custom required Example: `rfc5424` Message format used by the server, this can be either rfc3164 (the old BSD style message format), `rfc5424` (current syslog message format) or custom `key` string optional Example: `-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n` (PEM format) client key if the server requires client authentication `logline` string optional Example: `<%pri%>%timestamp:::date-rfc3339% %HOSTNAME% %app-name% %msg%` Conditional (required if `format` == `custom`). Syslog log line template for a custom format, supporting limited rsyslog style templating (using `%tag%`). Supported tags are: `HOSTNAME`, `app-name`, `msg`, `msgid`, `pri`, `procid`, `structured-data`, `timestamp` and `timestamp:::date-rfc3339`. * * * **Datadog Integration Example for Non-Mongo clusters**: ``` DD_KEY <%pri%>1 %timestamp:::date-rfc3339% %HOSTNAME%.DB_NAME %app-name% - - - %msg% ``` - Replace `DD_KEY` with your actual Datadog API key. - Replace `DB_NAME` with the actual name of your database cluster. - Configure the Server: - US Region: Use `intake.logs.datadoghq.com` - EU Region: Use `tcp-intake.logs.datadoghq.eu` - Configure the Port: - US Region: Use port `10516` - EU Region: Use port `443` - Enable TLS: - Ensure the TLS checkbox is enabled. - Note: This configuration applies to **non-Mongo clusters only**. For **Mongo clusters**, use the `datadog_logsink` integration instead. `port` integer required Example: `514` The internal port on which the rsyslog server is listening `sd` string optional Example: `TOKEN tag="LiteralValue"` content of the structured data block of rfc5424 message `server` string required Example: `192.168.0.1` DNS name or IPv4 address of the rsyslog server `tls` boolean required Example: `false` Use TLS (as the messages are not filtered and may contain sensitive information, it is highly recommended to set this to true if the remote server supports it) **Elasticsearch Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `index_days_max` integer optional Example: `5` Maximum number of days of logs to keep `index_prefix` string required Example: `elastic-logs` Elasticsearch index prefix `timeout` number (float) optional Example: `10` Elasticsearch request timeout limit `url` string required Example: `https://user:passwd@192.168.0.1:9200` Elasticsearch connection URL **Opensearch Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `index_days_max` integer optional Example: `5` Maximum number of days of logs to keep `index_prefix` string required Example: `opensearch-logs` Opensearch index prefix `timeout` number (float) optional Example: `10` Opensearch request timeout limit `url` string required Example: `https://user:passwd@192.168.0.1:9200` Opensearch connection URL **Datadog Logsink** `datadog_api_key` string required Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` Datadog API key `site` string required Example: `http-intake.logs.datadoghq.com` Datadog connection URL **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "sinks": [ { "config": { "format": "rfc5424", "port": 514, "server": "192.168.0.1", "tls": false }, "sink_id": "799990b6-d551-454b-9ffe-b8618e9d6272", "sink_name": "logs-sink-1", "sink_type": "rsyslog" }, { "config": { "format": "rfc3164", "port": 514, "server": "192.168.10.1", "tls": false }, "sink_id": "d6e95157-5f58-48d0-9023-8cfb409d102a", "sink_name": "logs-sink-2", "sink_type": "rsyslog" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Logsink for a Database Cluster `/v2/databases/{database_cluster_uuid}/logsink` To create logsink for a database cluster, send a POST request to `/v2/databases/$DATABASE_ID/logsink`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `sink_name` string optional Example: `prod-logsink` The name of the Logsink `sink_type` string, one of: rsyslog, elasticsearch, opensearch, datadog optional Example: `rsyslog` Type of logsink integration. - Use `datadog` for Datadog integration **only with MongoDB clusters**. - For non-MongoDB clusters, use `rsyslog` for general syslog forwarding. - Other supported types include `elasticsearch` and `opensearch`. More details about the configuration can be found in the `config` property. `config` anyOf optional One of: **Rsyslog Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `cert` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` (PEM format) client cert to use `format` string, one of: rfc5424, rfc3164, custom required Example: `rfc5424` Message format used by the server, this can be either rfc3164 (the old BSD style message format), `rfc5424` (current syslog message format) or custom `key` string optional Example: `-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n` (PEM format) client key if the server requires client authentication `logline` string optional Example: `<%pri%>%timestamp:::date-rfc3339% %HOSTNAME% %app-name% %msg%` Conditional (required if `format` == `custom`). Syslog log line template for a custom format, supporting limited rsyslog style templating (using `%tag%`). Supported tags are: `HOSTNAME`, `app-name`, `msg`, `msgid`, `pri`, `procid`, `structured-data`, `timestamp` and `timestamp:::date-rfc3339`. * * * **Datadog Integration Example for Non-Mongo clusters**: ``` DD_KEY <%pri%>1 %timestamp:::date-rfc3339% %HOSTNAME%.DB_NAME %app-name% - - - %msg% ``` - Replace `DD_KEY` with your actual Datadog API key. - Replace `DB_NAME` with the actual name of your database cluster. - Configure the Server: - US Region: Use `intake.logs.datadoghq.com` - EU Region: Use `tcp-intake.logs.datadoghq.eu` - Configure the Port: - US Region: Use port `10516` - EU Region: Use port `443` - Enable TLS: - Ensure the TLS checkbox is enabled. - Note: This configuration applies to **non-Mongo clusters only**. For **Mongo clusters**, use the `datadog_logsink` integration instead. `port` integer required Example: `514` The internal port on which the rsyslog server is listening `sd` string optional Example: `TOKEN tag="LiteralValue"` content of the structured data block of rfc5424 message `server` string required Example: `192.168.0.1` DNS name or IPv4 address of the rsyslog server `tls` boolean required Example: `false` Use TLS (as the messages are not filtered and may contain sensitive information, it is highly recommended to set this to true if the remote server supports it) **Elasticsearch Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `index_days_max` integer optional Example: `5` Maximum number of days of logs to keep `index_prefix` string required Example: `elastic-logs` Elasticsearch index prefix `timeout` number (float) optional Example: `10` Elasticsearch request timeout limit `url` string required Example: `https://user:passwd@192.168.0.1:9200` Elasticsearch connection URL **Opensearch Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `index_days_max` integer optional Example: `5` Maximum number of days of logs to keep `index_prefix` string required Example: `opensearch-logs` Opensearch index prefix `timeout` number (float) optional Example: `10` Opensearch request timeout limit `url` string required Example: `https://user:passwd@192.168.0.1:9200` Opensearch connection URL **Datadog Logsink** `datadog_api_key` string required Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` Datadog API key `site` string required Example: `http-intake.logs.datadoghq.com` Datadog connection URL ##### Request: `/v2/databases/{database_cluster_uuid}/logsink` ### Payload Content type `application/json` Example ```json { "config": { "datadog_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "site": "http-intake.logs.datadoghq.com" }, "sink_name": "logs-sink", "sink_type": "datadog" } ``` ```json { "config": { "format": "rfc5424", "port": 514, "server": "192.168.0.1", "tls": false }, "sink_name": "logs-sink", "sink_type": "rsyslog" } ``` ```json { "config": { "index_days_max": 5, "index_prefix": "elasticsearch-logs", "url": "https://user:passwd@192.168.0.1:25060" }, "sink_name": "logs-sink", "sink_type": "elasticsearch" } ``` ```json { "config": { "index_days_max": 5, "index_prefix": "opensearch-logs", "url": "https://user:passwd@192.168.0.1:25060" }, "sink_name": "logs-sink", "sink_type": "opensearch" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"sink_name": "logsink", "sink_type": "rsyslog", "config": {"server": "192.168.10.1", "port": 514, "tls": false, "format": "rfc5424"}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink" ``` #### Responses **201** A JSON object with a key of sink. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `sink` object optional **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **201** Example ```json { "sink": { "config": { "datadog_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "site": "http-intake.logs.datadoghq.com" }, "sink_id": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7", "sink_name": "logs-sink", "sink_type": "rsyslog" } } ``` ```json { "sink": { "config": { "format": "rfc5424", "port": 514, "server": "192.168.0.1", "tls": false }, "sink_id": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7", "sink_name": "logs-sink", "sink_type": "rsyslog" } } ``` ```json { "sink": { "config": { "index_days_max": 5, "index_prefix": "elasticsearch-logs", "url": "https://user:passwd@192.168.0.1:25060" }, "sink_id": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7", "sink_name": "logs-sink", "sink_type": "elasticsearch" } } ``` ```json { "sink": { "config": { "index_days_max": 5, "index_prefix": "opensearch-logs", "url": "https://user:passwd@192.168.0.1:25060" }, "sink_id": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7", "sink_name": "logs-sink", "sink_type": "opensearch" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get Logsink for a Database Cluster `/v2/databases/{database_cluster_uuid}/logsink/{logsink_id}` To get a logsink for a database cluster, send a GET request to `/v2/databases/$DATABASE_ID/logsink/$LOGSINK_ID`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `logsink_id` string required Example: `50484ec3-19d6-4cd3-b56f-3b0381c289a6` A unique identifier for a logsink of a database cluster ##### Request: `/v2/databases/{database_cluster_uuid}/logsink/{logsink_id}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink/77b28fc8-19ff-11eb-8c9c-c68e24557488" ``` #### Responses **200** A JSON object with logsink properties. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `sink_id` string optional Example: `dfcc9f57d86bf58e321c2c6c31c7a971be244ac7` A unique identifier for Logsink `sink_name` string optional Example: `prod-logsink` The name of the Logsink `sink_type` string, one of: rsyslog, elasticsearch, opensearch optional Example: `rsyslog` `config` anyOf optional Example: `{"config":{"format":"rfc5424","port":514,"server":"192.168.0.1","tls":false}}` One of: **Rsyslog Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `cert` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` (PEM format) client cert to use `format` string, one of: rfc5424, rfc3164, custom required Example: `rfc5424` Message format used by the server, this can be either rfc3164 (the old BSD style message format), `rfc5424` (current syslog message format) or custom `key` string optional Example: `-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n` (PEM format) client key if the server requires client authentication `logline` string optional Example: `<%pri%>%timestamp:::date-rfc3339% %HOSTNAME% %app-name% %msg%` Conditional (required if `format` == `custom`). Syslog log line template for a custom format, supporting limited rsyslog style templating (using `%tag%`). Supported tags are: `HOSTNAME`, `app-name`, `msg`, `msgid`, `pri`, `procid`, `structured-data`, `timestamp` and `timestamp:::date-rfc3339`. * * * **Datadog Integration Example for Non-Mongo clusters**: ``` DD_KEY <%pri%>1 %timestamp:::date-rfc3339% %HOSTNAME%.DB_NAME %app-name% - - - %msg% ``` - Replace `DD_KEY` with your actual Datadog API key. - Replace `DB_NAME` with the actual name of your database cluster. - Configure the Server: - US Region: Use `intake.logs.datadoghq.com` - EU Region: Use `tcp-intake.logs.datadoghq.eu` - Configure the Port: - US Region: Use port `10516` - EU Region: Use port `443` - Enable TLS: - Ensure the TLS checkbox is enabled. - Note: This configuration applies to **non-Mongo clusters only**. For **Mongo clusters**, use the `datadog_logsink` integration instead. `port` integer required Example: `514` The internal port on which the rsyslog server is listening `sd` string optional Example: `TOKEN tag="LiteralValue"` content of the structured data block of rfc5424 message `server` string required Example: `192.168.0.1` DNS name or IPv4 address of the rsyslog server `tls` boolean required Example: `false` Use TLS (as the messages are not filtered and may contain sensitive information, it is highly recommended to set this to true if the remote server supports it) **Elasticsearch Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `index_days_max` integer optional Example: `5` Maximum number of days of logs to keep `index_prefix` string required Example: `elastic-logs` Elasticsearch index prefix `timeout` number (float) optional Example: `10` Elasticsearch request timeout limit `url` string required Example: `https://user:passwd@192.168.0.1:9200` Elasticsearch connection URL **Opensearch Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `index_days_max` integer optional Example: `5` Maximum number of days of logs to keep `index_prefix` string required Example: `opensearch-logs` Opensearch index prefix `timeout` number (float) optional Example: `10` Opensearch request timeout limit `url` string required Example: `https://user:passwd@192.168.0.1:9200` Opensearch connection URL **Datadog Logsink** `datadog_api_key` string required Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` Datadog API key `site` string required Example: `http-intake.logs.datadoghq.com` Datadog connection URL **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** Example ```json { "config": { "format": "rfc5424", "port": 514, "server": "192.168.0.1", "tls": false }, "sink_id": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7", "sink_name": "logs-sink", "sink_type": "rsyslog" } ``` ```json { "config": { "index_days_max": 5, "index_prefix": "elasticsearch-logs", "url": "https://user:passwd@192.168.0.1:25060" }, "sink_id": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7", "sink_name": "logs-sink", "sink_type": "elasticsearch" } ``` ```json { "config": { "index_days_max": 5, "index_prefix": "opensearch-logs", "url": "https://user:passwd@192.168.0.1:25060" }, "sink_id": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7", "sink_name": "logs-sink", "sink_type": "opensearch" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Logsink for a Database Cluster `/v2/databases/{database_cluster_uuid}/logsink/{logsink_id}` To update a logsink for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/logsink/$LOGSINK_ID`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `logsink_id` string required Example: `50484ec3-19d6-4cd3-b56f-3b0381c289a6` A unique identifier for a logsink of a database cluster #### Request Body: `application/json` `config` anyOf required One of: **Rsyslog Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `cert` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` (PEM format) client cert to use `format` string, one of: rfc5424, rfc3164, custom required Example: `rfc5424` Message format used by the server, this can be either rfc3164 (the old BSD style message format), `rfc5424` (current syslog message format) or custom `key` string optional Example: `-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n` (PEM format) client key if the server requires client authentication `logline` string optional Example: `<%pri%>%timestamp:::date-rfc3339% %HOSTNAME% %app-name% %msg%` Conditional (required if `format` == `custom`). Syslog log line template for a custom format, supporting limited rsyslog style templating (using `%tag%`). Supported tags are: `HOSTNAME`, `app-name`, `msg`, `msgid`, `pri`, `procid`, `structured-data`, `timestamp` and `timestamp:::date-rfc3339`. * * * **Datadog Integration Example for Non-Mongo clusters**: ``` DD_KEY <%pri%>1 %timestamp:::date-rfc3339% %HOSTNAME%.DB_NAME %app-name% - - - %msg% ``` - Replace `DD_KEY` with your actual Datadog API key. - Replace `DB_NAME` with the actual name of your database cluster. - Configure the Server: - US Region: Use `intake.logs.datadoghq.com` - EU Region: Use `tcp-intake.logs.datadoghq.eu` - Configure the Port: - US Region: Use port `10516` - EU Region: Use port `443` - Enable TLS: - Ensure the TLS checkbox is enabled. - Note: This configuration applies to **non-Mongo clusters only**. For **Mongo clusters**, use the `datadog_logsink` integration instead. `port` integer required Example: `514` The internal port on which the rsyslog server is listening `sd` string optional Example: `TOKEN tag="LiteralValue"` content of the structured data block of rfc5424 message `server` string required Example: `192.168.0.1` DNS name or IPv4 address of the rsyslog server `tls` boolean required Example: `false` Use TLS (as the messages are not filtered and may contain sensitive information, it is highly recommended to set this to true if the remote server supports it) **Elasticsearch Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `index_days_max` integer optional Example: `5` Maximum number of days of logs to keep `index_prefix` string required Example: `elastic-logs` Elasticsearch index prefix `timeout` number (float) optional Example: `10` Elasticsearch request timeout limit `url` string required Example: `https://user:passwd@192.168.0.1:9200` Elasticsearch connection URL **Opensearch Logsink** `ca` string optional Example: `-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n` PEM encoded CA certificate `index_days_max` integer optional Example: `5` Maximum number of days of logs to keep `index_prefix` string required Example: `opensearch-logs` Opensearch index prefix `timeout` number (float) optional Example: `10` Opensearch request timeout limit `url` string required Example: `https://user:passwd@192.168.0.1:9200` Opensearch connection URL **Datadog Logsink** `datadog_api_key` string required Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` Datadog API key `site` string required Example: `http-intake.logs.datadoghq.com` Datadog connection URL ##### Request: `/v2/databases/{database_cluster_uuid}/logsink/{logsink_id}` ### Payload Content type `application/json` ```json { "config": { "format": "rfc3164", "port": 514, "server": "192.168.0.1", "tls": false } } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"config": {"server": "192.168.1.1", "port": 514, "tls": false, "format": "rfc3164"}}' \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink/77b28fc8-19ff-11eb-8c9c-c68e24557488" ``` #### Responses **200** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Logsink for a Database Cluster `/v2/databases/{database_cluster_uuid}/logsink/{logsink_id}` To delete a logsink for a database cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/logsink/$LOGSINK_ID`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `logsink_id` string required Example: `50484ec3-19d6-4cd3-b56f-3b0381c289a6` A unique identifier for a logsink of a database cluster ##### Request: `/v2/databases/{database_cluster_uuid}/logsink/{logsink_id}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink/77b28fc8-19ff-11eb-8c9c-c68e24557488" ``` #### Responses **200** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Schemas for Kafka Cluster `/v2/databases/{database_cluster_uuid}/schema-registry` To list all schemas for a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/schema-registry` ### cURL ```bash curl -X GET \ -H "Authorization: Bearer $API_TOKEN" \ "https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/schema-registry" ``` #### Responses **200** A JSON object with a key of subjects. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `subjects` array of object optional **Show child properties** `schema` string optional The schema definition in the specified format. `schema_id` integer optional Example: `12345` The id for schema. `schema_type` string, one of: AVRO, JSON, PROTOBUF optional Example: `AVRO` The type of the schema. `subject_name` string optional Example: `customer-schema` The name of the schema subject. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "subjects": [ { "schema": "{\n \"type\": \"record\",\n \"name\": \"Customer\",\n \"fields\": [ \n {\"name\": \"id\", \"type\": \"int\"},\n {\"name\": \"name\", \"type\": \"string\"}\n ]\n} ", "schema_id": 12345, "schema_type": "AVRO", "subject_name": "customer-schema" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Schema Registry for Kafka Cluster `/v2/databases/{database_cluster_uuid}/schema-registry` To create a Kafka schema for a database cluster, send a POST request to `/v2/databases/$DATABASE_ID/schema-registry`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `schema` string optional The schema definition in the specified format. `schema_type` string, one of: AVRO, JSON, PROTOBUF optional Example: `AVRO` The type of the schema. `subject_name` string optional Example: `customer-schema` The name of the schema subject. ##### Request: `/v2/databases/{database_cluster_uuid}/schema-registry` ### Payload Content type `application/json` ```json { "schema": "{\n \"type\": \"record\",\n \"name\": \"Customer\",\n \"fields\": [\n {\"name\": \"id\", \"type\": \"string\"},\n {\"name\": \"name\", \"type\": \"string\"},\n {\"name\": \"email\", \"type\": \"string\"},\n {\"name\": \"created_at\", \"type\": \"long\"}\n ]\n}\n", "schema_type": "AVRO", "subject_name": "customer-schema" } ``` ### cURL ```bash curl -X POST \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "schema": "{\n \"type\": \"record\",\n \"name\": \"Customer\",\n \"fields\": [\n {\"name\": \"id\", \"type\": \"string\"},\n {\"name\": \"name\", \"type\": \"string\"},\n {\"name\": \"email\", \"type\": \"string\"},\n {\"name\": \"created_at\", \"type\": \"long\"}\n ]\n}\n", "schema_type": "AVRO", "subject_name": "customer-schema" }' \ "https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/schema-registry" ``` #### Responses **201** A JSON object. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `schema` string optional The schema definition in the specified format. `schema_id` integer optional Example: `12345` The id for schema. `schema_type` string, one of: AVRO, JSON, PROTOBUF optional Example: `AVRO` The type of the schema. `subject_name` string optional Example: `customer-schema` The name of the schema subject. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **201** ```json { "schema": "{\n \"type\": \"record\",\n \"name\": \"Customer\",\n \"fields\": [ \n {\"name\": \"id\", \"type\": \"int\"},\n {\"name\": \"name\", \"type\": \"string\"}\n ]\n} ", "schema_id": 12345, "schema_type": "AVRO", "subject_name": "customer-schema" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get a Kafka Schema by Subject Name `/v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}` To get a specific schema by subject name for a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry/$SUBJECT_NAME`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `subject_name` string required Example: `customer-schema` The name of the Kafka schema subject. ##### Request: `/v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}` ### cURL ```bash curl -X GET \ -H "Authorization: Bearer $API_TOKEN" \ "https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}" ``` #### Responses **200** A JSON object. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `schema` string optional The schema definition in the specified format. `schema_id` integer optional Example: `12345` The id for schema. `schema_type` string, one of: AVRO, JSON, PROTOBUF optional Example: `AVRO` The type of the schema. `subject_name` string optional Example: `customer-schema` The name of the schema subject. `version` string optional Example: `1` The version of the schema. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "schema": "{\n \"type\": \"record\",\n \"name\": \"Customer\",\n \"fields\": [ \n {\"name\": \"id\", \"type\": \"int\"},\n {\"name\": \"name\", \"type\": \"string\"}\n ]\n} ", "schema_id": 12345, "schema_type": "AVRO", "subject_name": "customer-schema", "version": "1" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` * * * ## DELETE Delete a Kafka Schema by Subject Name `/v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}` To delete a specific schema by subject name for a Kafka cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/schema-registry/$SUBJECT_NAME`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `subject_name` string required Example: `customer-schema` The name of the Kafka schema subject. ##### Request: `/v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}` ### cURL ```bash curl -X DELETE \ -H "Authorization: Bearer $API_TOKEN" \ "https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}" ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` * * * ## GET Get Kafka Schema by Subject Version `/v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}/versions/{version}` To get a specific schema by subject name for a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry/$SUBJECT_NAME/versions/$VERSION`. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `subject_name` string required Example: `customer-schema` The name of the Kafka schema subject. `version` string required Example: `1` The version of the Kafka schema subject. ##### Request: `/v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}/versions/{version}` ### cURL ```bash curl -X GET \ -H "Authorization: Bearer $API_TOKEN" \ "https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}/versions/{version}" ``` #### Responses **200** A JSON object. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `schema` string optional The schema definition in the specified format. `schema_id` integer optional Example: `12345` The id for schema. `schema_type` string, one of: AVRO, JSON, PROTOBUF optional Example: `AVRO` The type of the schema. `subject_name` string optional Example: `customer-schema` The name of the schema subject. `version` string optional Example: `1` The version of the schema. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "schema": "{\n \"type\": \"record\",\n \"name\": \"Customer\",\n \"fields\": [ \n {\"name\": \"id\", \"type\": \"int\"},\n {\"name\": \"name\", \"type\": \"string\"}\n ]\n} ", "schema_id": 12345, "schema_type": "AVRO", "subject_name": "customer-schema", "version": "1" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` * * * ## GET Retrieve Schema Registry Configuration for a kafka Cluster `/v2/databases/{database_cluster_uuid}/schema-registry/config` To retrieve the Schema Registry configuration for a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry/config`. The response is a JSON object with a `compatibility_level` key, which is set to an object containing any database configuration parameters. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/schema-registry/config` ### cURL ```bash curl -X GET \ -H "Authorization: Bearer $API_TOKEN" \ "https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/schema-registry/config" ``` #### Responses **200** A JSON object with a key of compatibility_level. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `compatibility_level` string (enum) required The compatibility level of the schema registry. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "compatibility_level": "BACKWARD" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Schema Registry Configuration for a kafka Cluster `/v2/databases/{database_cluster_uuid}/schema-registry/config` To update the Schema Registry configuration for a Kafka cluster, send a PUT request to `/v2/databases/$DATABASE_ID/schema-registry/config`. The response is a JSON object with a `compatibility_level` key, which is set to an object containing any database configuration parameters. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. #### Request Body: `application/json` `compatibility_level` string (enum) required The compatibility level of the schema registry. ##### Request: `/v2/databases/{database_cluster_uuid}/schema-registry/config` ### Payload Content type `application/json` ```json { "compatibility_level": "BACKWARD" } ``` ### cURL ```bash curl -X PUT \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "compatibility_level": "BACKWARD" }' \ "https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/schema-registry/config" ``` #### Responses **200** A JSON object with a key of compatibility_level. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `compatibility_level` string (enum) required The compatibility level of the schema registry. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "compatibility_level": "BACKWARD" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Schema Registry Configuration for a Subject of kafka Cluster `/v2/databases/{database_cluster_uuid}/schema-registry/config/{subject_name}` To retrieve the Schema Registry configuration for a Subject of a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry/config/$SUBJECT_NAME`. The response is a JSON object with a `compatibility_level` key, which is set to an object containing any database configuration parameters. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `subject_name` string required Example: `customer-schema` The name of the Kafka schema subject. ##### Request: `/v2/databases/{database_cluster_uuid}/schema-registry/config/{subject_name}` ### cURL ```bash curl -X GET \ -H "Authorization: Bearer $API_TOKEN" \ "https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/schema-registry/config/{subject_name}" ``` #### Responses **200** A JSON object with a key of compatibility_level. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `compatibility_level` string (enum) required The compatibility level of the schema registry. `subject_name` string required The name of the schema subject. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "compatibility_level": "BACKWARD", "subject_name": "my-schema-subject" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Schema Registry Configuration for a Subject of kafka Cluster `/v2/databases/{database_cluster_uuid}/schema-registry/config/{subject_name}` To update the Schema Registry configuration for a Subject of a Kafka cluster, send a PUT request to `/v2/databases/$DATABASE_ID/schema-registry/config/$SUBJECT_NAME`. The response is a JSON object with a `compatibility_level` key, which is set to an object containing any database configuration parameters. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `subject_name` string required Example: `customer-schema` The name of the Kafka schema subject. #### Request Body: `application/json` `compatibility_level` string (enum) required The compatibility level of the schema registry. ##### Request: `/v2/databases/{database_cluster_uuid}/schema-registry/config/{subject_name}` ### Payload Content type `application/json` ```json { "compatibility_level": "BACKWARD" } ``` ### cURL ```bash curl -X PUT \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "compatibility_level": "BACKWARD" }' \ "https://api.digitalocean.com/v2/databases/{database_cluster_uuid}/schema-registry/config/{subject_name}" ``` #### Responses **200** A JSON object with a key of compatibility_level. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `compatibility_level` string (enum) required The compatibility level of the schema registry. `subject_name` string required The name of the schema subject. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "compatibility_level": "BACKWARD", "subject_name": "my-schema-subject" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Database Clusters' Metrics Endpoint Credentials `/v2/databases/metrics/credentials` To show the credentials for all database clusters' metrics endpoints, send a GET request to `/v2/databases/metrics/credentials`. The result will be a JSON object with a `credentials` key. ##### Request: `/v2/databases/metrics/credentials` ### cURL ```bash curl -X GET \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/metrics/credentials" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() creds, _, _ := client.Databases.GetMetricsCredentials(ctx) } ``` #### Responses **200** A JSON object with a key of credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `credentials` object optional **Show child properties** `credentials` object optional **Show child properties** `basic_auth_password` string optional Example: `password` basic authentication password for metrics HTTP endpoint `basic_auth_username` string optional Example: `username` basic authentication username for metrics HTTP endpoint **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "credentials": { "basic_auth_password": "password", "basic_auth_username": "username" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Database Clusters' Metrics Endpoint Credentials `/v2/databases/metrics/credentials` To update the credentials for all database clusters' metrics endpoints, send a PUT request to `/v2/databases/metrics/credentials`. A successful request will receive a 204 No Content status code with no body in response. #### Request Body: `application/json` `credentials` object optional **Show child properties** `basic_auth_password` string optional Example: `password` basic authentication password for metrics HTTP endpoint `basic_auth_username` string optional Example: `username` basic authentication username for metrics HTTP endpoint ##### Request: `/v2/databases/metrics/credentials` ### Payload Content type `application/json` ```json { "credentials": { "basic_auth_password": "new_password", "basic_auth_username": "new_username" } } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ -d '{"credentials": {"basic_auth_username": "new_username", "basic_auth_password": "new_password"}}'\ "https://api.digitalocean.com/v2/databases/metrics/credentials" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() _, _ = client.Databases.UpdateMetricsCredentials(ctx, &godo.DatabaseUpdateMetricsCredentialsRequest{ Credentials: &godo.DatabaseMetricsCredentials{ BasicAuthUsername: "a_new_username", BasicAuthPassword: "a_new_password", }, }) } ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Indexes for a OpenSearch Cluster `/v2/databases/{database_cluster_uuid}/indexes` To list all of a OpenSearch cluster's indexes, send a GET request to `/v2/databases/$DATABASE_ID/indexes`. The result will be a JSON object with a `indexes` key. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. ##### Request: `/v2/databases/{database_cluster_uuid}/indexes` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/indexes" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() replicas, _, err := client.Databases.ListIndexes(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) } ``` #### Responses **200** A JSON object with a key of indexes. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `indexes` array of object optional **Show child properties** `created_time` string (date-time) optional Example: `2021-01-01T00:00:00Z` The date and time the index was created. `index_name` string optional Example: `events` The name of the opensearch index. `number_of_replicas` integer optional Example: `3` The number of replicas for the index. `number_of_shards` integer optional Example: `2` The number of shards for the index. `size` integer optional Example: `208` The size of the index. `health` string, one of: unknown, green, yellow, red, red* optional Example: `green` The health of the OpenSearch index. `status` string, one of: unknown, open, close, none optional Example: `open` The status of the OpenSearch index. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **200** ```json { "indexes": [ { "created_time": "2021-01-01T00:00:00Z", "health": "green", "index_name": "sample-data", "number_of_replicas": 3, "number_of_shards": 2, "size": 208, "status": "open" }, { "created_time": "2021-01-01T00:00:00Z", "health": "green", "index_name": "logs-*", "number_of_replicas": 3, "number_of_shards": 2, "size": 208, "status": "open" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Index for OpenSearch Cluster `/v2/databases/{database_cluster_uuid}/indexes/{index_name}` To delete a single index within OpenSearch cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/indexes/$INDEX_NAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. #### Path Parameters `database_cluster_uuid` string (uuid) required Example: `9cc10173-e9ea-4176-9dbc-a4cee4c4ff30` A unique identifier for a database cluster. `index_name` string required Example: `logs-*` The name of the OpenSearch index. ##### Request: `/v2/databases/{database_cluster_uuid}/indexes/{index_name}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/indexes/sample-index" ``` ### Go ```go import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() indexName := "sampe-index" _, err := client.Databases.DeleteIndex(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", indexName) } ``` #### Responses **204** The action was successful and the response body is empty. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. ##### Response **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * Learn more: [How to Create OpenSearch Clusters](https://docs.digitalocean.com/products/databases/opensearch/how-to/create/index.html.md), [OpenSearch Pricing](https://docs.digitalocean.com/products/databases/opensearch/details/pricing/index.html.md), [How to Manage OpenSearch Users](https://docs.digitalocean.com/products/databases/opensearch/how-to/manage-users/index.html.md)