Your project database
Most apps need somewhere to keep things: signups, orders, posts, accounts. Berrybell can give your project its own managed Postgres database — created for you, connected to your app, and visible from a panel in the Studio.
This page covers what you can do with that database once it exists. If you just want to ask the AI to store something, start with Databases.
Turning it on
- Open your project settings and go to Cloud → Database.
- Press Enable Berrybell Cloud.
The card spells out what you're turning on: a dedicated Postgres database with pgvector, a SQL editor, table views and backups.
Provisioning runs in the background — the panel keeps checking and tells you when the database is Ready. If something goes wrong it shows the reason and a Retry button. (The provisioning screen names the Postgres host Berrybell uses underneath; that's expected.)
A project database is metered infrastructure. Enabling it requires an active plan with a hosting budget — on a workspace without one, Berrybell asks you to upgrade first and links to your plan options. See Plans & credits.
Turning Cloud on also sets up private file storage for the project's uploads, shown under Cloud → Storage. It's connected to your app the next time you publish, and can't be browsed from the Studio yet. See File storage.
Or start from the chat
When you ask for something that needs saved data, the AI stops before building and shows you a small card with Enable Berrybell Cloud and Not now. Choosing Enable Berrybell Cloud provisions the database and then continues with your request. The card waits about 90 seconds; if the database isn't ready by then, it shows "Timed out waiting for the database to provision." and holds your request until you choose again. Choosing Not now makes it build the feature with browser-only storage instead, and it won't ask again for that request — useful for a quick prototype, but the data lives only in that visitor's browser.
Browsing your data and schema
The Database page has two tabs, Tables and SQL editor. Tables has three views of its own: Data (the default), Schema and Backups.
- Data lists your tables down the left, each with an estimated row count
marked
~. The first table opens automatically. Rows come 50 to a page, with a "~N rows · page N" footer and arrows to page through them. ANULLvalue shows asNULL. - Schema lists your tables with their Name, Type, Schema and
Rows. Click one to see its columns — Name, Type, Nullable
(
NULLorNOT NULL) and Default, with a key icon on primary-key columns — then its indexes (Index; Type, which is primary, unique or index; and Definition) and a summary line such as "4 columns · 2 indexes · ~120 rows". All tables takes you back to the list, and View data opens the same table in Data.
Only tables are listed, not views, and they come from every schema except
Postgres's own system schemas. That includes the _migrations table (see
Schema changes and migration files) and,
once sign-in for your app's users is on, its tables. Row counts are Postgres's
estimates, not exact counts, so a table that has only just been filled can still
read ~0.
Any workspace member can browse these views. On a project with environments, Data, Schema and the SQL editor show the environment selected in the top bar. The first load of an environment that has been quiet can take a few seconds while its database wakes up.
Data and Schema are read-only. There is no inline cell editing and no way to insert a row by hand — use the SQL editor, or ask the AI to build the screen you need.
Once sign-in for your app's users is on, the tables that
hold its secrets — session, account, verification, rateLimit and
twoFactor — can't be opened in Data or Schema, and read-only queries
against them fail with a permission denied error (apart from a few harmless
columns of session and account). To look at your users, use Users under Cloud → Auth.
Running SQL
The SQL editor runs statements against your own database. On a project with environments, that's the database of the environment selected in the top bar.
- Read-only by default. Queries run as a restricted role unless you tick Allow writes / DDL, which switches to the owner role for that run.
- There are server-side limits. Statements are cut off after a timeout and results are capped at a maximum number of rows — currently a 15-second statement timeout and 1,000 rows. When a result was shortened, the editor says so.
- You need Editor permission in the workspace to run anything here.
- Production asks first. On a project with other environments, every run with Allow writes / DDL against production opens Run this SQL on production?, and nothing runs until you press Run on production. It asks every time. Read-only runs never ask.
- If the selected environment was deleted or isn't ready, the error comes with a Switch environment link.
Schema changes you make here aren't recorded as a migration file, so nothing applies them to any other database for you. See Schema changes and migration files.
Schema changes and migration files
The AI writes each structural change — a new table, a new column, an index — as a
numbered file under migrations/ in your project's code, such as
migrations/0001_add_orders.sql, and then applies it to the database. That's the
rule it follows, not something Berrybell enforces: a schema change run as plain
SQL still takes effect on that one database and leaves no file. Applying a
file falls under the Modify database permission (see
Letting the AI touch your data), so by default
the AI asks first. Projects started from a template that
keeps data in a database begin with migrations/0000_baseline.sql.
- Each applied file is logged in the
_migrationstable, with a fingerprint of its contents. That table is how Berrybell knows what has run, so don't edit it. - Each file runs as one transaction. If a statement fails, nothing from that file is kept, and later files aren't attempted.
- An applied file must not change. If one is edited — even just its line endings — or two files share a number, the next apply refuses every pending file until that's fixed. A correction always comes as a new file.
- Nothing applies files when you publish. A file reaches a database only when the AI applies it during a run on that environment. See Database changes don't travel with a publish.
Renaming a column, changing its type or dropping something comes in two steps:
add the new column, copy the values across, ship the code that uses it, and
remove the old one in a later change. That keeps your published app working while
the change lands. Nothing enforces this — a DROP in a migration file applies
cleanly and takes the data with it — so back up first.
Schema changes you make yourself in the SQL editor aren't written to a file, so nothing applies them to another environment. The one way they spread is by copy: an environment created or reset afterwards gets production's schema as it stands. Resetting an environment discards any made only there.
Backups
The Backups view keeps snapshots of your production database, whichever environment is selected. With another environment selected, it says so: "These are backups of production, not of the environment Cloud is showing, and restoring one replaces production's data."
- Back up now takes a snapshot of production immediately. Snapshots are copy-on-write, so they're near-instant and store only what has changed since they were taken — but they do count toward your database storage. You need the Editor role.
- Each row shows the backup's label (Snapshot for the ones you take), its type, when it was taken and its status. Berrybell adds some of its own: Before restore (see below) and Before enabling end-user auth, taken when sign-in for your app's users is turned on.
- Environments have no backups of their own. To give one a fresh copy of production, reset it.
- There is no delete-backup control in the Studio today, and no downloadable archive — you can't export a snapshot as a file. Backups, including the automatic ones, accumulate until support removes them.
Restoring a backup
Press the round-arrow button on a backup whose status is ready — its tooltip reads "Restore to this backup". There's no button labelled Restore.
- On a project with only production, your browser asks "Restore the database to this backup? Current data will be replaced."
- On a project with other environments, Restore production? opens instead, and nothing happens until you press Restore production.
You need the Editor role. Restoring replaces production's data — anything written since that backup is gone. Your published app keeps the same database connection, so there's nothing to republish.
A restore usually saves production's current state first as a Before restore backup, which you can restore to undo it. That isn't guaranteed — for example on a second restore in a row — so press Back up now before restoring if you might want to come back. A Before restore backup is stored and billed like any other.
There's no point-in-time restore in the Studio — only the backups in the list.
Take a snapshot before asking the AI for a big schema change on production. It's near-instant, and it's the fastest way back.
Environments: a database each
On a Business plan you can create environments —
staging, qa, development or another name of your choosing (lowercase
letters, numbers and hyphens) — from the Environments card on the
Cloud overview. Each one gets its own copy of production's database, taken
when it's created: the schema, the data and your app's user accounts. Its row
reads Preparing (branching from production)… until the copy is ready.
- An environment's app uses only its own database. You can't publish to an
environment until its database is ready, and a published environment is never
given production's
DATABASE_URL. - The top-bar switch decides which database is in use. The AI, the live preview and the Data, Schema and SQL editor views all use the environment selected in the top bar.
- Production isn't locked; it asks first. The card puts it as "Changes go to the environment you select. Production asks first." See Production asks first.
- Reset re-clones the database from production, after asking "Reset "staging" from production? Data and schema changes made only in staging will be discarded." Migrations applied only in that environment are undone; their files stay in your code.
- Delete destroys the environment's database, its compute and the environment's variables. It's refused while the environment still has custom domains.
Each environment's database has its own compute and storage, metered like production's. See Costs.
What Berrybell sets up for you
- Berrybell gives your app a
DATABASE_URLand aSESSION_SECRET. They're delivered to your app on every publish, but they aren't listed in Variables & secrets, and you can't add, change or override either name there. Each environment gets its ownDATABASE_URL, pointed at its own database when you publish to it. - The vector extension is installed for you, so an app can store and search embeddings without any setup.
Letting the AI touch your data
Your database also appears in Integrations as a first-party Berrybell Cloud connector, with a permission for each kind of action: Read database, Add data, Modify database (changing or deleting rows, schema and policy changes, and applying migration files), Run security checks, Read analytics and Read project info. The list also shows Configure auth and Read backend logs, though none of the AI's current database tools falls under either. The connector defaults to Ask each time.
On a project with environments, every call to production through this connector except Read database, Read analytics and Read project info asks each time — Run security checks included — even when it's set to Always allow. See Production asks first.
Through that connector the AI never receives a connection string and never picks its own database role: the server classifies each statement and runs read-only SQL as the restricted role, and anything else as the owner role, only after the permission you set is satisfied.
That's separate from your app's own DATABASE_URL, which your app's code does
receive — in the live preview (for the selected environment) and on every
publish — because it needs it to connect at all. The AI works alongside that
preview with the same connection, so code it runs there — a script, a seed, its
own database client — can use it without going through these permissions. See
Production asks first.
Costs
Database compute, storage and data transfer are metered hourly and drawn from your hosting budget, at cost plus a margin. The usage figures can trail real usage by one to three hours.
- The database sleeps when it's idle. After a short idle period it goes to sleep and wakes on the next query, so the first request after a quiet spell takes a moment longer — typically a few hundred milliseconds. The time it's awake is what Database compute meters.
- Each environment's database has its own compute and storage, metered separately from production's.
- Backups count toward storage, including the automatic ones, under Database storage.
See Plans & credits for how credits work and Billing for invoices.
There is currently no Disable or Delete control for a project database in the Studio. If you need one turned off, contact support.
If support turns Berrybell Cloud off, the database and every backup of it are deleted permanently, along with every environment you created and its database. Production's uploaded files are kept, but your app's next publish goes out without them connected, and turning Cloud back on doesn't reconnect them. Turning Cloud off is refused while an environment still has custom domains. See When files are deleted.