Databases attributes
field | type | description |
---|---|---|
id | string | unique ID |
resource_id | string | resource reference |
app_name | string | name of the linked application |
created_at | date | creation date of the database |
encryption_at_rest | boolean | is encryption at rest enabled on this database |
plan | string | name of the application plan |
status | string | status of the current database |
type_id | string | database type ID |
type_name | string | database type Name |
version_id | string | database version ID |
readable_version | string | human readable database version |
instances | array | list of all database instances |
features | array | list of all database features |
periodic_backups_enabled | boolean | true if periodic backups are enabled |
periodic_backups_scheduled_at | array | hours of the day of the periodic backup (UTC) |
Instance attributes
field | type | description |
---|---|---|
id | string | unique ID |
hostname | string | FQDN of the instance |
port | integer | instance port |
status | string | status of the current instance |
type | string | is this node a database node or a gateway |
Example object:
{
"database": {
"id": "5c599fd6f18b3202f7ab4e66",
"resource_id": "my-db-123",
"app_name": "my-app",
"created_at": "2019-02-05T15:38:14.343+01:00",
"encryption_at_rest": true,
"features": [
{
"name": "redis-rdb",
"status": "ACTIVATED"
}
],
"plan": "free",
"status": "running",
"type_id": "5bf30d1104c87f000161285a",
"type_name": "redis",
"version_id": "5bf30d1104c87f000161285b",
"instances": [
{
"id": "a7ecbaf9-7f3c-4324-bf35-975f546718c2",
"hostname": "a7ecbaf9-7f3c-4324-bf35-975f546718c2.test-db.redis.dbs.scalingo.com",
"port": 1234,
"status": "running",
"type": "db-node"
}
],
"readable_version": "3.2.9-1",
"periodic_backups_enabled": true,
"periodic_backups_scheduled_at": [0]
}
}
GET https://$DB_API_URL/api/databases/[:db_id]
Retrieve information of a specific database.
To find the database ID you must use our addon API documentation.
The ID to use correspond to the addon’s id
field.
Example request
curl -H "Accept: application/json" -H "Content-Type: application/json" \
-H "Authorization: Bearer $DB_BEARER_TOKEN" \
-X GET https://$DB_API_URL/api/databases/my-db-123
Returns 200 OK
{
"database": {
"id": "5c599fd6f18b3202f7ab4e66",
"resource_id": "my-db-123",
"app_name": "my-app",
"created_at": "2019-02-05T15:38:14.343+01:00",
"encryption_at_rest": true,
"features": [
{
"name": "redis-rdb",
"status": "ACTIVATED"
}
],
"plan": "free",
"status": "running",
"type_id": "5bf30d1104c87f000161285a",
"type_name": "redis",
"version_id": "5bf30d1104c87f000161285b",
"instances": [],
"readable_version": "3.2.9-1",
"periodic_backups_enabled": true,
"periodic_backups_scheduled_at": [0]
}
}
PATCH https://$DB_API_URL/api/databases/[:db_id]
or
PUT https://$DB_API_URL/api/databases/[:db_id]
Update database settings.
Example request
curl -H "Accept: application/json" -H "Content-Type: application/json" \
-H "Authorization: Bearer $DB_BEARER_TOKEN" \
-X PATCH https://$DB_API_URL/api/databases/my-db-123 \
-d '{
"database": {
"periodic_backups_enabled": true,
"periodic_backups_scheduled_at": 3
}
}'
Returns 200 OK
{
"database": {
"id": "5c599fd6f18b3202f7ab4e66",
"resource_id": "my-db-123",
"app_name": "my-app",
"created_at": "2019-02-05T15:38:14.343+01:00",
"encryption_at_rest": true,
"features": [
{
"name": "redis-rdb",
"status": "ACTIVATED"
}
],
"plan": "free",
"status": "running",
"type_id": "5bf30d1104c87f000161285a",
"type_name": "redis",
"version_id": "5bf30d1104c87f000161285b",
"instances": [],
"readable_version": "3.2.9-1",
"periodic_backups_enabled": true,
"periodic_backups_scheduled_at": [3]
}
}
POST https://$DB_API_URL/api/databases/[:db_id]/upgrade
Upgrade the database to the next available version.
Example request
curl -H "Accept: application/json" \
-H "Authorization: Bearer $DB_BEARER_TOKEN" \
-X POST https://$DB_API_URL/api/databases/my-db-123/upgrade
Returns 202 Accepted (Asynchronous task)
Headers:
Location
: ‘https://db-api.osc-fr1.scalingo.com/api/operations/609145e66ffbd934f6745bb4’{
"message": "Database upgrade to 12.6.0-1 is pending",
"build": 1,
"created_at": "2021-03-23T10:00:09.498+01:00",
"database_type_id": "5d0b95b801dcea2f34b18f1a",
"deleted_at": null,
"features": [
"tls"
],
"major": 12,
"minor": 6,
"patch": 0,
"release_number": 230,
"updated_at": "2021-03-23T10:00:09.498+01:00",
"warning_message": "",
"allowed_plugins": [],
"id": "6051fe19406c31aaafd31a05"
}
POST https://$DB_API_URL/api/databases/[:db_id]/pitr/restore
Restore the database data at a specific point in time. This is currently only available for PostgreSQL databases.
Example request
curl -H "Accept: application/json" -H "Content-Type: application/json" \
-H "Authorization: Bearer $DB_BEARER_TOKEN" \
-X POST https://$DB_API_URL/api/databases/my-db-123/pitr/restore \
-d '{
"restore_time": "2019-07-18T23:00:00Z"
}'
Returns 201 Created
{
"operation_id": "5c10e85ca506b701f42f92dc"
}
POST https://$DB_API_URL/api/databases/[:db_id]/action
This generic endpoint aims at wrapping direct actions over the running database. The different possible actions depend on the type of the database, as well as their parameters and return value.
Generic Parameters:
{
"action_name": "name-of-the-action",
"params": {
"option1": "value1"
}
}
Generic Success response
{
"ok": 1,
"result": {"prop1": "value1"}
}
Generic Error Response:
{
"ok": 0,
"error": "something bad happened"
}
list-databases
: List all logical databases of the database deploymentResult:
{
"ok": 1,
"result": [
{
"name": "database-name-1234",
"protected": true
}, {
"name": "custom-db",
"protected": false
}
]
}
create-database
: Create a new logical databaseParams:
{
"action_name": "create-database",
"params": {
"database_name": "custom-db"
}
}
Response:
{
"ok": 1,
"result": {
"name": "custom-db",
"protected": false
}
}
delete-database
: Delete a logical databaseParams:
{
"action_name": "delete-database",
"params": {
"database_name": "custom-db"
}
}
Response:
{
"ok": 1,
"result": null
}
reset-database
: Delete all data inside a logical databaseParams:
{
"action_name": "delete-database",
"params": {
"database_name": "custom-db"
}
}
Response:
{
"ok": 1,
"result": null
}
get-sqlmode
: Get the current SQL Mode of the databaseParams:
{
"action_name": "get-sqlmode",
"params": null
}
Response:
{
"ok": 1,
"result": "ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"
}
set-sqlmode
: Set the SQL Mode of the database{
"action_name": "set-sqlmode",
"params": "NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO"
}
Response:
{
"ok": 1,
"result": null
}
list-extensions
: List enabled PostgreSQL extensions and their version{
"action_name": "list-extensions",
"params": null
}
Response:
{
"ok": 1,
"result": [
{
"name": "plpgsql",
"version": "v1.0"
}, {
"name": "postgis",
"version": "v2.5.0"
}
]
}
pg-list-queries
: List running and idle queries of the databaseParams:
{
"action_name": "pg-list-queries"
}
Response:
{
"ok": 1,
"result": [
{
"query": "SELECT * FROM users",
"state": "active",
"username": "username_1234",
"query_start": "2020-05-10T09:00:00Z",
"pid": 2000,
"query_duration": 1000000000
}, {
// ...
}
]
}
query_duration
is in nanoseconds
pg-cancel-query
: Ask PostgreSQL to cancel: (pg_cancel_backend
method)Params:
{
"action_name": "pg-cancel-query",
"params": {
"pid": 2000
}
}
Response:
{
"ok": 1,
"result": null
}
pg-terminate-query
: Force stop a running query (pg_terminate_backend
method)Params:
{
"action_name": "pg-terminate-query",
"params": {
"pid": 2000
}
}
Response:
{
"ok": 1,
"result": null
}
pg-stat-statements-enable
: Enable the collect of stats using the extension pg-stat-statements.Params:
{
"action_name": "pg-stat-statements-enable"
}
Response:
{
"ok": 1,
"result": null
}
pg-stat-statements-reset
: Reset stats collectParams:
{
"action_name": "pg-stat-statements-reset"
}
Response:
{
"ok": 1,
"result": null
}
pg-stat-statements-list
: List current statsParams:
{
"action_name": "pg-stat-statements-list"
}
Response:
{
"ok": 1,
"result": [
{
"user_id": 1000,
"query": "SELECT * FROM users",
"calls": 24512,
"rows": 500,
"total_time": 1837.1,
"min_time": 0.2,
"max_time": 3.5,
"mean_time": 0.6,
"std_dev": 0.1
}, {
// ...
}
]
}
list-databases
: List all logical databases of the database deploymentResult:
{
"ok": 1,
"result": [
{
"name": "database-name-1234",
"protected": true
}, {
"name": "custom-db",
"protected": false
}
]
}
create-database
: Create a new logical databaseParams:
{
"action_name": "create-database",
"params": {
"database_name": "custom-db"
}
}
Response:
{
"ok": 1,
"result": {
"name": "custom-db",
"protected": false
}
}
delete-database
: Delete a logical databaseParams:
{
"action_name": "delete-database",
"params": {
"database_name": "custom-db"
}
}
Response:
{
"ok": 1,
"result": null
}
reset-database
: Delete all data inside a logical databaseParams:
{
"action_name": "delete-database",
"params": {
"database_name": "custom-db"
}
}
Response:
{
"ok": 1,
"result": null
}
list-retention-policies
: List existing retention policiesParams:
{
"action_name": "list-retention-policies"
}
Response:
{
"ok": 1,
"result": [
{
"name": "autogen",
"duration": "0",
"default": true
}, {
"name": "30-days",
"duration": "30d",
"default": false
}
]
}
add-retention-policy
: Create a new retention policyParams:
{
"action_name": "add-retention-policy",
"params": {
"name": "30-days",
"duration": "30d",
"default": true
}
}
Response:
{
"ok": 1,
"result": null
}
del-retention-policy
: Delete an existing retention policyParams:
{
"action_name": "del-retention-policy",
"params": {
"name": "30-days"
}
}
Response:
{
"ok": 1,
"result": null
}