Documentation Index
Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
Use this file to discover all available pages before exploring further.
Free while in preview. Data stores don’t count toward your plan’s usage today, but platform
charges will kick in once the feature is generally available. We’ll notify your organization
before any billing starts—nothing on your account will start charging without warning.
| Type | What it holds | Good for |
|---|---|---|
| Database | Tables of structured data (rows and columns) | Shared users, products, orders, content |
| Storage | Files and folders | Uploaded PDFs, images, documents you want to browse |
Data stores are built for complex internal systems—think a restaurant running a POS, a QR
ordering app, and a back-office dashboard, all inside one organization, all sharing the same
menu, orders, and customers. If you’re building a simple standalone site, the built-in app
database is still fine. If you’re building a small ecosystem of apps that need to see the same
data, you want a data store.
How it fits together
One store lives at the org level. Each connected app picks an access level (read, write, or admin) and routes each environment to a specific branch—so sandbox can safely experiment ondev while production keeps reading main.
When to use a data store
Data stores are designed for teams building multiple related apps inside one organization that need to share the same underlying data. A few examples of the kind of system they’re built for:- A restaurant running a POS terminal, a QR-code ordering app for tables, and a back-office dashboard—all reading and writing the same menu, orders, and customers
- A retailer with a customer storefront, an inventory manager, and a staff app sharing the same products and stock levels
- A service business with a booking site, an admin scheduler, and a customer portal operating on the same appointments and accounts
- Any setup where you want to browse and edit data directly in Stardeck across several apps at once
Example: restaurant operations
One shared database means a QR order placed by a customer shows up on the POS terminal instantly, and the back-office sees every sale as it happens—without any of the apps talking to each other directly.Example: retail with inventory
Two data stores: one database for structured data, one storage store for product photos. The customer storefront only needs read access; the staff app writes orders; the inventory manager has full control over both.Creating a data store
- Open the Dashboard and go to Data Stores
- Click New Data Store
- Give it a name and pick Database or Storage
- Click Create
Choosing data stores during app creation
You can also set up data store connections while creating a new app. The app creation dialog includes three options:- Built-in Neon database — enabled by default. Uncheck this if you plan to connect an existing data store instead, or if the app doesn’t need a database at all. When unchecked, the app starts with no
DATABASE_URL. - Connect existing data stores — a list of your org-level data stores appears with checkboxes. Selected stores are connected to the new app with admin access automatically.
- Create new data stores — add a name to provision a new database store alongside the app. The store is created at the org level and connected to the app in one step.
Each app with a built-in database shows a single data store with two branches — production
and sandbox — rather than two separate entries. This doesn’t change how the database works; it
just groups both environments under one store in the dashboard.
Deleting an app’s built-in database
If an app’s built-in Neon database is no longer needed, you can permanently delete it from the data store detail page.- Open Dashboard → Data Stores and click the app’s database store
- Click the red Delete database button in the header
- Type the store name to confirm
How the agent uses data stores
You don’t have to operate any of this yourself—the agent can do it for you. Here’s what it knows:- The agent sees every data store connected to your app and the access level you granted
- When it’s running in sandbox, it automatically operates on whichever branch you picked for sandbox in the Branch routing panel
- It can create tables, add columns, insert rows, and run queries—within the bounds of the access level
“Add a status column to the users table in my shared-db store.”
“Show me the last 10 orders from the shared-db store.”
“Create a new branch called experiment on the shared-db store.”
For that last one, the agent will create the branch for you, then tell you to open Branch routing and point sandbox at the new branch yourself.
FAQ
Q: What’s the difference between my app’s built-in database and a data store? A: The built-in per-app database is a legacy concept from before data stores existed. It’s private to one app, can’t be shared, and doesn’t support branch routing. Data stores replace it: they live at the organization level, can be connected to as many apps as you want, and support explicit access levels and branch-per-environment routing. New apps should use a data store from day one. Q: Can two apps read from the same data store at the same time? A: Yes. That’s the whole point—multiple apps can connect to the same data store and all see the same data. You control what each app can do with the access level. Q: Do data stores count toward my plan’s usage? A: Not yet. Data stores are free while the feature is in preview. Platform charges will come once data stores reach general availability—we’ll notify your organization before any billing starts. Once charges land, data stores will use the same underlying database and storage infrastructure as your apps and contribute to your overall usage; see Platform Costs for how that’ll be billed. Q: Can I delete a data store? A: Yes, but be careful—any app connected to it will lose access to its data. Disconnect the store from each app first, then delete it from the Data Stores dashboard. To delete an app’s own built-in database instead, see Deleting an app’s built-in database above. Q: Can I export data out of a data store? A: Ask the agent. A prompt like “export the orders table from my shared-db store as a CSV” will get you a downloadable file. Q: Do storage stores have branches like databases? A: No. Branches only exist on database stores. Every environment connected to a storage store sees the same files. Q: Can I move data between branches? A: The agent can copy rows from one branch to another. Ask it: “copy everything from theexperiment branch on my shared-db store over to main.”
Q: Can the agent undo a data store change for me?
A: Not via rewind — point-in-time restore is a user-initiated dashboard action. The agent can perform compensating writes (re-insert a deleted row, rerun a script that produced the wrong output), but if you want to roll the whole branch back to a previous moment, you do that yourself from the Rewind page.
Q: Can I turn my app’s built-in database into a full org-level data store?
A: Yes. From the data store’s settings, click Promote. After promotion: the underlying database is no longer deleted when the app is deleted, your app keeps a read-level connection to it (bump access from the app’s data store settings if you need more), and your app can no longer run schema migrations against it — migrations would affect any other consumers and are intentionally blocked. The action isn’t reversible from the dashboard; contact support if you need to undo it. See Connecting & routing for the full walkthrough.
Q: Can I create an app without a built-in database?
A: Yes. When creating a new app, uncheck the “Set up Neon database” option. The app starts with no database and no DATABASE_URL. You can connect an existing org-level data store during creation, or add one later from the app’s settings.
Q: Can I delete my app’s built-in database?
A: Yes. Open the data store’s detail page and click Delete database. This permanently destroys the underlying Neon database — all rows, schema, snapshots, and history are gone. Your deployed app loses its DATABASE_URL and any code reading from it will fail. If you later re-enable Neon on the app, you get a fresh empty database. See Deleting an app’s built-in database for more detail.
Data stores let you share real data across apps without copying it around—set up branches once, and each environment will read exactly what it should.