1. Articles
  2. Platform as a Service
  3. Managed Databases
  4. General Guides

Articles in this section

See more

Getting Started with Cloud Databases via API

Avatar
Stephanie R.
  • Updated

Learn how to order a PostgreSQL instance of a Cloud Database service using the OVHcloud API.

Managed Databases (also called Cloud Databases) allow you to focus on building and deploying cloud applications while OVHcloud takes care of the database infrastructure and maintenance.

 

Requirements

 

Instructions

Step 1: Gather the set of required parameters

To create a database service, you will need to specify at minimum:

  • an engine, and its version (e.g. "PostgreSQL v15")
  • the plan (e.g. "business")
  • the nodes of the cluster (e.g. "2 nodes with 4 cores, 15 GiB memory, 320 GiB disk")

 

List the capabilities

The capabilities endpoint lists the allowed values for the engine, plan, and flavor the service knows about.

GET /cloud/project/{serviceName}/database/capabilities

The call returns an object listing allowed values for:

  • the various engines, with the various versions for each engine
  • the plans
  • and the flavors

 

Get the availability

The availability endpoint lists what combination of parameters the service allows. For example, a PostgreSQL Essential plan currently allows clusters with a single node, whereas Business services allow two nodes. You should decide what set of parameters among that list best fit your needs.

GET /cloud/project/{serviceName}/database/availability

The call returns an array listing the available set of parameters. Each entry in this array lists (among other data): an engine, a version, a plan, a flavor, a region, if it supports public or private networking, a minimum number of nodes, and a maximum number of nodes.

 

Step 2: Create a PostgreSQL database service

NOTE: By creating a cluster, you will be billed accordingly.

Use this endpoint to create a new database cluster:

POST /cloud/project/{serviceName}/database/postgresql

NOTE: All options within the _ API should be set to NULL or EMPTY except for the fields listed below.
  • description: A human-readable description of the service you wish to create.
    For security reasons, the default network configuration does not allow any incoming connections. You must authorize a suitable IP address to successfully access your database.
  • ipRestrictions: Declare the IP address blocks allowed to connect to your cluster.
    description is a human-readable label for the IP block
    ip is a string representing an IP block or network, using the syntax aaa.bbb.ccc.ddd/xy. If you want to specify a single IP address, use aaa.bbb.ccc.ddd/32.
    You can add authorize multiple IP blocks.
  • nodeslist: Specify the flavor and Region of the database you want to create. Role is not required.
  • plan: The desired plan for the service.
  • Version: The PostgreSQL version you want to use.

If you want to use public networking, no further information is needed. If you want to use private networking, you'll also want to specify:

  • networkId: The ID of the vRack you want to use.
  • subnetId: The ID of the vRack subnet you want your cluster to be attached to.

The call returns an object describing the cluster you asked for. Initially, its status property will be CREATING. Take note of the id property of the newly-created cluster for the next step.

 

Step 3: Wait for your database service to be ready

The cluster will take a few minutes to become fully usable. You can check its status using:

GET /cloud/project/{serviceName}/database/postgresql/{clusterId}

The call returns an object describing the cluster. Its status property will transition to READY when the cluster becomes available.

 

Step 4: Reset the primary user password

At this point, you don't know your cluster primary user's password.

Start by getting your new cluster’s ID:

GET /cloud/project/{serviceName}/database/postgresql

List your cluster's users with:

GET /cloud/project/{serviceName}/database/postgresql/{clusterId}/user

Note the id of your admin user. Reset its password with:

POST /cloud/project/{serviceName}/database/postgresql/{clusterId}/user/{userId}/credentials/reset

Note the new password of the user to later be able to connect to the cluster.

NOTE: That password won't ever be available later on. OVHcloud never stores users' passwords.

 

Step 5: Start using the cluster

You’ll find the cluster connection information in your Control Panel; you can now start using the cluster! More information about connecting to the PostgreSQL database is available here.

 

Go further

Configuring vRack for Public Cloud

For more information and tutorials, please see our other Cloud Databases support guides or explore the guides for other OVHcloud products and services.

Related articles