Environments, staging and deploying to production
Give a project a staging environment with its own database, functions, policies and API URL, make changes there first, and deploy them to production with a checked, all-or-nothing step.
An environment is an extra database for the same project, created in the project's own database container. It starts as a copy of production's structure — tables, views, functions, row-level security policies and migration history — with no rows, and gets its own API URL. It has its own functions and access policies too, using production's for anything it doesn't change. Work there never touches production.
Create an environment
Open the environment switcher
In the console top bar, open the database menu and choose + New environment or API version, then Staging.
Name it
Lowercase letters, digits and dashes, starting with a letter — for example
stagingorpreview.Switch to it
When it is built, pick it in the same menu. Its API URL is shown in Connect; point your test app at it.
Make changes in staging first
Turn on Project settings → Database → Staging first. If the project has no environment yet, Sovaria builds staging first and shows the progress. From then on, tables, columns and migrations are made in staging, and production changes only through Deploy to production.
Deploy to production
Deploy to production (top bar) lists everything the environment has that production doesn't: its migrations, its new and changed functions and its new and changed access policies. Before anything is applied it is all checked with nothing written — the migrations run on production inside a transaction that is rolled back, every function and policy is validated, and production's access is simulated with the new policies. Only if everything passes is it applied, as one commit you can undo from Version history: see, undo and restore changes. If something fails, nothing is applied and you see what and why.
What is separate and what is shared
| Per environment | Shared with production | |
|---|---|---|
| Database: tables, rows, row-level security | Yes | |
| API URL | Yes | |
| Migrations history | Yes (starts as production's) | |
| Functions | Its own versions; production's for any it hasn't changed | |
| Access policies | Its own; production's for any it hasn't replaced | |
| Function secrets and environment variables | Yes (never copied or deployed) | |
| Storage buckets, API keys, team, billing | Yes |
An environment can also be an API version of your app — production stays v1, the environment is v2 with its own URL, and both keep working. See API versions: run v1 and v2 side by side.
Plans and extra environments
| Free | Pro | Ultra | Team | Enterprise | |
|---|---|---|---|---|---|
| Environments per project, staging and API versions together (besides production) | — | 2 | 5 | 10 | 50 |
| Start an environment from another environment (not only production) | — | — | Yes | Yes | Yes |
On Pro, Ultra and Team you can add up to 10 more with the Extra environment add-on ($5 per month each) under Billing. An environment's disk counts towards database storage like production's.
Common mistakes
- Expecting staging to have production's rows. It starts empty on purpose; seed it with test data.
- Pointing a test app at production's URL. Use the environment's URL from Connect.
- Writing migrations without down SQL — then they can't be undone from Version history: see, undo and restore changes.