Overview

A data store lives at the organization level. Create it once, then connect it to any app in the org under the access level you choose.

Every new app gets its own stores when you create it. Connect a store to a second app when both need the same data, such as one customer list for a POS and a booking app.

Next: Connecting & routing to wire a store into an app, History & rewind for snapshots and restore.

How it fits togetherCopy Anchor Link

flowchart TB
    Org["🏢 Your Organization"]
    Store[("🗄️ Data Store<br/>shared-db")]
    Org --> Store

    Store -->|"branch"| Main["🌿 main<br/><i>live data</i>"]
    Store -->|"branch"| Dev["🌿 dev<br/><i>experiments</i>"]

    ProjA["📱 POS App"]
    ProjB["📱 QR Ordering"]
    ProjC["📱 Back-office"]

    Main -.->|"production • read/write"| ProjA
    Main -.->|"production • read"| ProjB
    Main -.->|"production • admin"| ProjC
    Dev  -.->|"sandbox"| ProjA
    Dev  -.->|"sandbox"| ProjB
    Dev  -.->|"sandbox"| ProjC

Each connected app has an access level (read, write or admin) and routes each environment to a branch. In this example the sandboxes work on dev while production reads main. A new app starts with every environment on the default branch, so its sandbox and production share data until you route the sandbox elsewhere. See Environments.

Usage and billingCopy Anchor Link

Data stores count toward your plan's database and file storage allowances. The organization's usage page shows the average GB held across all stores this month against the plan allowance. See Platform Costs for allowances and add-ons.

Create a data storeCopy Anchor Link

1. Go to Dashboard → Data Stores and click New Data Store
2. Name it, pick Database or Storage, and click Create

Nothing connects automatically. See Connecting & routing.

Stores created with a new appCopy Anchor Link

The Data stores section of the Create New App form lists each store a new app needs, labelled New, from and the store's name. Each row creates an empty store with the app's schema; you can rename it there. Add more stores later.

Each new store has one branch, and the app's sandbox, previews and production all use it. To keep test data out of the live app, give the sandbox its own branch.

Older apps that have their own production and sandbox databases show them in the dashboard as one store with two branches.

Delete an app databaseCopy Anchor Link

1. Open the app's database store from Dashboard → Data Stores
2. Go to Settings → Danger zone, click Delete database and type the store name

What your agent can doCopy Anchor Link

Your coding agent works with stores through the Stardeck MCP server, and Starcat Developer does the same from the Build tab. Within the app's access level, an agent can:

• See every store connected to the app and its access level
• Work on the branch routed to the sandbox
• Create tables, add columns, insert rows and run queries
• Create branches and route an environment to one (createDataStoreBranch, setDataStoreEnvironmentMapping)

Snapshots and point-in-time restore are dashboard-only, from the Rewind page. The agent can make compensating writes instead.

Example prompts:

"Add a status column to the users table in my shared-db store."

"Show me the last 10 orders from the shared-db store."

Store page toolsCopy Anchor Link

Open a store from Dashboard → Data Stores:

Apps read and write stores through @stardeck-customer-apps/data-store-sdk.

FAQCopy Anchor Link

Must I pick data stores when creating an app? No. Creation sets up only the stores a new app needs. Connect others later under the app's Settings → Data Stores.

Can I delete a data store? Yes. Disconnect it from every app first, then use Settings → Danger zone on the store.

Do storage stores have branches? No. Every environment sees the same files.

Can I move data between branches? Ask the agent to copy rows, e.g. "copy everything from the experiment branch on shared-db to main."

Can I turn an app's database into an org-level store? Yes, with Promote to org-level data store under Settings → Danger zone. The app can then no longer run schema migrations against it, and the database outlives the app. Not reversible from the dashboard. Read Promoting a project database first.