Connecting & routing
Connect a data store to an app, pick an access level, and route each environment to its own branch
Connect a store to an app, set its access level, route each environment to a branch, and browse data in the dashboard. New to data stores? Start with the Overview. For rollback, see History & rewind.
Connect a store to an app
- Open your app and go to Settings → Data Stores
- Click Connect, or Connect Existing if nothing is connected yet
- Pick the data store and choose an access level
Access levels
| Level | What the app can do |
|---|---|
| Read | Query data only—no additions, edits, or deletions |
| Write | Add, edit, and delete rows, but can't change the schema |
| Admin | Full control, including creating and altering tables |
Pick the lowest level that works. A storefront that only shows products needs Read.
Branches and environment routing
A database store can have several branches: independent copies of its tables and rows. Changes on one never touch another.
Under each connected database store in Settings → Data Stores, the Branch routing panel picks a branch per environment. It appears once the store has more than one branch. Default means the store's default branch, which is where every environment of a new app starts. See Environments.
| Environment | Example branch | What it means |
|---|---|---|
| Production | main | Real customers touch this data |
| Preview | main | Client-facing previews share production data |
| Sandbox | dev | Safe to experiment—agent changes land here |
When routing changes:
- Sandbox restarts and uses the new branch. If the agent is mid-task, the restart waits until it finishes.
- Preview and Production switch on the next deploy.
A common setup: production and preview on main, sandbox on dev. Schema changes made on dev reach main when you deploy to production; the deploy review lists them. Rows don't move. To copy data, ask the agent.
Non-production routes can be marked Read-only: the sandbox or preview reads that branch but can't write to it, so writes fail at the database. Use it to test against real data safely.
Your coding agent can read and change routing too: getProjectDataStoreEnvironments shows what each environment runs against, and setDataStoreEnvironmentMapping changes it.
Browsing and editing data
- Go to Dashboard → Data Stores → [your store]
- Use the branch picker at the top to choose which branch you're viewing
- The left sidebar lists every table—click one to open it
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
Deleting a table from the dashboard renames and hides it rather than dropping it. Support can recover it.
Storage stores
Open the store from Dashboard → Data Stores. Drag files in to upload, use New Folder, click a file for its download link, or select files and click Delete.
Storage stores have no branches. For files isolated per environment, use separate storage stores.
Promoting a project database to an org-level store
An app's own databases are stores owned by the app: admin access, can't be disconnected, deleted with the app. To share one with other apps, open the store, go to Settings → Danger zone, click Promote to org-level data store and type the store name.
After promotion:
- The original app keeps a read connection. Raise it in the app's data store settings if needed.
- The original app can no longer run schema migrations on it. Change the schema from the store dashboard.
- Deleting the original app no longer deletes the database.
- Any app in the org can connect to it.
Then move the app off the old connection string:
Find every reference to
process.env.DATABASE_URLin this app and move them to the Stardeck data store SDK (@stardeck-customer-apps/data-store-sdk), using the promoted store's name asstoreName. Update the drizzle config, the db client, and any server-side code that reads it. Don't touch references insidenode_modulesor generated migration files.
Not reversible from the dashboard. To undo, email support@stardeck.ai.
Production and sandbox are promoted separately. Most people promote only production so the agent can keep migrating sandbox.
Access for deployed apps
Every connected store reaches deployed apps, sandboxes and previews in one STARDECK_DATA_STORES environment variable: a JSON list of each store's id, name, slug and access level. @stardeck-customer-apps/data-store-sdk reads it and resolves a store by slug or id, so renaming a store doesn't break the app. See Environment Variables.
Troubleshooting
- Changed the sandbox branch, nothing happened. The restart waits for the agent to finish its task. A stopped sandbox picks up the branch on next start.
- Production still reads the old branch. Production and preview switch on the next deploy. Publish again.
- Want to try a schema change safely. Create a branch, route sandbox to it, and apply to
mainwhen ready. For a one-off, take a snapshot first instead. - Two apps need the same users. Connect one database store to both, with the lowest access level each needs.
Next
History & rewind
Snapshots and point-in-time restore for a database store