Skip to main content

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.

This page covers the operational side of data stores: how an app actually gets access to one, what the different access levels mean, how to route each environment to a different branch, and how to browse and edit the data directly from the dashboard. If you haven’t read Overview yet, start there—it explains what a data store is and when to reach for one. For rolling back changes, see History & rewind.

​
Connecting a store to an app

An app can’t use a data store until you explicitly connect it.
  1. Open your app and go to Settings
  2. Scroll to the Data Stores section
  3. Click Connect
  4. Pick the data store and choose an access level

​
Access levels

LevelWhat the app can do
ReadQuery data only—no additions, edits, or deletions
WriteAdd, edit, and delete rows, but can’t change the schema
AdminFull control, including creating and altering tables
Pick the lowest level that still lets the app do its job. A customer-facing app that only displays products is safer with Read. An admin tool that manages inventory needs Write or Admin.
If your app was created before data stores existed, you’ll see its built-in database listed here with Admin access. It’s always connected and can’t be disconnected—this is the legacy per-app database. New apps won’t have this entry.

​
Branches and environment routing

This is the most important concept to understand, so take a minute with it. A database store can have multiple branches—think of them as independent copies of your data, similar to git branches for code. Each branch has its own tables and its own rows. Changes on one branch never touch another. When you connect a database store to an app, you decide which branch each environment reads from. Open Settings → Data Stores and you’ll see a Branch routing panel under each connected database store, with three dropdowns:
EnvironmentExample branchWhat it means
ProductionmainReal customers touch this data
PreviewmainClient-facing previews share production data
SandboxdevSafe to experiment—agent changes land here

​
What happens when you change routing

  • Sandbox — your sandbox restarts automatically so the new branch takes effect immediately
  • Preview and Production — the change takes effect on your next deploy
If the agent is in the middle of working when you change the sandbox branch, the restart is queued until the agent finishes. You’ll see a notification letting you know. This prevents the agent from being cut off mid-task.
A common setup: keep production and preview on main, and point sandbox at a dev branch. Now when the agent makes schema changes or experiments with data in sandbox, none of it touches your live customers. When you’re happy with what’s on dev, you can ask the agent to replicate the changes on main.

​
Browsing and editing data

For database stores, the dashboard gives you a full view of your tables without touching any code.
  1. Go to Dashboard → Data Stores → [your store]
  2. Use the branch picker at the top to choose which branch you’re viewing
  3. The left sidebar lists every table—click one to open it
From here you can:
  • Create tables and columns with rich field types: text, number, date, boolean, select, multi-select, url, email, phone, currency, rating, relation, file reference, and JSON
  • Sort by any column
  • Filter rows with conditions like “equals”, “contains”, “is null”
  • Insert, edit, and delete rows individually
  • Paginate through large tables
When you delete a table from the dashboard, Stardeck soft-deletes it—the table is renamed and hidden rather than dropped. If you ever delete something by mistake, reach out to support and we can recover it.

​
Storage stores

Storage stores work a little differently because they hold files rather than rows.
  1. Go to Dashboard → Data Stores → [your storage store]
  2. You’ll see a folder tree on the left and a file list on the right
  3. Drag and drop files to upload them, create folders with New Folder, and click a file to open its detail panel with a download link
  4. Select files with the checkboxes and click Delete to remove them
Storage stores are a great fit for uploaded files you want to manage yourself—product photos, customer PDFs, downloadable assets—without writing any code to handle uploads.
Storage stores don’t have branches. Every environment connected to a storage store sees the same files. If you need environment-isolated files, use separate storage stores.

​
Promoting an app database to an org-level store

Every app that uses Neon has its built-in databases (production and sandbox) automatically wrapped as data stores so you can browse them from the dashboard. By default these are owned by their app — they’re listed with admin access in the app’s data store settings, they can’t be disconnected, and they’re deleted along with the app. If an app’s database has grown into something more than one app should be able to read, you can promote it from the data store’s settings page. Click Promote in the header next to the Branches and Rewind buttons, type the store name to confirm, and the wrapper becomes a real org-level data store. After promotion:
  • The originating app keeps a read connection via an explicit data_store_connections entry. Bump it to write or admin from the app’s data store settings if you need to.
  • The originating app can no longer run schema migrations against this database. Schema changes become your responsibility from the data store dashboard.
  • Deleting the originating app no longer deletes the underlying database. That’s the whole point — the data outlives the app that created it.
  • Your app’s DATABASE_URL references will need to be updated. The promoted store is injected under a new env var name. See the warning below for the rewrite.
  • You can connect any other app in your org to the promoted store from the app’s settings, just like any standalone store.
Your app’s DATABASE_URL references will break. Before promotion, your deployed app and sandbox receive the database connection string in process.env.DATABASE_URL. After promotion, the connection is injected as a data store env var instead — under a name derived from the data store’s display name, e.g. DATA_STORE_MY_APP__PRODUCTION_URL. Any code that reads process.env.DATABASE_URL directly (your drizzle config, your db client, server actions, etc.) will see undefined until you switch the references over.
After promoting, ask the agent to do the rewrite for you. A prompt that works well:
Find every reference to process.env.DATABASE_URL in this app and switch them to process.env.DATA_STORE_<MY_STORE_NAME>_URL (the env var name from my newly-promoted data store — check the data store dashboard for the exact name). Update the drizzle config, the db client, and any server-side code that reads it. Don’t touch references inside node_modules or generated migration files.
If you want the env var to land at a name you choose, rename the data store before promoting it. The store’s display name (uppercased, non-alphanumerics replaced with _) becomes the env var prefix. Renaming “MyApp (production)” to “myapp-db” will give you DATA_STORE_MYAPP_DB_URL, which is shorter and easier to type than the default.
Promotion is not reversible from the dashboard. If you need to undo it, email support@stardeck.ai. Take a moment to make sure you actually want the database detached from the app lifecycle before you confirm.
Production and sandbox are promoted independently — each is its own data store wrapper. Most users only promote production; sandbox usually stays with the app so the agent can keep running migrations against it freely.

​
Access for deployed apps

You don’t have to wire anything up manually. When you connect a data store to an app, Stardeck automatically makes the connection details available to your deployed app as environment variables. The agent uses them when it writes code that reads from or writes to the store, so you never need to copy a connection string. See Environment Variables for more on how environment variables work in Stardeck.

​
Common scenarios

​
”I want my admin app and my customer app to share the same users”

Create a database store (e.g. shared-users), connect it to both apps, and give the admin app Admin access and the customer app Write access. Ask the agent to read and write users from the shared store instead of the built-in app database.

​
”I want to try a schema change without breaking production data”

Create a new branch on your database store—say, experiment. Point your sandbox at that branch in the Branch routing panel. Now the agent can add, remove, or rename tables in sandbox without touching the main branch that production reads from. When you’re ready, ask the agent to apply the same changes to main.
For a less-involved safety net, take a snapshot of the branch before the risky change and restore it if things go sideways. Branches are better for longer-lived experiments; snapshots are better for one-shot “let me try this” moments.

​
”I want to keep uploaded PDFs in one place and view them in the dashboard”

Create a storage store, connect it to your app with Write access, and ask the agent to save uploads there. You’ll be able to browse every uploaded file right from the dashboard without writing any admin UI.

​
”I changed the sandbox branch and nothing seems to have happened”

Check two things: is the sandbox actually running, and was the agent in the middle of a task when you made the change? If the agent was busy, the restart is queued until it finishes. If the sandbox wasn’t running, it’ll pick up the new branch the next time you start it.

​
”My production app still reads the old branch after I changed routing”

Production and preview only pick up branch routing changes on the next deploy. Publish a new production deploy from the dashboard and it’ll start reading the branch you selected.