Application Setup

Resources

A resource is a network-attached dependency of your application.

Definition

Here we define a resource called mydb that is a Postgres database with 100GB of storage, and we then link it to our web service, which will be given an env var to connect to the database:

resources:
  mydb:
    type: postgres
    options:
      storage: 100
services:
  web:
    resources:
      - mydb

The resource name only affects the environment variable name that is passed to your services. You are free to name it what you wish with no regard to the type of resource.

You can easily define multiple resources within one convox.yml:

resources:
  maindb:
    type: mysql
  gisdb:
    type: postgres
    options:
      version: 12
  queue:
    type: redis
  cache:
    type: redis
services:
  web:
    resources:
      - maindb
      - gisdb
      - queue
      - cache

Read Replica Support

*Available in rack version 20240513194424 or later*

Read replicas allow you to scale out read-heavy workloads by creating read-only copies of an existing database. This helps distribute database traffic, improve performance, and enhance application scalability without affecting the primary database.

Defining a Read Replica

To create a read replica using Convox resources, reference an existing database as the readSourceDB in your convox.yml file. The source database must exist before deploying a read replica.

How to Set readSourceDB

The value for readSourceDB follows this format:

#convox.resources.<source-database-name>

The #convox.resources. prefix is constant, and the <source-database-name> must match the name of the database resource you want to replicate. For example, if your primary database resource is named maindb, then the correct readSourceDB reference would be:

readSourceDB: "#convox.resources.maindb"

Configurable Read Replica Options

While read replicas inherit most configurations from their primary database, certain parameters can be adjusted:

Encryption Rules

• If the primary database is unencrypted, the read replica must also be unencrypted.
• If the primary database is encrypted, the read replica can be either encrypted or unencrypted.
• You cannot create an encrypted read replica from an unencrypted primary database.

Storage Capacity Rules

• A read replica can have more storage than the primary database, but not less.
• Storage capacity cannot be reduced once allocated.

Multi-AZ Failover (durable)

• Multi-AZ failover is optional for read replicas.
• A read replica is not required to have durable: true, even if the primary database does.

Important: Ensure the Database Version Matches

When creating a read replica, it is mandatory to explicitly set the same database version as the primary database. A mismatch can lead to deployment failures or unexpected behavior.

Always ensure the version field in the read replica matches the source database exactly.

Example Configuration

resources:
  primary-db:
    type: mysql
    options:
      version: "8.0"  # Ensure the version matches the primary database
      class: db.t3.medium
      storage: 50
      encrypted: true
      durable: true

  read-replica:
    type: mysql
    options:
      readSourceDB: "#convox.resources.primary-db"
      version: "8.0"  # The read replica must use the same version as the primary database
      class: db.t3.medium
      storage: 50
      encrypted: true

Converting a Read Replica to an Active Database

If you want to convert a read replica into an independent database, remove the readSourceDB option from convox.yml and redeploy the application. This process does not affect the original primary database, and the read replica retains the same name.

EFS Resource

*Available in rack version 20221214201933 or later*

The EFS resource lets you share volumes between services in different AZs.

EFS resources have additional configurations. The definition is different from the database resources. See Available Resources > EFS. After declaring the resource and the options, the link between the resource and service you want to expose is required. Example:

resources:
  sharedvolume:
    type: efs
    options:
      path: "/root-directory"
services:
  web:
    resources:
      - sharedvolume

Once the resource is linked to the service, set the volume and the path you want to expose to the application, e.g. {efs-resource-name}:/path/to/mount/on/application. The path you want to link the application is not bound to the same you declared in the definition, it’s the directory that will be mount in the application container. A full example of EFS resource using the resources and volumes:

resources:
  sharedvolume:
    type: efs
    options:
      path: "/root-directory"
services:
  web:
    volumes:
      - sharedvolume:/app/dir
    resources:
      - sharedvolume

Dynamic Configuration

If you’d like to make your resource configuration variable (e.g. to produce different results between environments like staging vs production) you can use environment variable interpolation:

resources:
  mydb:
    type: postgres
    options:
      storage: ${POSTGRES_STORAGE_SIZE}

$ convox env set POSTGRES_STORAGE_SIZE=50 --rack=acme/staging
$ convox env set POSTGRES_STORAGE_SIZE=200 --rack=acme/production

Accessing Resources

You can access defined resources from services with environment variables. In the above example, the mydb resource provides a MYDB_URL variable that is accessible from the web service.

The environment variable name is the resource name converted to all-caps, with a _URL suffix.

This would contain the entire connection string you would need, ie:

MYDB_URL=postgres://username:password@host.com:5432/databaseName

Additional credentials

*Available in rack version 20221013170042 or later*

You can also use the additional credentials to connect to the resource, the credentials will be provided in the environment variables with the resource name prefix and the following suffix: _USER, , _PASS, _HOST, _PORT, _NAME.

Using the example above, the resource name mydb will provide the following environment variable:

MYDB_USER=username
MYDB_PASS=password
MYDB_HOST=host.com
MYDB_PORT=5432
MYDB_NAME=databaseName

Available Resources

memcached

mariadb

mysql

postgres

redis

efs

Use to share volumes between the tasks in different AZs and instances.

AutoMinorVersionUpgrade

In case you specify the minor version on your resource definition you have to turn off the AutoMinorVersionUpgrade on your app parameter. It’s enabled by default and it will update the DB instance during the maintenance window.