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 Databases List

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

Display all accessible Managed PostgreSQL Databases.

Query Parameters

page
integer > = 1
Default: 1

The page of a collection to return.

page_size
integer [25 .. 500]
Default: 100

The number of items to return per page.

Request Samples

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

Response Samples

{}

Responses

200: Returns a paginated list of all accessible Managed PostgreSQL Databases on your Account.

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 Create

post
https://api.linode.com/v4/databases/postgresql/instances

Provision a Managed PostgreSQL Database.

Restricted Users must have the add_databases grant to use this command.

New instances can take approximately 15 to 30 minutes to provision.

The allow_list is used to control access to the Managed Database.

  • 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.

All Managed Databases include automatic, daily backups. Up to seven backups are automatically stored for each Managed Database, providing restore points for each day of the past week.

All Managed Databases include automatic patch updates, which apply security patches and updates to the underlying operating system of the Managed PostgreSQL Database during configurable maintenance windows.

  • 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.

  • To modify update the maintenance window for a Database, use the Managed PostgreSQL Database Update (PUT /databases/postgresql/instances/{instanceId}) command.

Request Body Schema

engine
Required
string

The Managed Database engine in engine/version format.

label
Required
Filterable
string [3 .. 32] characters

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

region
Required
Filterable
string

The Region ID for the Managed Database.

type
Required
Filterable
string

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

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.

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.

encrypted
boolean

Whether the Managed Databases is encrypted.

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.

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.

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.

Request Samples

curl -H "Content-Type: application/json" \
 -H "Authorization: Bearer $TOKEN" \
 -X POST -d '{    "label": "example-db",
    "region": "us-east",
    "type": "g6-dedicated-2",
    "cluster_size": 3,
    "engine": "postgresql/13.2",
    "encrypted": false,
    "ssl_connection": false,
    "replication_type": "asynch",
    "replication_commit_type": "local",
    "allow_list": [
      "203.0.113.1",
      "192.0.1.0/24"
    ]
}' \
 https://api.linode.com/v4/databases/postgresql/instances

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: A new Managed PostgreSQL Database is provisioning.

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.