postgresql_instances

Creates, updates, deletes, gets or lists a postgresql_instances resource.

Overview

Name	postgresql_instances
Type	Resource
Id	linode.databases.postgresql_instances

Fields

The following fields are returned by SELECT queries:

get_databases_postgre_sql_instance

Returns information for a single PostgreSQL Managed Database.

Name	Datatype	Description
id	integer	Read-only A unique ID that can be used to identify and reference the Managed Database.
allow_list	array	Controls access to the Managed Database. - Individually included IP addresses or CIDR ranges can access the Managed Database while all other sources are blocked. - A standalone value of 0.0.0.0/0 allows all IP addresses access to the Managed Database. - An empty array ([]) blocks all public and private connections to the Managed Database.
cluster_size	integer	The number of Linode instance nodes deployed to the Managed Database. - Choose 3 nodes to create a high availability cluster that consists of one primary node and two replica nodes. - A 2 node cluster is only available with a dedicated plan. It consists of one primary node and one replica node.
created	string (date-time)	Read-only When this Managed Database was created. (example: 2022-01-01T00:01:01)
encrypted	boolean	Read-only Whether the Managed Databases is encrypted. Currently required to be true.
engine	string	Filterable, Read-only The Managed Database engine type. (example: postgresql)
engine_config	object	Advanced parameters you can apply to a PostgreSQL Managed Database, via our partner Aiven's specification. Only include the objects for parameters you want to set in your database. Omit objects for parameters you don't want to define or change. > 📘 > > Aiven may offer additional parameters in their specification. Currently, only those listed here are supported for use in a PostgreSQL Managed Database. You can also run the List PostgreSQL Managed Database advanced parameters operation to see an up-to-date list.
fork	object	Details on the database that was the target of the fork. This only exists if the database was restored by creating a fork from another MySQL or PostgreSQL database.
hosts	object	Read-only The primary and secondary hosts for the Managed Database. These are assigned after provisioning is complete.
label	string	Filterable A unique, user-defined string referring to the Managed Database. This string needs to be unique per Managed Database engine type. (example: example-db)
members	object	Read-only A mapping between IP addresses and strings designating them as primary or failover.
oldest_restore_time	string (date-time)	Read-only The oldest time to which a database can be restored. (example: 2024-10-03 20:48:05)
platform	string	Filterable, Read-only The back-end platform for relational databases used by the service. (example: rdbms-default)
port	integer	Read-only The access port for this Managed Database.
region	string	Filterable The Region ID for the Managed Database. (example: us-east)
ssl_connection	boolean	Currently required to be true. Whether to require SSL credentials to establish a connection to the Managed Database. Run the Get managed PostgreSQL database credentials operation for access information.
status	string	Filterable, Read-only The operating status of the Managed Database. (example: active)
total_disk_size_gb	integer	Read-only The total disk size of the database, in GB.
type	string	Filterable The Linode Instance type used by the Managed Database for its nodes. (example: g6-dedicated-2)
updated	string (date-time)	Read-only When this Managed Database was last updated. (example: 2022-01-01T00:01:01)
updates	object	Configuration settings for automated patch update maintenance for the Managed Database.
used_disk_size_gb	integer	Read-only The amount of space currently in use in the database, in GB.
version	string	Filterable The Managed Database engine version. (example: 13.2)

get_databases_postgre_sql_instances

Returns a paginated list of all accessible PostgreSQL Managed Databases on your account.

Name	Datatype	Description
id	integer	Read-only A unique ID that can be used to identify and reference the Managed Database.
allow_list	array	Controls access to the Managed Database. - Individually included IP addresses or CIDR ranges can access the Managed Database while all other sources are blocked. - A standalone value of 0.0.0.0/0 allows all IP addresses access to the Managed Database. - An empty array ([]) blocks all public and private connections to the Managed Database.
cluster_size	integer	The number of Linode instance nodes deployed to the Managed Database. - Choose 3 nodes to create a high availability cluster that consists of one primary node and two replica nodes. - A 2 node cluster is only available with a dedicated plan. It consists of one primary node and one replica node.
created	string (date-time)	Read-only When this Managed Database was created. (example: 2022-01-01T00:01:01)
encrypted	boolean	Read-only Whether the Managed Databases is encrypted. Currently required to be true.
engine	string	Filterable, Read-only The Managed Database engine type. (example: postgresql)
engine_config	object	Advanced parameters you can apply to a PostgreSQL Managed Database, via our partner Aiven's specification. Only include the objects for parameters you want to set in your database. Omit objects for parameters you don't want to define or change. > 📘 > > Aiven may offer additional parameters in their specification. Currently, only those listed here are supported for use in a PostgreSQL Managed Database. You can also run the List PostgreSQL Managed Database advanced parameters operation to see an up-to-date list.
fork	object	Details on the database that was the target of the fork. This only exists if the database was restored by creating a fork from another MySQL or PostgreSQL database.
hosts	object	Read-only The primary and secondary hosts for the Managed Database. These are assigned after provisioning is complete.
label	string	Filterable A unique, user-defined string referring to the Managed Database. This string needs to be unique per Managed Database engine type. (example: example-db)
members	object	Read-only A mapping between IP addresses and strings designating them as primary or failover.
oldest_restore_time	string (date-time)	Read-only The oldest time to which a database can be restored. (example: 2024-10-03 20:48:05)
platform	string	Filterable, Read-only The back-end platform for relational databases used by the service. (example: rdbms-default)
port	integer	Read-only The access port for this Managed Database.
region	string	Filterable The Region ID for the Managed Database. (example: us-east)
ssl_connection	boolean	Currently required to be true. Whether to require SSL credentials to establish a connection to the Managed Database. Run the Get managed PostgreSQL database credentials operation for access information.
status	string	Filterable, Read-only The operating status of the Managed Database. (example: active)
total_disk_size_gb	integer	Read-only The total disk size of the database, in GB.
type	string	Filterable The Linode Instance type used by the Managed Database for its nodes. (example: g6-dedicated-2)
updated	string (date-time)	Read-only When this Managed Database was last updated. (example: 2022-01-01T00:01:01)
updates	object	Configuration settings for automated patch update maintenance for the Managed Database.
used_disk_size_gb	integer	Read-only The amount of space currently in use in the database, in GB.
version	string	Filterable The Managed Database engine version. (example: 13.2)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_databases_postgre_sql_instance	select			Display information for a single, accessible PostgreSQL Managed Database. Learn more... Learn more...
get_databases_postgre_sql_instances	select		page, page_size	Display all accessible PostgreSQL Managed Databases. Learn more... Learn more...
post_databases_postgre_sql_instances	insert	data__label, data__type, data__engine, data__region		Provision a PostgreSQL Managed Database Use this operation to create a new PostgreSQL Managed Database. - Restricted users need the add_databases user grant. - New instances can take 10 to 15 minutes to deploy. - When you create a new PostgreSQL Managed Database, our partner Aiven automatically enables disk encryption on each cluster. - 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 updates, which apply security patches to the underlying operating system of the PostgreSQL Managed Database. Configure the maintenance window for these updates with the Update a managed PostgreSQL database operation. - If your database cluster is configured with a single node, downtime occurs during maintenance updates. Adjust the window to match a time that's the least disruptive to your application and users. Also consider upgrading to a high availability plan to avoid any maintenance downtime. - Major upgrades are optional until the service reaches end of service, and can be done in place. - A successful request triggers a database_create event. Restore a PostgreSQL Managed Database Include the fork object in the request to target a backed-up database. Your user needs read_write access to the target database and its status can be active, degraded, or failed. > 📘 > > Restoring from a backup creates a second running cluster, which incurs billing. Delete the first cluster after the restore is complete, to avoid this billing. Learn more... Learn more...
post_databases_postgre_sql_instance_patch	update			Apply security patches and updates to the underlying operating system of the PostgreSQL Managed Database. This function runs during regular maintenance windows, which you can configure with the Update a managed PostgreSQL database operation. - The user needs read_write user grant access to the database. - The database's status needs to be active. - If your database cluster is configured with a single node, downtime occurs during maintenance updates. Consider upgrading to a high availability plan to avoid any maintenance downtime. - Major upgrades are optional until the service reaches end of service, and can be done in place. - A successful request triggers a database_upgrade event. Learn more... Learn more...
put_databases_postgre_sql_instance	replace			Make changes to an existing PostgreSQL Managed Database. - The user needs read_write user grant access to the database. - The database's status needs to be active. - New values set in the allow_list overwrite existing values. To keep existing values, run the List PostgreSQL Managed Databases operation, store the allow_list addresses from the response, and include them with any new addresses in this operation. - Updates to your allow_list may take a short period of time to complete, making this operation inappropriate for rapid successive updates. - Also allows resizing the database cluster to a larger one. Clusters can't be resized to smaller plans. - All Managed Databases include automatic updates, which apply security patches to the underlying operating system of the Managed PostgreSQL Database. Use the updates object in this operation to modify the maintenance window for these updates. - If your database cluster is configured with a single node, downtime occurs during maintenance updates. Use the updates object to adjust the window to match a time that's the least disruptive to your application and users. Also consider upgrading to a high availability plan to avoid any maintenance downtime. - Major upgrades are optional until the service reaches end of service, and can be done in place. - You can't update engine_config advanced parameter settings for a suspended database. You'll need to resume it first. - A successful request triggers a database_update event. Learn more... Learn more...
delete_databases_postgre_sql_instance	delete			Remove a PostgreSQL Managed Database from your account. - The user needs read_write user grant access to the database. - The database's status can be active, failed, or degraded. - Only unrestricted users can access this operation. They have access regardless of the acting token's OAuth scopes. Learn more... Learn more...
resume_databases_postgre_sql_instance	exec			Resume a suspended PostgreSQL Managed Database from your account. This resumes billing for the cluster. - The user needs read_write user grant access to the database. - The database's status needs to be suspended. - A successful request triggers a database_resume event. OAuth scopes. <br /> databases:read_write<br /> Learn more...
suspend_databases_postgre_sql_instance	exec			Suspend a PostgreSQL Managed Database from your account, releasing idle resources and keeping only necessary data. All service data is lost if there are no backups available. This halts billing for the cluster. - The user needs read_write user grant access to the database. - The database's status needs to be active. - Akamai deletes suspended clusters after 180 days. - A successful request triggers a database_suspend event. OAuth scopes. <br /> databases:read_write<br /> Learn more...

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
page	integer	The page of a collection to return.
page_size	integer	The number of items to return per page.

SELECT examples

get_databases_postgre_sql_instance

Display information for a single, accessible PostgreSQL Managed Database.

Learn more...

Learn more...

SELECT
id,
allow_list,
cluster_size,
created,
encrypted,
engine,
engine_config,
fork,
hosts,
label,
members,
oldest_restore_time,
platform,
port,
region,
ssl_connection,
status,
total_disk_size_gb,
type,
updated,
updates,
used_disk_size_gb,
version
FROM linode.databases.postgresql_instances;

get_databases_postgre_sql_instances

Display all accessible PostgreSQL Managed Databases.

Learn more...

Learn more...

SELECT
id,
allow_list,
cluster_size,
created,
encrypted,
engine,
engine_config,
fork,
hosts,
label,
members,
oldest_restore_time,
platform,
port,
region,
ssl_connection,
status,
total_disk_size_gb,
type,
updated,
updates,
used_disk_size_gb,
version
FROM linode.databases.postgresql_instances
WHERE page = '{{ page }}'
AND page_size = '{{ page_size }}';

INSERT examples

post_databases_postgre_sql_instances

Provision a PostgreSQL Managed Database

Use this operation to create a new PostgreSQL Managed Database.

- Restricted users need the add_databases user grant.

- New instances can take 10 to 15 minutes to deploy.

- When you create a new PostgreSQL Managed Database, our partner Aiven automatically enables disk encryption on each cluster.

- 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 updates, which apply security patches to the underlying operating system of the PostgreSQL Managed Database. Configure the maintenance window for these updates with the Update a managed PostgreSQL database operation.

- If your database cluster is configured with a single node, downtime occurs during maintenance updates. Adjust the window to match a time that's the least disruptive to your application and users. Also consider upgrading to a high availability plan to avoid any maintenance downtime.

- Major upgrades are optional until the service reaches end of service, and can be done in place.

- A successful request triggers a database_create event.

Restore a PostgreSQL Managed Database

Include the fork object in the request to target a backed-up database. Your user needs read_write access to the target database and its status can be active, degraded, or failed.

> 📘
>
> Restoring from a backup creates a second running cluster, which incurs billing. Delete the first cluster after the restore is complete, to avoid this billing.

Learn more...

Learn more...

INSERT INTO linode.databases.postgresql_instances (
data__allow_list,
data__cluster_size,
data__engine,
data__engine_config,
data__fork,
data__label,
data__region,
data__ssl_connection,
data__type
)
SELECT 
'{{ allow_list }}',
{{ cluster_size }},
'{{ engine }}' --required,
'{{ engine_config }}',
'{{ fork }}',
'{{ label }}' --required,
'{{ region }}' --required,
{{ ssl_connection }},
'{{ type }}' --required
RETURNING
id,
allow_list,
cluster_size,
created,
encrypted,
engine,
engine_config,
fork,
hosts,
label,
members,
platform,
port,
region,
ssl_connection,
status,
total_disk_size_gb,
type,
updated,
updates,
used_disk_size_gb,
version
;

Manifest

# Description fields are for documentation purposes
- name: postgresql_instances
  props:
    - name: allow_list
      value: array
      description: >
        Controls access to the Managed Database.

- Individually included IP addresses or CIDR ranges can access the Managed Database while all other sources are blocked.

- A standalone value of `0.0.0.0/0` allows all IP addresses access to the Managed Database.

- An empty array (`[]`) blocks all public and private connections to the Managed Database.
        
    - name: cluster_size
      value: integer
      description: >
        The number of Linode instance nodes deployed to the Managed Database.

 - Choose `3` nodes to create a high availability cluster that consists of one primary node and two replica nodes.

- A `2` node cluster is only available with a dedicated plan. It consists of one primary node and one replica node.
        
      valid_values: ['1', '2', '3']
      default: 1
    - name: engine
      value: string
      description: >
        The Managed Database engine in engine/version format.
        
    - name: engine_config
      value: object
      description: >
        Advanced parameters you can apply to a PostgreSQL Managed Database, via our partner [Aiven's specification](https://aiven.io/docs/products/postgresql/reference/advanced-params). Only include the objects for parameters you want to set in your database. Omit objects for parameters you don't want to define or change.

> 📘
>
> Aiven may offer additional parameters in their specification. Currently, only those listed here are supported for use in a PostgreSQL Managed Database. You can also run the [List PostgreSQL Managed Database advanced parameters](https://techdocs.akamai.com/linode-api/reference/get-databases-postgresql-config) operation to see an up-to-date list.
        
    - name: fork
      value: object
      description: >
        Include this object to restore a Managed Database by forking from a backup.

- If you include this object, all other fields are optional.

- Don't include this object if you're creating a new Managed Database.
        
    - name: label
      value: string
      description: >
        __Filterable__ A unique, user-defined string referring to the Managed Database. This string needs to be unique per Managed Database engine type.
        
    - name: region
      value: string
      description: >
        __Filterable__ The [Region](https://techdocs.akamai.com/linode-api/reference/get-regions) ID for the Managed Database.
        
    - name: ssl_connection
      value: boolean
      description: >
        Currently required to be `true`. Whether to require SSL credentials to establish a connection to the Managed Database. Run the [Get managed PostgreSQL database credentials](https://techdocs.akamai.com/linode-api/reference/get-databases-postgre-sql-instance-credentials) operation for access information.
        
      default: true
    - name: type
      value: string
      description: >
        __Filterable__ The Linode Instance type used by the Managed Database for its nodes.
        

UPDATE examples

post_databases_postgre_sql_instance_patch

Apply security patches and updates to the underlying operating system of the PostgreSQL Managed Database. This function runs during regular maintenance windows, which you can configure with the Update a managed PostgreSQL database operation.

- The user needs read_write user grant access to the database.

- The database's status needs to be active.

- If your database cluster is configured with a single node, downtime occurs during maintenance updates. Consider upgrading to a high availability plan to avoid any maintenance downtime.

- Major upgrades are optional until the service reaches end of service, and can be done in place.

- A successful request triggers a database_upgrade event.

Learn more...

Learn more...

UPDATE linode.databases.postgresql_instances
SET 
-- No updatable properties
WHERE 
;

REPLACE examples

put_databases_postgre_sql_instance

Make changes to an existing PostgreSQL Managed Database.

- The user needs read_write user grant access to the database.

- The database's status needs to be active.

- New values set in the allow_list overwrite existing values. To keep existing values, run the List PostgreSQL Managed Databases operation, store the allow_list addresses from the response, and include them with any new addresses in this operation.

- Updates to your allow_list may take a short period of time to complete, making this operation inappropriate for rapid successive updates.

- Also allows resizing the database cluster to a larger one. Clusters can't be resized to smaller plans.

- All Managed Databases include automatic updates, which apply security patches to the underlying operating system of the Managed PostgreSQL Database. Use the updates object in this operation to modify the maintenance window for these updates.

- If your database cluster is configured with a single node, downtime occurs during maintenance updates. Use the updates object to adjust the window to match a time that's the least disruptive to your application and users. Also consider upgrading to a high availability plan to avoid any maintenance downtime.

- Major upgrades are optional until the service reaches end of service, and can be done in place.

- You can't update engine_config advanced parameter settings for a suspended database. You'll need to resume it first.

- A successful request triggers a database_update event.

Learn more...

Learn more...

REPLACE linode.databases.postgresql_instances
SET 
data__allow_list = '{{ allow_list }}',
data__engine_config = '{{ engine_config }}',
data__label = '{{ label }}',
data__type = '{{ type }}',
data__updates = '{{ updates }}',
data__version = '{{ version }}'
WHERE 

RETURNING
id,
allow_list,
cluster_size,
created,
encrypted,
engine,
engine_config,
fork,
hosts,
label,
members,
oldest_restore_time,
platform,
port,
region,
ssl_connection,
status,
total_disk_size_gb,
type,
updated,
updates,
used_disk_size_gb,
version;

DELETE examples

delete_databases_postgre_sql_instance

Remove a PostgreSQL Managed Database from your account.

- The user needs read_write user grant access to the database.

- The database's status can be active, failed, or degraded.

- Only unrestricted users can access this operation. They have access regardless of the acting token's OAuth scopes.

Learn more...

Learn more...

DELETE FROM linode.databases.postgresql_instances;

Lifecycle Methods

resume_databases_postgre_sql_instance

Resume a suspended PostgreSQL Managed Database from your account. This resumes billing for the cluster.

- The user needs read_write user grant access to the database.

- The database's status needs to be suspended.

- A successful request triggers a database_resume event. OAuth scopes.

<br /> databases:read_write<br />

Learn more...

EXEC linode.databases.postgresql_instances.resume_databases_postgre_sql_instance 
;

suspend_databases_postgre_sql_instance

Suspend a PostgreSQL Managed Database from your account, releasing idle resources and keeping only necessary data. All service data is lost if there are no backups available. This halts billing for the cluster.

- The user needs read_write user grant access to the database.

- The database's status needs to be active.

- Akamai deletes suspended clusters after 180 days.

- A successful request triggers a database_suspend event. OAuth scopes.

<br /> databases:read_write<br />

Learn more...

EXEC linode.databases.postgresql_instances.suspend_databases_postgre_sql_instance 
;