Databases

Database services: templates, connections, queries, readers and point-in-time recovery. Each operation lists its method and path, parameters, request body, responses and an example call.

List the database templates a service can be created from.

GET/api/v1/database-templates

Authorization

AuthorizationBearer <token>

An API token, sent as Authorization: Bearer <token>. A token belongs to one organization and has the role it was created with, so it needs no X-Nebula-Organization header; if you send one, it must name the token's organization.

In: header

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/database-templates"

{  "$schema": "https://example.com/TemplatesOutputBody.json",  "templates": [    {      "engineVersion": "string",      "image": "string",      "port": 0,      "template": "postgres"    }  ]}

List the databases in a project and the variable a service connects to each through.

GET/api/v1/projects/{id}/database-connections

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/projects/string/database-connections"

{  "$schema": "https://example.com/ConnectionsOutputBody.json",  "items": [    {      "reference": "string",      "serviceId": "string",      "serviceName": "string",      "serviceSlug": "string",      "template": "postgres",      "urlKey": "string",      "variable": "string"    }  ]}

Create a database service from a template.

POST/api/v1/projects/{id}/databases

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length <= 63

stageIn?

Stage the database's first deploy in your draft change set for this environment. The database, its variables, its marker and the change-set item are written together, so nothing deploys until you apply the change set. Without it the database is only created.

template*string

Value in

"postgres"
"valkey"
"mysql"
"mongodb"

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/projects/string/databases" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "template": "postgres"  }'

{  "$schema": "https://example.com/CreatedBody.json",  "changeSet": {    "$schema": "https://example.com/ViewBody.json",    "changeSet": {      "appliedAt": "2019-08-24T14:15:22Z",      "approvalId": "string",      "createdAt": "2019-08-24T14:15:22Z",      "downtimeAccepted": true,      "environmentId": "string",      "id": "string",      "message": "string",      "reason": "string",      "source": "console",      "sourceCommit": "string",      "state": "draft"    },    "environmentId": "string",    "items": [      {        "createdAt": "2019-08-24T14:15:22Z",        "from": "string",        "id": "string",        "key": "string",        "kind": "string",        "label": "string",        "managed": true,        "processId": "string",        "secret": true,        "serviceId": "string",        "serviceSlug": "string",        "to": "string",        "toEmpty": true,        "volumeId": "string"      }    ],    "projectConfig": {      "changeSet": {        "appliedAt": "2019-08-24T14:15:22Z",        "approvalId": "string",        "createdAt": "2019-08-24T14:15:22Z",        "downtimeAccepted": true,        "environmentId": "string",        "id": "string",        "message": "string",        "reason": "string",        "source": "console",        "sourceCommit": "string",        "state": "draft"      },      "items": [        {          "createdAt": "2019-08-24T14:15:22Z",          "from": "string",          "id": "string",          "key": "string",          "kind": "string",          "label": "string",          "managed": true,          "processId": "string",          "secret": true,          "serviceId": "string",          "serviceSlug": "string",          "to": "string",          "toEmpty": true,          "volumeId": "string"        }      ],      "summary": {        "affectedServiceIds": [          "string"        ],        "needsApproval": true,        "requiresDowntime": true      }    },    "summary": {      "affectedServiceIds": [        "string"      ],      "needsApproval": true,      "requiresDowntime": true    }  },  "hint": "string",  "image": "string",  "scheduledBackups": 0,  "service": {    "createdAt": "2019-08-24T14:15:22Z",    "id": "string",    "imageRepository": "string",    "name": "string",    "projectId": "string",    "slug": "string",    "template": "postgres"  }}

Get a database service's connection details, tables and point-in-time recovery state in one environment.

GET/api/v1/services/{id}/database

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

environmentId*string

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/services/string/database?environmentId=string"

{  "$schema": "https://example.com/InfoBody.json",  "cnpgAvailable": true,  "connectionUrlMasked": "string",  "engineVersion": "string",  "image": "string",  "internalHost": "string",  "pitr": {    "enabled": true,    "window": {      "firstRecoverabilityPoint": "2019-08-24T14:15:22Z",      "lastSuccessfulBackup": "2019-08-24T14:15:22Z"    }  },  "port": 0,  "postgres": {    "autoFailover": true,    "autoFailoverAvailable": true,    "readers": [      {        "connections": 0,        "lagSeconds": 0.1,        "maxConnections": 0,        "node": "string",        "podName": "string",        "ready": true,        "state": "string",        "syncState": "string",        "walBytesPerSecond": 0.1,        "writesPerSecond": 0.1      }    ],    "writer": {      "connections": 0,      "lagSeconds": 0.1,      "maxConnections": 0,      "node": "string",      "podName": "string",      "ready": true,      "state": "string",      "syncState": "string",      "walBytesPerSecond": 0.1,      "writesPerSecond": 0.1    }  },  "tables": [    {      "name": "string",      "rows": 0,      "sizeBytes": 0    }  ],  "tablesError": "string",  "template": "postgres"}

Promote a Postgres reader to writer in one environment.

POST/api/v1/services/{id}/database/promote

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

environmentId*string

podName*string

Length1 <= length

Response Body

`application/problem+json`

curl -X POST "https://example.com/api/v1/services/string/database/promote" \  -H "Content-Type: application/json" \  -d '{    "environmentId": "string",    "podName": "string"  }'

Empty

Run a read-only query against a database service.

POST/api/v1/services/{id}/database/query

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

environmentId*string

query*string

SQL for Postgres and MySQL; a read command for Redis (for example GET key); for MongoDB a JSON document {"find": "", "filter": {}, "projection": {}, "sort": {}, "limit": 50} or {"countDocuments": "", "filter": {}}.

Length1 <= length

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/services/string/database/query" \  -H "Content-Type: application/json" \  -d '{    "environmentId": "string",    "query": "string"  }'

{  "$schema": "https://example.com/QueryOutputBody.json",  "columns": [    "string"  ],  "durationMs": 0,  "readOnly": true,  "rowCount": 0,  "rows": [    [      "string"    ]  ],  "truncated": true}

Use the request body type in TypeScript.

accessKeyId?string

A key scoped to this archive's prefix only. Required the first time, and with a new objectStoreId.

enabled*boolean

environmentId*string

objectStoreId?string

The store (endpoint, region, bucket) the archive lives in. Required the first time.

prefix?string

Where under the store's own prefix the archive lives. Defaults to //.

secretAccessKey?string

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/api/v1/services/string/pitr" \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "environmentId": "string"  }'

{  "$schema": "https://example.com/PutPITROutputBody.json",  "objectStoreId": "string",  "prefix": "string"}

Use the request body type in TypeScript.

at*string

The moment to recover to, RFC 3339. Truncated to whole seconds; not in the future.

Formatdate-time

environmentId*string

The environment whose archive to restore from; the new database is deployed there.

name?string

The new service's name. Defaults to -restored-, the moment in UTC.

Lengthlength <= 63

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/services/string/pitr/restore" \  -H "Content-Type: application/json" \  -d '{    "at": "2019-08-24T14:15:22Z",    "environmentId": "string"  }'

{  "$schema": "https://example.com/RestorePITROutputBody.json",  "environmentId": "string",  "image": "string",  "service": {    "createdAt": "2019-08-24T14:15:22Z",    "id": "string",    "imageRepository": "string",    "name": "string",    "projectId": "string",    "slug": "string",    "template": "postgres"  },  "targetTime": "2019-08-24T14:15:22Z"}

Databases

List the database templates a service can be created from.Copy Anchor Link

AuthorizationCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

List the databases in a project and the variable a service connects to each through.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Create a database service from a template.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

201application/json

defaultapplication/problem+json

Get a database service's connection details, tables and point-in-time recovery state in one environment.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Promote a Postgres reader to writer in one environment.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

204

defaultapplication/problem+json

Run a read-only query against a database service.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Turn a Postgres database's point-in-time recovery on or off in one environment.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Restore a Postgres database to a moment in time as a new database service.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

201application/json

defaultapplication/problem+json

List the database templates a service can be created from.

Authorization

Response Body

`application/json`

`application/problem+json`

List the databases in a project and the variable a service connects to each through.

Authorization

Path Parameters

Response Body

`application/json`

`application/problem+json`

Create a database service from a template.

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`

Get a database service's connection details, tables and point-in-time recovery state in one environment.

Authorization

Path Parameters

Query Parameters

Response Body

`application/json`

`application/problem+json`

Promote a Postgres reader to writer in one environment.

Authorization

Path Parameters

Request Body

Response Body

`application/problem+json`

Run a read-only query against a database service.

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`

Turn a Postgres database's point-in-time recovery on or off in one environment.

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`

Restore a Postgres database to a moment in time as a new database service.

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`