Database
Store structured content in a built-in database you edit like a spreadsheet, and use across your site, your automations, and Ploy's Agent.
A database is for structured data — content organized into fields, where every entry of a kind shares the same shape. Blog posts, job listings, team members, products, form submissions: each gets its own table, with the same columns on every row. Keep it in one place, and your site, your team, and Ploy's Agent all work from that single source.
One common use is as a CMS for your site. Ploy's Agent builds one template that turns every row into its own page, so publishing a post or a listing is as simple as adding a record — and you write and manage it all right in the table. No code, and no page to build each time.
You don't need to write database code. Ask Ploy's Agent to set up or edit tables, columns, records, and the pages that use them, or manage everything visually. Find your databases under Database in the workspace sidebar.
When to Use a Database
Reach for a database whenever content repeats in a consistent shape:
- Blog and changelog posts — announcements, release notes, updates.
- Listings and directories — jobs, team members, customers, events.
- Catalogs — products, pricing tiers, features.
- Form submissions — contact requests, waitlist signups, RSVPs.
- App data — accounts, users, sessions, and other application records.
Rule of thumb: if you'd keep it in a spreadsheet, it belongs in a database. For one-off content — a homepage hero, an About page — just edit the page. Running a blog? CMS & Blogging covers that end to end, and we recommend backing it with a database.
Core Concepts
| Term | Description |
|---|---|
| Database | The top-level container, owned by your workspace. Create as many as you need. |
| Table | One collection of things — Jobs, Team, Posts. A database holds many. |
| Column | A typed property on a table — Title, Status, Published date. |
| Record | A single row — one job, one person, one entry. |
| Access key | A scoped credential that lets your published site read or write specific tables. |
Creating a Database
Describe what you're modeling and let Ploy's Agent set it up:
- "A database for job listings with title, department, location, and a status"
- "A customer directory — company, industry, logo, and a link to their case study"
Ploy's Agent proposes the tables and columns and creates them once you approve; you can also build them by hand. You don't have to start empty: choose Import CSV and point it at a new or existing table. Ploy reads the first row as your column names and picks a sensible type for each.
Editing Your Data
The grid works like a spreadsheet:
- Edit inline — click a cell and type; changes save as you go.
- Record panel — open a single row to see all its fields in one view, easier for long values.
- Filter, sort, reorder — filter any column, sort by any column, and drag rows and columns into the order you want.
- Live updates — changes appear as they happen, including new submissions from your live site, with no refresh.
Columns can be text or long text, number, currency, or percent, checkbox, single- or multi-select, status, people, date, URL, or email. Change a column's type later and Ploy converts the existing values for you; if a value can't convert, it stops and shows you which rows to fix.
Any workspace member can view a database; owners and admins make changes — editing records, adjusting columns and tables, and managing databases, keys, and restore points.
Powering Pages with Your Data
Describe the page and Ploy's Agent builds it from your table, layout and all:
"Build a /jobs page listing every open role by department, with a detail page for each."
A page built this way keeps itself current: your edits reach visitors on their own, usually within a minute, with no republish. It stays fast, too, even with a lot of records.
Your site can collect information, too. Ask for a contact form, a waitlist, or an RSVP, and every submission lands straight in a table.
Access Keys
A published site can't sign in the way you do, so it reaches a database with its own credential: an access key.
When Ploy's Agent builds a page that reads from a database, it creates the appropriate key and adds it to your site after you approve. The key's value isn't exposed along the way. To create, roll, or revoke keys yourself, open Manage access on the database (owner/admin only).
Every key belongs to one database. For each table, grant read access, write access, both, or neither. New keys have no table access until you configure them, and write-only keys can't read data back. A common setup uses a read-only key for pages that display content and a write-only key for forms.
Heads up: A key's value is shown once, when you create or roll it — Ploy doesn't keep a copy you can look up later. Copy it right then; if you lose it, roll for a new one.
A key lives as a Secret in your site's Environment Variables under a name you choose (e.g. JOBS_READ_TOKEN). When Ploy's Agent creates a key for a page it built, it sets that secret for you; if you make one yourself, you add it the same way. It takes effect the next time you publish. Later, you can roll a key to replace a leaked one, revoke it to turn it off, or change which tables it can reach.
Building outside Ploy? See Use PloyDB from your own app for the server-side API, authentication, and read and write examples.
Version history and restore
Ploy keeps a rolling 30-day history of every database. You can create a named restore point before a risky change, or roll the database back to any point in the last 30 days. Before a rollback, Ploy automatically creates an undo point, so you can reverse the restore if needed. Only workspace owners and admins can restore a database.
Secret Columns
Some columns hold sensitive values — a password hash, a session token, a user's API key. Ploy hides these from Ploy's Agent, so they never show up in a chat. Columns that look like credentials are hidden automatically, and you can flag any column yourself with Mark as secret. Only a person can un-hide one: Ploy's Agent can mark a column secret, but never reveal it.
Good to Know
- From your own app — Use the external-app API from a backend, serverless function, or mobile client.
- From the terminal — the Ploy CLI lists databases, queries tables, and bulk-imports CSVs, for automations and agents.
- Limits — up to 97 columns per table and 128 KB per text value; CSV imports up to 32 MB. Writes from published sites are rate-limited to help protect a database from abuse.
What's Next?
- Build the pages — Site Builder covers pages, sections, and the design system.
- Store the key — Environment Variables & Secrets shows how to add your access key to a site.
- Run a blog — CMS & Blogging covers the blogging workflow, backed by a database.
- Go live — Publishing & Deploys ships your site and applies new secrets.