View All Products
Compute
Storage
Databases
Networking
Developer Tools
Delivery
Security
Services
Industries
Pricing
Community
Engage With Us
Linode API 4.163.0

Endpoints

Databases

Managed PostgreSQL Database View

get
https://api.linode.com/v4/databases/postgresql/instances/{instanceId}

Display information for a single, accessible Managed PostgreSQL Database.

Path Parameters

instanceId
Required
integer

The ID of the Managed PostgreSQL Database.

Request Samples

curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/databases/postgresql/instances/123

Response Samples

{
  "status": "active",
  "created": "2022-01-01T00:01:01",
  "updated": "2022-01-01T00:01:01",
  "id": 1234,
  "label": "example-db",
  "type": "g6-dedicated-2",
  "engine": "postgresql",
  "version": "13.2",
  "region": "us-east",
  "encrypted": "",
  "allow_list": [],
  "cluster_size": 3,
  "hosts": {
    "primary": "lin-0000-000-pgsql-primary.servers.linodedb.net",
    "secondary": "lin-0000-000-pgsql-primary-private.servers.linodedb.net"
  },
  "ssl_connection": true,
  "replication_type": "async",
  "port": 3306,
  "updates": {
    "frequency": "weekly",
    "duration": 3,
    "hour_of_day": 0,
    "day_of_week": 1,
    "week_of_month": ""
  },
  "replication_commit_type": "local"
}

Responses

200: Returns information for a single Managed PostgreSQL Database.

status
Filterable
string
Enum: "provisioning""active""suspending""suspended""resuming""restoring""failed""degraded""updating""backing_up"

The operating status of the Managed Database.

created
string <date-time>

When this Managed Database was created.

updated
string <date-time>

When this Managed Database was last updated.

id
integer

A unique ID that can be used to identify and reference the Managed Database.

label
Filterable
string [3 .. 32] characters

A unique, user-defined string referring to the Managed Database.

type
Filterable
string

The Linode Instance type used by the Managed Database for its nodes.

engine
Filterable
string

The Managed Database engine type.

version
Filterable
string

The Managed Database engine version.

region
Filterable
string

The Region ID for the Managed Database.

encrypted
boolean

Whether the Managed Databases is encrypted.

allow_list
array of objects

A list of IP addresses that can access the Managed Database. Each item can be a single IP address or a range in CIDR format.

By default, this is an empty array ([]), which blocks all connections (both public and private) to the Managed Database.

If 0.0.0.0/0 is a value in this list, then all IP addresses can access the Managed Database.

cluster_size
integer
Enum: "1""3"

The number of Linode Instance nodes deployed to the Managed Database.

Choosing 3 nodes creates a high availability cluster consisting of 1 primary node and 2 replica nodes.

hosts
object

The primary and secondary hosts for the Managed Database. These are assigned after provisioning is complete.

primary
Nullable
string

The primary host for the Managed Database.

secondary
Nullable
string

The secondary/private network host for the Managed Database.

A private network host and a private IP can only be used to access a Database Cluster from Linodes in the same data center and will not incur transfer costs.

Note: The secondary hostname is publicly viewable and accessible.

ssl_connection
boolean

Whether to require SSL credentials to establish a connection to the Managed Database.

Use the Managed PostgreSQL Database Credentials View (GET /databases/postgresql/instances/{instanceId}/credentials) command for access information.

replication_type
string
Enum: "none""asynch"

The replication method used for the Managed Database.

Defaults to none for a single cluster and asynch for a high availability cluster.

Must be none for a single node cluster.

Must be asynch for a high availability cluster.

port
integer

The access port for this Managed Database.

updates
object

Configuration settings for automated patch update maintenance for the Managed Database.

frequency
string
Enum: "weekly""monthly"

Whether maintenance occurs on a weekly or monthly basis.

duration
integer

The maximum maintenance window time in hours.

hour_of_day
integer

The hour to begin maintenance based in UTC time.

day_of_week
integer

The day to perform maintenance. 1=Monday, 2=Tuesday, etc.

week_of_month
Nullable
integer

The week of the month to perform monthly frequency updates. Defaults to null.

  • Required for monthly frequency updates.

  • Must be null for weekly frequency updates.

replication_commit_type
string
Enum: "on""local""remote_write""remote_apply""off"

The synchronization level of the replicating server.

Must be local or off for the asynch replication type.

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.

Managed PostgreSQL Database Update

put
https://api.linode.com/v4/databases/postgresql/instances/{instanceId}

Update a Managed PostgreSQL Database.

Requires read_write access to the Database.

The Database must have an active status to perform this command.

Updating addresses in the allow_list overwrites any existing addresses.

  • IP addresses and ranges in this list can access the Managed Database. All other sources are blocked.

  • If 0.0.0.0/0 is a value in this list, then all IP addresses can access the Managed Database.

  • Entering an empty array ([]) blocks all connections (both public and private) to the Managed Database.

  • Note: Updates to the allow_list may take a short period of time to complete, making this command inappropriate for rapid successive updates to this property.

All Managed Databases include automatic patch updates, which apply security patches and updates to the underlying operating system of the Managed PostgreSQL Database. The maintenance window for these updates is configured with the Managed Database's updates property.

  • If your database cluster is configured with a single node, you will experience downtime during this maintenance window when any updates occur. It's recommended that you adjust this window to match a time that will be the least disruptive for your application and users. You may also want to consider upgrading to a high availability plan to avoid any downtime due to maintenance.

  • The database software is not updated automatically. To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then migrate your databases from the original Managed Database cluster to the new one.

Path Parameters

instanceId
Required
integer

The ID of the Managed PostgreSQL Database.

Request Body Schema

allow_list
array

A list of IP addresses that can access the Managed Database. Each item can be a single IP address or a range in CIDR format.

By default, this is an empty array ([]), which blocks all connections (both public and private) to the Managed Database.

If 0.0.0.0/0 is a value in this list, then all IP addresses can access the Managed Database.

label
Filterable
string [3 .. 32] characters

A unique, user-defined string referring to the Managed Database.

updates
object

Configuration settings for automated patch update maintenance for the Managed Database.

frequency
string
Enum: "weekly""monthly"

Whether maintenance occurs on a weekly or monthly basis.

duration
integer

The maximum maintenance window time in hours.

hour_of_day
integer

The hour to begin maintenance based in UTC time.

day_of_week
integer

The day to perform maintenance. 1=Monday, 2=Tuesday, etc.

week_of_month
Nullable
integer

The week of the month to perform monthly frequency updates. Defaults to null.

  • Required for monthly frequency updates.

  • Must be null for weekly frequency updates.

Request Samples

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X PUT -d '{
        "label": "example-db",
        "allow_list": [
          "203.0.113.1",
          "192.0.1.0/24"
        ],
        "updates" = {
          "frequency": "monthly",
          "duration": 3,
          "hour_of_day": 12,
          "day_of_week": 4,
          "week_of_month": 3,
        }
    }' \
    https://api.linode.com/v4/databases/postgresql/instances/123

Response Samples

{
  "id": 1234,
  "label": "example-db",
  "status": "active",
  "type": "g6-dedicated-2",
  "engine": "postgresql",
  "version": "13.2",
  "region": "us-east",
  "encrypted": "",
  "allow_list": [],
  "cluster_size": 3,
  "hosts": {
    "primary": "lin-0000-000-pgsql-primary.servers.linodedb.net",
    "secondary": "lin-0000-000-pgsql-primary-private.servers.linodedb.net"
  },
  "ssl_connection": true,
  "replication_type": "async",
  "port": 3306,
  "created": "2022-01-01T00:01:01",
  "updated": "2022-01-01T00:01:01",
  "updates": {
    "frequency": "weekly",
    "duration": 3,
    "hour_of_day": 0,
    "day_of_week": 1,
    "week_of_month": ""
  },
  "replication_commit_type": "local"
}

Responses

200: Managed Database updated successfully.

label
Filterable
string [3 .. 32] characters

A unique, user-defined string referring to the Managed Database.

allow_list
array of objects

A list of IP addresses that can access the Managed Database. Each item can be a single IP address or a range in CIDR format.

By default, this is an empty array ([]), which blocks all connections (both public and private) to the Managed Database.

If 0.0.0.0/0 is a value in this list, then all IP addresses can access the Managed Database.

updates
object

Configuration settings for automated patch update maintenance for the Managed Database.

frequency
string
Enum: "weekly""monthly"

Whether maintenance occurs on a weekly or monthly basis.

duration
integer

The maximum maintenance window time in hours.

hour_of_day
integer

The hour to begin maintenance based in UTC time.

day_of_week
integer

The day to perform maintenance. 1=Monday, 2=Tuesday, etc.

week_of_month
Nullable
integer

The week of the month to perform monthly frequency updates. Defaults to null.

  • Required for monthly frequency updates.

  • Must be null for weekly frequency updates.

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.

Managed PostgreSQL Database Delete

delete
https://api.linode.com/v4/databases/postgresql/instances/{instanceId}

Remove a Managed PostgreSQL Database from your Account.

Requires read_write access to the Database.

The Database must have an active, failed, or degraded status to perform this command.

Only unrestricted Users can access this command, and have access regardless of the acting token's OAuth scopes.

Path Parameters

instanceId
Required
integer

The ID of the Managed PostgreSQL Database.

Request Samples

curl -H "Authorization: Bearer $TOKEN" \
    -X DELETE \
    https://api.linode.com/v4/databases/postgresql/instances/123

Response Samples

{}

Responses

200: Managed PostgreSQL Database successfully deleted.

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.