Managed databases
Create a dedicated PostgreSQL database for a workspace, connect to it, and back it up and restore it.
A managed database is a PostgreSQL database dedicated to one workspace, with its own size, backup schedule and point-in-time restore. You don't need one to get started: every workspace already has a shared database. Create a managed database when you want your data isolated, sized for your load, or backed up on your own schedule.
Before you start
- To create, resize, back up or restore: the Writer, Admin or Owner role. To delete: the same. To view: Member or above.
- Room under the per-workspace limit: a workspace can have up to 5 managed databases by default. This is a platform setting, not part of your plan, and it can differ on your cell. Databases that failed to create don't count.
Create a database
Open Databases
Go to Data → Databases and pick the workspace at the top of the page.
Create it
Click Create, enter a name and choose a size: small or medium. The engine is PostgreSQL.
Wait until it's ready
Creating takes a few minutes. The list shows its status until it's ready.
The Databases list always starts with Shared PostgreSQL, marked Default: the free shared database every workspace has. It has no credentials to manage and can't be deleted. Your managed databases follow it.
For each ready database, the list also shows whether it can be used through the data API and Data Vault: Connected as <name>, or Not connected. If it says Not connected, click Retry. In Data Vault, a managed database that isn't connected is listed but can't be picked.
Connect to it
Your database's connection details are stored in Secrets, never shown in plain text in the API. The secret names come from the database's name, in capitals, with other characters turned into _. For a database called orders-db:
| Secret | Holds |
|---|---|
MANAGED_DB_ORDERS_DB_HOST | Host name |
MANAGED_DB_ORDERS_DB_PORT | Port |
MANAGED_DB_ORDERS_DB_USERNAME | User name |
MANAGED_DB_ORDERS_DB_PASSWORD | Password |
MANAGED_DB_ORDERS_DB_DATABASE | Database name |
There are two ways to use it:
- Through the data API. Browse it in Data Vault, and read and write it from code exactly as you would the shared database.
- Directly, from a Coderunner, with any PostgreSQL driver. Read the secrets above at runtime; see Configuration and secrets. Groundfloor won't pass these as deploy-time variables.
Sizes
small and medium set CPU, memory and storage. You can change the size on the database's page once it's ready.
Each database runs as a single instance. There's no high-availability option or automatic failover yet: if the instance fails, recovery is a restore from backup. Backups are kept in one region.
Backups and restore
| Feature | Details |
|---|---|
| Scheduled backups | A new database starts with a daily backup schedule, kept for 30 days, where backups are available on your cell. Change the schedule and how long backups are kept on the database's page |
| On-demand backups | Take one any time from the database's page |
| Point-in-time restore | Restore to any moment within the retention period: 30 days by default |
| Restore | Always creates a new database from the backup, leaving the original untouched |
Groundfloor aims to lose at most 5 minutes of data, and a restore usually takes a few minutes. These are targets, not contractual guarantees.
Delete a database
On the database's page, delete it and confirm. This can't be undone; restore from a backup if you need the data back.
Troubleshooting
| Problem | Likely cause | What to do |
|---|---|---|
| It stays in a creating state | Creation is still in progress | Wait a few minutes and refresh |
| You can't create one | The workspace already has its maximum number of managed databases (5 by default) | Delete a database you don't use, or ask the Groundfloor team about the limit. See Quotas and limits |
| You can't find the password | It's only in Secrets | Use the secret names above |
403 when creating | Your role can't create databases | Ask an Admin or Owner to raise your role |
| A database shows Not connected | The database is ready but wasn't connected to the data API | Click Retry. If it stays Not connected, contact support |
| An on-demand backup fails straight away with a message about backup storage | Backups aren't available on your cell yet | Contact support |
Next steps
- Data Vault — browse and edit its data.
- Configuration and secrets — read its credentials in a Coderunner.
- Managed Databases API — create and manage databases from code.