Memory and sizing

Every web service, worker, cron job, database and key value store has a memory slider. The memory you set is guaranteed to that service on the machine it runs on. Its CPU and disk follow the same share of the machine.

The slider

On web services and cron jobs, the slider is labelled Guaranteed memory. On workers, it's Guaranteed memory per instance. Databases and key value stores have a Memory slider.

The slider goes up to what the chosen machine has free. When the project has several machines, it follows the machine you pick in the Machine field. It starts lower when the machine has less than the starting value free. Free memory here is memory not yet guaranteed to another service.

If the machine doesn't have the smallest amount free, the form says so. Lower another service's memory, pick another machine, or add or enlarge a machine first.

As you move the slider, the form shows:

• the vCPU guaranteed at that memory
• the disk at that memory
• how much memory and disk it leaves free on the machine

Memory doesn't change the price. A service's fee is the same at any size. See How billing works.

Memory

The memory you set is guaranteed to the service. A machine's guarantees never add up to more than its usable memory, so each service always has its own.

Use idle memory

Web services, workers and cron jobs can also use memory the machine's other services aren't using, up to the machine's usable memory. Turn this on or off with the Use idle memory switch on the service's Settings page, under the memory slider. It's on by default.

The switch saves straight away. The change applies at once:

• A web service restarts.
• A worker redeploys.
• A cron job uses it from its next run.

Databases and key value stores always have exactly their own memory. They never use idle memory, because their settings are tuned to their size.

Guarantee what a service needs most of the time, not its peak. With idle memory on, it can use more at busy moments.

When the machine runs short

If the machine runs short of memory, the service using the most beyond its guarantee restarts first. Its Events page shows an amber Memory short event, which says it restarted because its machine ran short of memory. The service isn't shown as crashed. If this happens often, give it more guaranteed memory.

When a service runs out of memory

A service can use up to its guarantee with idle memory off, or up to the machine's whole usable memory with it on. A service that tries to use more is stopped and restarted. Its logs say it ran out of memory. If that happens, give it more memory in its settings.

CPU

Each service is guaranteed the same share of the machine's CPU as its share of memory. For example, a service guaranteed a quarter of the machine's usable memory is guaranteed a quarter of its usable CPU.

Idle CPU is shared. Any service can use all of the machine's cores when the others don't need them, so the guarantee only matters when the machine is busy.

Disk

Each service gets the same share of the machine's usable disk as its share of memory. For a Postgres database, that share is its storage allowance. See Postgres storage. A database on a volume keeps its data there instead and takes no share of the machine's disk.

What counts against the machine

Every service keeps its guaranteed memory for as long as it exists, so you can always resume or start it again without running out of room. That includes:

• a web service you have suspended
• a worker you have stopped (each instance holds its memory)
• a cron job between runs
• a database's or key value store's standby, which holds the same memory and disk on its machine as the original

Some parts of the project take a fixed amount of memory on a machine:

Each one appears as its own row in the machine's table on the Resources page.

A command is refused if the machine can't guarantee 128 MB, or doesn't have enough memory free right now. The message says which.

Leave room for builds and updates

Builds run on the service's machine. They reserve only a little memory and borrow what the machine has idle.

Memory that isn't guaranteed to any service decides how a web service updates. If the machine has room for a second copy of the web service's guaranteed memory, the new version starts next to the old one. Visitors notice nothing. If it doesn't, the old version stops first and the service is briefly offline.

The Resources page names the web services that will go offline during an update, for example: "Updates will briefly take shop offline. There isn't room on machine-1 to start the new version beside the old one." For zero-downtime deploys, keep at least as much memory unguaranteed on the machine as the web service's guaranteed memory. See Deploys.

Change a service's memory

Open the service's Settings and move its slider: