Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 37 ยท Add-ons and Config

Add-ons Overview

Learn how Heroku add-ons work: provisioning with addons:create, plans, attachments and config vars, sharing between apps, popular add-ons and how to control cost.

Your dynos should do one thing well: run your code. Everything stateful or specialized, such as a database, a cache, a log search tool, an email sender or a job scheduler, is a separate service. On Heroku you obtain these as add-ons: managed services from Heroku or third-party providers, provisioned with one command and connected to your app through config vars.

Add-ons are the "backing services" of the twelve-factor model made practical. You do not install or patch the software; the provider runs it and bills you (usually through your Heroku bill).

Provisioning an add-on

An add-on is identified by service and plan, written service:plan:

CONSOLE
$ heroku addons:plans heroku-postgresql
$ heroku addons:create heroku-postgresql:essential-0
$ heroku addons
$ heroku addons:info heroku-postgresql
$ heroku addons:open heroku-postgresql
  • addons:plans SERVICE lists the plans and their prices, which is the way to see current names and costs (plan names change; confirm them before you copy a command from an old tutorial).
  • addons:create SERVICE:PLAN provisions a new instance and attaches it to your app. If you omit the plan, you get the service's default entry plan.
  • heroku addons lists the add-ons of the app with plan and state.
  • addons:open opens the provider's dashboard.
  • addons:upgrade moves to a different plan; addons:destroy removes the add-on and, for data services, its data. Destroying asks you to retype the add-on name.

Creating an add-on creates a release, because the new config vars are part of the app's state.

Attachments and config vars

Provisioning gives the app an attachment, which is the link between the app and the add-on instance. Each attachment has a name, and the attachment exposes one or more config vars with connection details.

For Postgres the first attachment is named DATABASE, and the config var is DATABASE_URL. A second database on the same app gets a name based on a color or the name you choose, for example HEROKU_POSTGRESQL_CHARCOAL_URL. You can choose the name when you create it:

CONSOLE
$ heroku addons:create heroku-postgresql:essential-0 --as ANALYTICS_DB

That creates ANALYTICS_DB_URL. Your code reads the variable; it never needs to know where the database physically is.

Sharing one add-on between apps

The same instance can be attached to more than one app, for example a web app and a separate admin app sharing a database:

CONSOLE
$ heroku addons:attach postgresql-curved-12345 -a admin-app --as DATABASE

The two apps now see the same data. Deleting the add-on from the owner app has consequences for all attachments, so handle it carefully. Detach with heroku addons:detach NAME.

Common add-ons

Add-ons you will meet

Heroku Postgres Managed SQL database.
Key-Value Store Redis-compatible cache and queue.
Scheduler Run commands on a timer.
Logging Store and search your logs.

Names and plans change; check the Elements marketplace.

1 / 2

The marketplace (called Elements) lists hundreds of options by category. Heroku's own Postgres, Key-Value Store (Redis-compatible), and Scheduler cover the most common needs; third parties provide logging, monitoring, search, email and many more. Details of the database are in the data chapter of this course, and you will see logging again in operations.

Choosing a plan and watching cost

Each add-on plan has a price, usually per month and prorated to the second, and some have a free or very low tier with limits (rows, memory, connections). Practical advice:

  • Start with the smallest plan that meets your needs and upgrade when metrics say so.
  • Check heroku addons in every app, including old ones: forgotten add-ons keep billing.
  • Remember that each environment has its own add-ons: staging also pays for a database.
  • Billing for add-ons goes to the app owner.
  • Read the plan's limits (connections, storage, uptime guarantee). A plan with no backups or no high availability is fine for a hobby project, not for customer data.

Stand-in: parse an add-on spec

The service:plan syntax is easy to mistype. This stand-in parses specs, checks them against a made-up catalog and shows the config var each attachment would create. It models the idea only; the real names come from heroku addons:plans.

Python Stand-in: validate service:plan and name the config var

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: attachments across apps

This stand-in shows two apps attached to the same database instance and what happens to the config vars. Both apps point at the same instance, so writes from one are visible to the other.

Python Stand-in: one add-on, two apps

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Cleaning up

CONSOLE
$ heroku addons -a demo-shop
$ heroku addons:destroy heroku-postgresql-curved-12345 -a demo-shop

Before destroying a database, make sure you have a backup you have tested (see the data chapter). The platform will ask you to confirm by typing the app name; read the prompt rather than adding --confirm out of habit.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What format identifies an add-on to provision?

    The format is service:plan, for example heroku-postgresql:essential-0 (check addons:plans for current names).
  2. 2. How does your app learn how to connect to an add-on?

    Attachments inject connection details such as DATABASE_URL as config vars.
  3. 3. Two apps are attached to the same Postgres instance. What do they share?

    An attachment is a link to one instance, so both apps read and write the same database.
  4. 4. Why check heroku addons on old apps?

    Forgotten add-ons continue to cost money until they are destroyed.
  5. 5. Which command lists the plans and prices of a service?

    addons:plans shows the current plans and prices for a service.

Summary

  • Add-ons are managed services (database, cache, logging, scheduler, email and more) provisioned with heroku addons:create service:plan.
  • Attachments connect an add-on to an app and set config vars such as DATABASE_URL; an instance can be shared across apps.
  • Creating or destroying an add-on creates a release; destroying a data add-on deletes its data.
  • Check plans and limits before choosing, and audit add-ons regularly to control cost.

Next: app.json and the app manifest