# DBClusters

{% hint style="info" %}
A license is required to use the [Relational Database Service](https://documentation.dnanexus.com/user/objects/relational-database-clusters), which provides the functionality described on this page. Contact [DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

A DBCluster object is used to represent a relational database cluster that exists in the same cloud provider and region as the project it resides within. These databases are accessible from within DNAnexus jobs at the port and endpoint properties returned when describing the DBCluster. All DBClusters are created with two instances in the cluster to provide high availability for database operations. If the primary instance fails, the second instance is automatically promoted to primary. DBClusters can only exist within a single project and cannot be cloned.

See the [Relational Database Clusters](https://documentation.dnanexus.com/user/objects/relational-database-clusters) page for more information on the DBCluster service.

## DBCluster API Specification

### API method: `/dbcluster-xxxx/describe`

#### Specification

Describes the specified DBCluster object.

#### Inputs

* `project` **string** (optional) A project or container ID used as a hint for finding the DBCluster.
* `defaultFields` **boolean** (optional) Whether to include the default set of fields in the output (the default fields are described in the "Outputs" section below). The selections are overridden by any fields explicitly named in the `fields` input.
  * Defaults to `false` if `fields` is supplied, `true` otherwise.
* `fields` **mapping** (optional) Include or exclude specific fields from the output. These selections override settings in `defaultFields`.
  * **key** — the desired output field. See "Outputs" below for valid values.
  * **value** **boolean** — whether to include the field.

#### Outputs

* `id` **string** The ID of the DBCluster.

The following fields are included by default (but can be disabled using `fields` or `defaultFields`):

* `project` **string** ID of the project or container in which the object was found.
* `class` **string** The value `dbcluster`.
* `types` **array of strings** Types associated with the object. See the [Types](https://documentation.dnanexus.com/developer/api/data-object-lifecycle/types) page for details.
* `created` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which this object was created.
* `state` **string** Always "open".
* `hidden` **boolean** Whether the object is hidden or not.
* `name` **string** The name of the database data object, matches the ID.
* `folder` **string** The project folder the DBCluster object resides in.
* `sponsored` **boolean** Whether the object is sponsored by DNAnexus.
* `tags` **array of strings** Tags associated with the object. See the [Tags](https://documentation.dnanexus.com/developer/api/introduction-to-data-object-metadata/tags) page for details.
* `modified` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which the user-provided metadata of the object was last modified.
* `createdBy` **mapping** How the object was created.
  * `user` **string** ID of the user who created the object or launched an execution which created the object.
* `properties` **mapping** Properties associated with the object.
  * **key** — the property name.
  * **value** **string** — the property value.
* `details` **mapping or array** Contents of the object's details.
* `status` **string** The status of the database cluster instances. Refer to [Relational Databases](https://documentation.dnanexus.com/user/objects/relational-database-clusters) for possible values and meaning.
* `port` **integer** The port this database should be accessed on.
* `engineVersion` **string** The engine version this cluster is running, corresponds to AWS Aurora engine versions for [MySQL Versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Updates.html) and [Postgres Versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Updates.20180305.html). Refer to [DBCluster Support Matrix](https://documentation.dnanexus.com/user/objects/relational-database-clusters#dbcluster-instance-types) for valid `dxInstanceClass`, `engine`, and `engineVersion` combinations.
* `engine` **string** The engine this cluster is running.
* `dxInstanceClass` **string** The instance class for the instances in the cluster.
* `statusAsOf` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) The timestamp the cluster's status was last updated.
* `endpoint` **string** The host endpoint to use when accessing this database from a DNAnexus job.

The following field (included by default) is available if the object is sponsored by a third party:

* `sponsoredUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Indicates the expiration time of data sponsorship. This field appears only for sponsored objects, and when present, the specified time is always in the future.

#### Errors

* ResourceNotFound
  * Thrown if the DBCluster is not found in any accessible project
* InvalidInput
  * The input is not a valid JSON object, other inputs (if supplied) are not of the correct types
* PermissionDenied
  * Thrown if user does not have VIEW access to the specified project

### API method: `/dbcluster/new`

#### Specification

Creates a new DBCluster in the specified project.

#### Inputs

* `name` **string** (required) A user-friendly name for the database cluster.
* `project` **string** (required) The project ID for creating the database cluster.
* `engine` **string** (required) The database engine to use.
  * Must be one of `"aurora"`, `"aurora-mysql"`, or `"aurora-postgresql"`.
* `engineVersion` **string** (required) The version of the database engine to use.

  Aurora (`mysql`) versions:

  [MySQL Versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Updates.html#AuroraMySQL.Updates.EngineVersions)

  PostgreSQL versions:

  [Postgres Versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Updates.20180305.html)
* `dxInstanceClass` **string** (required) The DNAnexus instance class for the database instances in this cluster.
* `adminPassword` **string** (required) The password associated with the admin user for this cluster. Must be at least 8 characters in length. The admin user has the username 'root' for connecting to the database.

#### Outputs

* `id` **string** The ID of the DBCluster.

#### Errors

* InvalidInput - Thrown for invalid combinations of `dxInstanceClass` + `engine` + `engineVersion`
* ResourceNotFound - Thrown if the projectID does not exist
* SpendingLimitExceeded
  * The `billTo` has reached its spending limit.
* OrgExpired
  * The `billTo` organization has expired.
* PermissionDenied
  * User doesn't have ADMIN access to the project or the org does not have the `dbcluster` license feature enabled
  * DBCluster pricing is required for the project's `billTo` in the project's region to create a new DBCluster
  * DBCluster pricing for instance type <> is required for the project's `billTo` in the project's region to create a new DBCluster that uses this instance type.

### API method: `/dbcluster-xxxx/stop`

#### Specification

Stops the specified DBCluster. The cluster needs 'available' status for this call to succeed.

#### Inputs

* None

#### Outputs

* `id` **string** The ID of the DBCluster.

#### Errors

* InvalidState - Thrown if the cluster is not in the available status.
* PermissionDenied - User doesn't have ADMIN access to the project or the org does not have the `dbcluster` license feature enabled

### API method: `/dbcluster-xxxx/start`

#### Specification

Restarts the specified DBCluster. Can only be called when the DBCluster is in the 'stopped' status.

#### Inputs

* None

#### Outputs

* `id` **string** The ID of the DBCluster.

#### Errors

* InvalidState - Thrown if the cluster is not in the stopped status.
* PermissionDenied - User doesn't have ADMIN access to the project or the org does not have the `dbcluster` license feature enabled

### API method: `/dbcluster-xxxx/terminate`

#### Specification

Terminates the specified DBCluster. This can only be called when the DBCluster is in the 'available' status as AWS does not allow users to terminate stopped databases.

{% hint style="info" %}
After terminating a DBCluster, its data becomes inaccessible from the platform and all database data is lost.
{% endhint %}

#### Inputs

* None

#### Outputs

* `id` **string** The ID of the DBCluster.

#### Errors

* InvalidState - Thrown if the cluster is not in the 'available' status.
* PermissionDenied - User doesn't have ADMIN access to the project or the org does not have the `dbcluster` license feature enabled