Database RDB APIv1beta1

Scaleway Database is a service that make your database's management easy as pie. It provides simple and reliable solutions to create and run your database, dealing with security and high availability to ensure the durability of your data.

The following sections define concepts such as Instance, Database Engine, Configuration, ACL, Failover, Configuration, Backup and Restore in Scaleway Database. These concepts will evolve all along the private beta, this documentation will be updated after each release.

A Database engine is the software component that stores and retrieves your data from a database. For example, PostgreSQL is a database engine and it implements the SQL standard. There are several database engines based on the SQL standard, only PostgreSQL for now. Database Engines have versions. Differences in major versions represents changes that can break the backward compatibility. PostgreSQL major versions 9.6, 10 and 11 are available during this phase.

A Database instance is composed of one or more computing nodes, depending on the chosen HA setting. A database replica is synchronized with a leader. Synchronous replication offers the ability to confirm that all changes intended by a transaction have been transferred and applied to one or more synchronous standby servers.

A Database instance has settings that let you tune it to better fit your needs. Available settings depend on the Database Engine and its version. Each instance setting entry has a default value that the user can override. The deletion of a setting entry will restore the entry's default value.

Access control list rules define which hosts can reach your database instance at network level. You can add, edit or delete rules from your ACLs. The initial setup of an instance allows full network access from anywhere.

We provide a solution to easily failover HA instances to its replica. If your leader is down, unresponsive for more than 700 seconds or in an unhealthy state, one of the replica is promoted as a new leader and gets the service back up. Auto healing is available and enabled by default on HA clusters.

Databases can be saved to and restored from our storage facilities, located on a different physical location than your database. Each logical database inside of a database instance is backed up and therefore restorable separately.

The region is a geographic zone of the following list:

• fr-par
• nl-ams

You can use cURL to send request to APIs, we will provide curl example for each step.

Ubuntu

?> sudo apt-get install curl

Mac OS

?> brew install curl

Go to the following link: https://console.scaleway.com/register Provide a valid e-mail address and a password.

Login to your Scaleway account and create a token from the credentials page. A secret_key and an access_key will show on your screen, the secret_key will be used as X-Auth-Token.

reference: https://www.scaleway.com/docs/generate-an-api-token/

The organization id is required to create a database. You will need to query:

curl https://account.scaleway.com/organizations -H "X-Auth-Token: $secret_key"

To get your organization id:

{
"organizations": [
  {
->    "id": "000a115d-2852-4b0a-9ce8-47f1134ba95a",
    "name": "jsnow@got.wint",
    "users": [
      {
        ...
      }
    ]
  }
]
}

reference: https://www.scaleway.com/docs/retrieve-my-organization-id-throught-the-api/

The access to Database product is limited during the private beta. Only authorized users will access to the service.

This documentation shows how to create and connect to a PostgreSQL Database using Scaleway Database product. During the private beta, PostgreSQL is available, the feature set can change and your database's might not be kept at the end of this phase. You will be notified by e-mail before any potential loss of data related with a new release.

Requirements:

You have to complete the "Setup" explained on upper sections, you are logged in scaleway and have your API Token and Organization ID. We are going to create, connect to and delete a database.

Create your database instance

• endpoint: https://api.scaleway.com/rdb/v1beta1/regions/{region}/instances

{
    "organization_id": "xxx",
    "name": "myDB",
    "engine": "PostgreSQL-10",
    "tags": ["donnerstag"],
    "is_ha_cluster": true,
    "node_type": "db-beta",
    "disable_backup": true,
    "user_name": "my_initial_user",
    "password": "thiz_is_very_s3cret"
}

Example:

?> curl -X POST -d '{}' -H "Content-Type: application/json" \
-H "X-Auth-Token: $secret_key" https://api.scaleway.com/rdb/v1beta1/regions/{region}/instances

Now you've created your database instance, you can open a connection between a database client and your database. You will need a PostgreSQL client such as psql

List instances

• endpoint: https://api.scaleway.com/rdb/v1beta1/regions/{region}/instances

example:

?> curl -X GET -H "Content-Type: application/json" \
-H "X-Auth-Token: $secret_key" https://api.scaleway.com/rdb/v1beta1/regions/{region}/instances

{
  "instances": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "myDB",
      "organization_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status": "ready",
      "engine": "PostgreSQL-10",
      "endpoint": {
        "ip": "xxx.xxx.xxx.xxx",
        "port": 22245,
        "name": null
      },
      "tags": [
        "donnerstag"
      ],
      "settings": [],
      "backup_schedule": {
        "frequency": 24,
        "retention": 7,
        "disabled": true
      },
      "is_ha_cluster": true,
      "read_replicas": [],
      "node_type": {
        "name": "db-beta",
        "stock_status": "available",
        "description": "2 GB ram; 2 cpu; 50 GB LSSD storage",
        "region": "fr-par"
      },
      "disk_size": 50000000000,
      "created_at": "2019-04-19T16:24:52.591417Z",
      "region": "fr-par"
    }
  ],
  "total_count": 1
}

Get the endpoint, port and password

• endpoint: https://api.scaleway.com/rdb/v1beta1/regions/{region}/instances/{instance_id}

?> curl -X GET -H "Content-Type: application/json" \
-H "X-Auth-Token: $secret_key" https://api.scaleway.com/rdb/v1beta1/regions/{region}/instances/{instance_id}

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "myDB",
  "organization_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ready",
  "engine": "PostgreSQL-10",
  "endpoint": {
    "ip": "xxx.xxx.xxx.xxx",
    "port": 22245,
    "name": null
  },
  "tags": [
    "donnerstag"
  ],
  "settings": [],
  "backup_schedule": {
    "frequency": 24,
    "retention": 7,
    "disabled": false
  },
  "is_ha_cluster": false,
  "read_replicas": [],
  "node_type": {
    "name": "db-beta",
    "stock_status": "available",
    "description": "2 GB ram; 2 cpu; 50 GB LSSD storage",
    "region": "fr-par"
  },
  "disk_size": 50000000000,
  "created_at": "2019-04-18T15:27:24.177854Z",
  "region": "fr-par"
}

Connect to your database with psql client

?> psql -h 192.0.2.250 -p 28991 -U my_initial_user
password:

postsql>

Congratulations! You have done your first steps on Database product !

• api token: get your api token
• organization id: get your organization id