DNAnexus Documentation
APIDownloadsIndex of dx CommandsLegal
  • Overview
  • Getting Started
    • DNAnexus Essentials
    • Key Concepts
      • Projects
      • Organizations
      • Apps and Workflows
    • User Interface Quickstart
    • Command Line Quickstart
    • Developer Quickstart
    • Developer Tutorials
      • Bash
        • Bash Helpers
        • Distributed by Chr (sh)
        • Distributed by Region (sh)
        • SAMtools count
        • TensorBoard Example Web App
        • Git Dependency
        • Mkfifo and dx cat
        • Parallel by Region (sh)
        • Parallel xargs by Chr
        • Precompiled Binary
        • R Shiny Example Web App
      • Python
        • Dash Example Web App
        • Distributed by Region (py)
        • Parallel by Chr (py)
        • Parallel by Region (py)
        • Pysam
      • Web App(let) Tutorials
        • Dash Example Web App
        • TensorBoard Example Web App
      • Concurrent Computing Tutorials
        • Distributed
          • Distributed by Region (sh)
          • Distributed by Chr (sh)
          • Distributed by Region (py)
        • Parallel
          • Parallel by Chr (py)
          • Parallel by Region (py)
          • Parallel by Region (sh)
          • Parallel xargs by Chr
  • User
    • Login and Logout
    • Projects
      • Project Navigation
      • Path Resolution
    • Running Apps and Workflows
      • Running Apps and Applets
      • Running Workflows
      • Running Nextflow Pipelines
      • Running Batch Jobs
      • Monitoring Executions
      • Job Notifications
      • Job Lifecycle
      • Executions and Time Limits
      • Executions and Cost and Spending Limits
      • Smart Reuse (Job Reuse)
      • Apps and Workflows Glossary
      • Tools List
    • Cohort Browser
      • Chart Types
        • Row Chart
        • Histogram
        • Box Plot
        • List View
        • Grouped Box Plot
        • Stacked Row Chart
        • Scatter Plot
        • Kaplan-Meier Survival Curve
      • Locus Details Page
    • Using DXJupyterLab
      • DXJupyterLab Quickstart
      • Running DXJupyterLab
        • FreeSurfer in DXJupyterLab
      • Spark Cluster-Enabled DXJupyterLab
        • Exploring and Querying Datasets
      • Stata in DXJupyterLab
      • Running Older Versions of DXJupyterLab
      • DXJupyterLab Reference
    • Using Spark
      • Apollo Apps
      • Connect to Thrift
      • Example Applications
        • CSV Loader
        • SQL Runner
        • VCF Loader
      • VCF Preprocessing
    • Environment Variables
    • Objects
      • Describing Data Objects
      • Searching Data Objects
      • Visualizing Data
      • Filtering Objects and Jobs
      • Archiving Files
      • Relational Database Clusters
      • Symlinks
      • Uploading and Downloading Files
        • Small File Sets
          • dx upload
          • dx download
        • Batch
          • Upload Agent
          • Download Agent
    • Platform IDs
    • Organization Member Guide
    • Index of dx commands
  • Developer
    • Developing Portable Pipelines
      • dxCompiler
    • Cloud Workstation
    • Apps
      • Introduction to Building Apps
      • App Build Process
      • Advanced Applet Tutorial
      • Bash Apps
      • Python Apps
      • Spark Apps
        • Table Exporter
        • DX Spark Submit Utility
      • HTTPS Apps
        • Isolated Browsing for HTTPS Apps
      • Transitioning from Applets to Apps
      • Third Party and Community Apps
        • Community App Guidelines
        • Third Party App Style Guide
        • Third Party App Publishing Checklist
      • App Metadata
      • App Permissions
      • App Execution Environment
        • Connecting to Jobs
      • Dependency Management
        • Asset Build Process
        • Docker Images
        • Python package installation in Ubuntu 24.04 AEE
      • Job Identity Tokens for Access to Clouds and Third-Party Services
      • Enabling Web Application Users to Log In with DNAnexus Credentials
      • Types of Errors
    • Workflows
      • Importing Workflows
      • Introduction to Building Workflows
      • Building and Running Workflows
      • Workflow Build Process
      • Versioning and Publishing Global Workflows
      • Workflow Metadata
    • Ingesting Data
      • Molecular Expression Assay Loader
        • Common Errors
        • Example Usage
        • Example Input
      • Data Model Loader
        • Data Ingestion Key Steps
        • Ingestion Data Types
        • Data Files Used by the Data Model Loader
        • Troubleshooting
      • Dataset Extender
        • Using Dataset Extender
    • Dataset Management
      • Rebase Cohorts and Dashboards
      • Assay Dataset Merger
      • Clinical Dataset Merger
    • Apollo Datasets
      • Dataset Versions
      • Cohorts
    • Creating Custom Viewers
    • Client Libraries
      • Support for Python 3
    • Walkthroughs
      • Creating a Mixed Phenotypic Assay Dataset
      • Guide for Ingesting a Simple Four Table Dataset
    • DNAnexus API
      • Entity IDs
      • Protocols
      • Authentication
      • Regions
      • Nonces
      • Users
      • Organizations
      • OIDC Clients
      • Data Containers
        • Folders and Deletion
        • Cloning
        • Project API Methods
        • Project Permissions and Sharing
      • Data Object Lifecycle
        • Types
        • Object Details
        • Visibility
      • Data Object Metadata
        • Name
        • Properties
        • Tags
      • Data Object Classes
        • Records
        • Files
        • Databases
        • Drives
        • DBClusters
      • Running Analyses
        • I/O and Run Specifications
        • Instance Types
        • Job Input and Output
        • Applets and Entry Points
        • Apps
        • Workflows and Analyses
        • Global Workflows
        • Containers for Execution
      • Search
      • System Methods
      • Directory of API Methods
      • DNAnexus Service Limits
  • Administrator
    • Billing
    • Org Management
    • Single Sign-On
    • Audit Trail
    • Integrating with External Services
    • Portal Setup
    • GxP
      • Controlled Tool Access (allowed executables)
  • Science Corner
    • Scientific Guides
      • Somatic Small Variant and CNV Discovery Workflow Walkthrough
      • SAIGE GWAS Walkthrough
      • LocusZoom DNAnexus App
      • Human Reference Genomes
    • Using Hail to Analyze Genomic Data
    • Open-Source Tools by DNAnexus Scientists
    • Using IGV Locally with DNAnexus
  • Downloads
  • FAQs
    • EOL Documentation
      • Python 3 Support and Python 2 End of Life (EOL)
    • Automating Analysis Workflow
    • Backups of Customer Data
    • Developing Apps and Applets
    • Importing Data
    • Platform Uptime
    • Legal and Compliance
    • Sharing and Collaboration
    • Product Version Numbering
  • Release Notes
  • Technical Support
  • Legal
Powered by GitBook

Copyright 2025 DNAnexus

On this page
  • DBCluster API Specification
  • API method: /dbcluster-xxxx/describe
  • API method: /dbcluster/new
  • API method: /dbcluster-xxxx/stop
  • API method: /dbcluster-xxxx/start
  • API method: /dbcluster-xxxx/terminate

Was this helpful?

Export as PDF
  1. Developer
  2. DNAnexus API
  3. Data Object Classes

DBClusters

Learn how to access DBCluster objects via the DNAnexus API.

Last updated 1 year ago

Was this helpful?

A license is required to use the , which provides the functionality described on this page. Contact for more information.

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 can be accessed 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 the database operations. If the primary instance should fail, the second instance will be automatically promoted to primary. DBClusters can only exist within a single project, they cannot be cloned.

See the 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 A project or container ID used as a hint for finding the dbcluster.

  • defaultFields boolean (optional, default false if fields is supplied, true otherwise) 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.

  • fields mapping (optional) Include or exclude specific fields from the output. These selections override settings in defaultFields.

    • key Desired output field. See "Outputs" Section for valid values here

    • 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 page for details

  • created timestamp 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 page for details

  • modified timestamp 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 Property name

    • value string Property value

  • details mapping or array Contents of the object’s details

  • status string The status of the database cluster instances. Refer to for possible values and meaning

  • port integer The port this db should be accessed on

  • engineVersion string The engine version this cluster is running, corresponds to AWS Aurora engine versions for MySQL and PostGres . Refer to 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 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 Indicates the expiration time of data sponsorship (this field is only set if the object is currently sponsored, and if set, 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:

All of the following inputs are required:

  • name string A user friendly name for the database cluster

  • project string The project ID that the database cluster will be created in

  • engine string The database engine to use (aurora, aurora-mysql, aurora-postgresql)

  • engineVersion string The version of the database engine to use.

    Aurora (mysql) versions:

    Postgresql versions:

  • dxInstanceClass string The DNAnexus instance class for the database instances in this cluster

  • adminPassword string The password associated with the admin user for this cluster. Must be at least 8 characters in length.

    Note: The admin user will have the username 'root' for purposes of 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

  • 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 must be in the 'available' status in order 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.

Note: Once a dbcluster is terminated, the data is no longer accessible from the platform and all the data on the databases will be lost.

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

MySQL Versions
Postgres Versions
Relational Database Service
DNAnexus Sales
Relational Database Clusters
Types
Tags
Relational Databases
MySQL Versions
Postgres Versions
DBCluster Support Matrix