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

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 (20221013170042 or newer)

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

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.