Volumes

A volume gives a database room to grow without a larger machine. Without one, a database's storage is a share of its machine's disk that follows its memory. On a volume, the database has storage of its own, and you can grow it whenever you need more.

A volume is network storage in the same geo as its database's machine, attached to that machine. Each volume holds one database. A project can have up to 4 volumes.

Create a volume

1. On the project's Services page, click Add next to Volumes. You can also open a database's Settings and click Add a volume under Storage.
2. Under Attach to, choose the database.
3. Optionally, enter a Name. By default the volume is named after its database.
4. Choose its Size, from 10 GB to 1,000 GB in steps of 10. The slider shows how much is for data and the monthly price as you move it.
5. Click Create volume.

Creating a volume is refused when:

• the database has a standby, because one machine holds the volume. Remove the standby first.
• the database already uses 90% or more of the volume's room for data. Choose a larger size.
• the database's machine doesn't have room for a second copy of the database while it moves. See What happens to the database.

In an app Athena built, you can also type /volume in Athena's box, or /volume 50 for a 50 GB volume.

What happens to the database

The database moves onto the volume. This takes a few minutes, longer for a large database, and the volume shows Moving meanwhile.

• The database keeps running while its data is copied.
• Its connections drop for a few seconds when it switches over to the copy on the volume. Apps reconnect by themselves.
• Its address stays the same, so DATABASE_URL and your app don't change.

While the data moves, the database runs a second copy of itself, so its machine needs the database's memory free for a few minutes.

When it's done, the volume shows Attached.

Storage

95% of a volume is for the database's data; the rest is left for the filesystem. The volume's Overview shows how much is Used, measured every 5 minutes, and the database's Overview shows it too.

As on the machine's disk, the database warns you when its data reaches 90% of that space, and becomes Read-only when it's full, until it has room again. See Postgres storage.

A database on a volume uses none of the machine's disk, and giving it more memory doesn't change its storage.

Grow a volume

Open the volume's Settings, move the slider under Size and click Grow. It grows in place in a minute or so, with the database running.

A volume can grow but can't shrink.

Backups

Backups work the same on a volume. The two do different jobs. A volume is where the data lives, and backups bring it back after a mistake. Turn backups on for any data you'd miss.

Remove a volume

Open the volume's Settings and click Remove volume under Danger Zone. The database moves back onto the machine's disk the same way, keeps running, and then the volume is deleted.

Removing is refused while the database uses 90% or more of the storage the machine's disk would give it. The Danger Zone shows that amount. Remove data, or give the database more memory, first.

Deleting a database also deletes its volume.

Price

A volume costs its monthly service fee plus its size, per GB a month. It's billed by the second from when you create it until it's removed. The create form shows both under Price, and the slider shows the total. A volume keeps the price it was created at until it grows.

A volume keeps billing while its project is suspended, because its storage still exists. See How billing works.