Postgres

Definition

A Postgres Resource is defined in convox.yml and linked to one or more Services.

resources:
  database:
    type: postgres
services:
  web:
    resources:
      - database

Options

A Postgres Resource can have the following options configured for it (default values are shown):

resources:
  database:
    type: postgres
    options:
      version: 13
      storage: 10

AWS RDS Managed Postgres Resources

In addition to containerized resources, Convox v3 allows the creation of Postgres resources via AWS RDS. This provides enhanced durability and managed service benefits. Below is a general example of how to define AWS RDS resources:

resources:
  database:
    type: rds-postgres
    options:
      class: db.m5.large
      storage: 100
      version: 13
      deletionProtection: true
      durable: true
      encrypted: true
      backupRetentionPeriod: 7
      preferredBackupWindow: 02:00-03:00
      preferredMaintenanceWindow: sun:05:00-sun:06:00
services:
  web:
    resources:
      - database

Features

  • Read Replica Support: AWS RDS resources support integrated AWS read replicas. You can configure read replicas for improved read scalability and reliability. Additionally, read replicas can be promoted to active primaries if needed.
  • Snapshot Restoration: Easily restore from a snapshot to create a new database instance with your desired specifications.
  • Import Existing RDS Database: Import existing AWS RDS databases into a Convox rack for management or access via linking.

Configuration Options

Below is a chart of configuration options available for AWS RDS Postgres resources:

Attribute Type Default Description
class string db.t3.micro The compute and memory capacity of the DB instance.
encrypted boolean false Whether to enable storage encryption.
deletionProtection boolean false Whether to enable deletion protection for the DB instance.
durable boolean false Whether to create a Multi-AZ DB instance.
storage int 20 The amount of storage (in GB) to allocate for the DB instance.
version string 13 The version of the database engine.
preferredBackupWindow string AWS managed The daily time range during which automated backups are created if automated backups are enabled, using the backupRetentionPeriod option. Must be in the format hh24:mi-hh24:mi, in UTC, at least 30 minutes, and must not conflict with the preferred maintenance window. If not set, AWS decides based on usage.
backupRetentionPeriod int 1 The number of days for which automated backups are retained. Setting this parameter to a positive number enables backups. Setting this parameter to 0 disables automated backups.
iops int AWS managed The amount of provisioned IOPS.
port int 5432 The port on which the database accepts connections.
masterUserPassword string Convox managed The password for the master user. Should be set as an environment variable to avoid hardcoding.
allowMajorVersionUpgrade boolean true Whether major version upgrades are allowed.
autoMinorVersionUpgrade boolean true Whether minor version upgrades are applied automatically.
preferredMaintenanceWindow string AWS managed The weekly time range during which system maintenance can occur. Must be in the format ddd:hh24:mi-ddd:hh24:mi, in UTC, at least 30 minutes, and must not conflict with the preferred backup window. If not set, AWS decides based on usage.
readSourceDB string `` The source database identifier for creating a read replica.
import string `` The database identifier used for database import. Requires the correct masterUserPassword option set.
snapshot string `` The snapshot identifier for restoring from a snapshot.

Note: The readSourceDB option is used for the read replica feature.

Note: The import option requires the correct masterUserPassword to be set for importing a database.

Note: The masterUserPassword should be set as an environment variable to avoid hardcoding the password.

Command Line Interface

Listing Resources

$ convox resources -a myapp
NAME      TYPE          URL
database  rds-postgres  postgres://username:password@host.name:port/database

Getting Information about a Resource

$ convox resources info database -a myapp
Name  database
Type  rds-postgres
URL   postgres://username:password@host.name:port/database

Getting the URL for a Resource

$ convox resources url database -a myapp
postgres://username:password@host.name:port/database

Launching a Console

$ convox resources console database -a myapp
psql (13.3 (Debian 13.3-1.pgdg90+1), server 13.3 (Debian 13.3-2.pgdg90+1))
Type "help" for help.
database=#

Starting a Proxy to a Resource

$ convox resources proxy database -a myapp
Proxying localhost:5432 to host.name:port

Proxying allows you to connect tools on your local machine to Resources running inside the Rack.

Exporting Data from a Resource

$ convox resources export database -f /tmp/db.sql
Exporting data from database... OK

Importing Data to a Resource

$ convox resources import database -f /tmp/db.sql
Importing data to database... OK