# dabadata

> dabadata hosts whole apps for people and their AI agents: plain Postgres underneath, tables and access rules declared as one JSON definition, a sentence explaining every allow or deny, a trace of every read and write, live subscriptions over one socket, hosted sign-in for an app's own users, file storage, the app's frontend at <name>.dabadata.site or its own domain, AI calls in actions, and a hosted MCP server per project so agents can build the app and people can use it inside ChatGPT and Claude with interactive widgets.

The hosted service is at https://dabadata.com (API at https://dabadata.com/v1, console at https://dabadata.com/console/, docs at https://dabadata.com/docs/, MCP at https://dabadata.com/mcp/<project id>). Every page below is plain markdown; https://dabadata.com/llms-medium.txt is every page in brief (its sections and their first paragraphs), https://dabadata.com/llms-full.txt is all of them in one file, and https://dabadata.com/v1/openapi.json describes every HTTP route (OpenAPI 3.1). Every feature is listed on https://dabadata.com/docs/features/index.md.

## Start here

1. Sign up at https://dabadata.com/console/ (free, no card). You get a workspace and a project `my-first-app` with a live and a test environment. Build on **test** first.
2. In the console open **Keys** and copy the environment's publishable key (`pk_test_...`, safe in a browser) and its secret key (`sk_test_...`, server only: it bypasses every rule; it is shown once - press Rotate to get a new one). Keep them in `.env` as `DABADATA_URL=https://dabadata.com`, `DABADATA_PUBLISHABLE_KEY`, `DABADATA_SECRET_KEY`. Never put the secret key in browser code.
3. Define the tables and rules: `PUT https://dabadata.com/v1/schema` with `Authorization: Bearer <secret key>` and `{ "definition": { "roles": [...], "tables": { ... } }, "dryRun": true }` first - it answers the plan (`create table x`, `add column x.y`) and changes nothing - then the same body without `dryRun` to apply it. Applying only adds tables and columns, never drops. Every table needs an explicit `read` rule; rules are `"anyone" | "authenticated" | "nobody" | { "role": [...] } | { "owner": "<userId column>" } | { "any": [...] } | { "all": [...] }`.
4. Connect from the app: `createClient({ url, key, token })` from https://dabadata.com/client/dist/dabadata.js (ES module) or `dabadata.iife.js` (script tag) - `url` = https://dabadata.com, `key` = the publishable key, `token` = the signed-in user's token. Then `db.insert`, `db.update`, `db.delete`, `db.query`, `db.subscribe` (live rows).
5. Write safely: for anything read-modify-write use atomic operators (`db.update("products", id, { stock: db.dec(1) })`, `{ "$inc": n }`, `$dec`, `$min`, `$max`, `$append`, `$remove`), conditional writes (`expect`, `ifAbsent`) or `POST /v1/transact` / `db.transact([...])` (all or nothing, serializable, retried). Never read a counter or a stock level and write back the computed value: concurrent users lose updates. Add `unique` columns and `checks` (e.g. `stock >= 0`) to the definition.
6. Users: either mint user tokens on your server (`POST /v1/users/token` with the secret key, body `{ "id", "name", "role" }` -> `{ token, refreshToken }`), trust your identity provider's JWTs (`auth.issuers`), or enable hosted end-user accounts (`auth.users: { enabled: true, defaultRole: "member" }`) and use `db.auth.signUp` / `signIn` with the publishable key.
7. Connect the MCP server: add `"mcp": { "enabled": true }` to the definition, then `claude mcp add --transport http dabadata https://dabadata.com/mcp/<project id> --header "Authorization: Bearer <secret key>"` (use `<project id>_test` for the test environment). Call `describe_app` first; `apply_definition` (with `dryRun`), `widget_put`, `trace_recent` and `simulate` build and debug the app. https://dabadata.com/docs/agents/index.md has the whole setup, including ChatGPT and Claude connectors.

When something is refused, read the error: a denial carries `explanation` (the rule that decided, in words) and a `traceId`; `GET /v1/trace` (or the MCP tool `trace_recent`) shows every call with its decision.

When someone shows you a screenshot of the console, https://dabadata.com/docs/console/index.md#screenshots says how to tell the page, the environment and the role from it, what each page's states mean and what to tell them to do next.

## Features

Every capability, grouped; https://dabadata.com/docs/features/index.md has each one with a sentence and a link to its page.

- [Data and schema](https://dabadata.com/docs/features/index.md#data): Tables, columns and constraints are declared in one definition and kept as plain Postgres tables; applying a definition only ever adds, with a dry run, versions and rollback.
- [Rules and access](https://dabadata.com/docs/features/index.md#rules): One rule per operation per table, written as data, with row conditions, time, column rules, relations, actions (which may call Claude, OpenAI or Gemini with your key) and strict tables; every decision comes with a sentence that explains it.
- [Views and joins](https://dabadata.com/docs/features/index.md#views): Declared, read-only views give each role its own shape of a table, with params, computed fields and joined rows, over HTTP, the client, live subscriptions and MCP.
- [Live data](https://dabadata.com/docs/features/index.md#live): Live subscriptions keep queries and views up to date over one socket, shaped for each subscriber by the same rules, including changes that happen by time.
- [Safe concurrent writes](https://dabadata.com/docs/features/index.md#writes): Atomic operators, conditional writes, serializable transactions, constraints and actions make the safe write the short one, so concurrent users never lose updates.
- [Sign-in for your app's users](https://dabadata.com/docs/features/index.md#auth): Hosted accounts with email, sign-in links and social providers, or your own identity provider's JWTs, or tokens your backend mints, or anonymous access; all of them reach the same rules.
- [File storage](https://dabadata.com/docs/features/index.md#storage): Buckets of files for your app's users with the same rules, trace and live updates as rows, uploaded straight to object storage.
- [Sites](https://dabadata.com/docs/features/index.md#sites): Host your app's static frontend next to its data at `<name>.dabadata.site`, or your own domain from Starter, deployed by the CLI, the console or an AI agent.
- [AI agents, MCP and apps in ChatGPT and Claude](https://dabadata.com/docs/features/index.md#agents): Docs written for agents, a hosted MCP server per environment for coding agents (Claude Code, Cursor) and for people inside ChatGPT and Claude, live widgets, templates and a local stdio server.
- [Console, CLI and teams](https://dabadata.com/docs/features/index.md#console): A web console and a command-line tool for the people who build with dabadata, with workspaces, roles, invitations and an audit log.
- [Trace, logs and debugging](https://dabadata.com/docs/features/index.md#trace): Every mutation, read and subscription is recorded with who did it, the rule, the decision and why; request and realtime logs sit beside it.
- [API, client and protocol](https://dabadata.com/docs/features/index.md#api): A JSON HTTP API under `/v1` with one WebSocket, a zero-dependency JavaScript client, OpenAPI 3.1, and a wire protocol written for SDK authors.
- [WordPress plugin](https://dabadata.com/docs/features/index.md#wordpress): A WordPress plugin connects a site to a project, maps WordPress users and roles to it, and puts live tables on pages.
- [Self-hosting](https://dabadata.com/docs/features/index.md#self-hosting): Run the whole of dabadata on your own machine or server, over your own Postgres, with the same API as the hosted service.
- [Plans and limits](https://dabadata.com/docs/features/index.md#plans): Plans are per workspace (Free, Starter, Pro, Scale, Enterprise), never per seat or per read; nothing is charged during the beta, and every limit is a hard cap unless the owner opts into overages.
- [Not built yet](https://dabadata.com/docs/features/index.md#not-built): Missing or planned today: server functions (your own code), left joins in views, more sign-in providers, sign-in on your own domain, live changes from writes made directly in Postgres, client libraries beyond JavaScript, and offline sync, push notifications, phone sign-in and multi-factor.

## Docs: start

- [What dabadata is](https://dabadata.com/docs/index.md): dabadata hosts your whole app: plain Postgres underneath, declared tables, sign-in, file storage, your frontend on your own domain, AI calls, rules with an explanation on every decision, a trace of every interaction, live subscriptions and an MCP server.
- [Features](https://dabadata.com/docs/features/index.md): Every dabadata feature on one page: declared Postgres tables, rules with explanations, views and joins, live subscriptions, safe concurrent writes, hosted sign-in, file storage, sites, MCP and ChatGPT / Claude apps, console, trace, API, WordPress, self-hosting and plans - and what is not built yet.
- [Getting started](https://dabadata.com/docs/getting-started/index.md): Sign up for hosted dabadata, copy your keys, paste the HTML snippet, watch your first live row arrive and put your app online.
- [Build with an AI agent](https://dabadata.com/docs/agents/index.md): One link for your AI agent: llms.txt, the docs as markdown, OpenAPI, the hosted MCP server for Claude Code, Cursor, ChatGPT and Claude, the prompt to paste, safe writes, templates and a worked example.
- [The console](https://dabadata.com/docs/console/index.md): The dabadata console: workspaces and projects, live and test, every page (Overview, Definition, Tables, Files, Sites, SQL, Trace, Logs, Rules, Views, Playground, Apps, Authentication, Keys, Secrets, Members, Usage and plan, Settings), reading a screenshot of it, roles, and plans in the beta.
- [Accounts and teams](https://dabadata.com/docs/accounts/index.md): Console accounts and teams in dabadata: sign in with a password, an email link or Google, sessions, invitations and seats, transferring a workspace, the audit log and account security.

## Docs: concepts

- [Tables](https://dabadata.com/docs/tables/index.md): How dabadata tables are declared: the definition (JSON on a hosted project, a project file when self-hosted), column types and options, constraints, ref deletes, implicit columns, names and what applying a definition does.
- [Rules](https://dabadata.com/docs/rules/index.md): The dabadata rule grammar: roles, owners and row conditions with $now, column read rules, validation, how read rules become a row filter, explanations, the simulator, column rules, actions, strict tables and views.
- [Views](https://dabadata.com/docs/views/index.md): Declared views in dabadata: a named, read-only shape of one table - rows, columns, computed flags, params, per-role shapes and joined rows of other tables - read with the server's rights over HTTP, the client, live subscriptions and MCP.
- [Access patterns](https://dabadata.com/docs/access-patterns/index.md): Worked dabadata access examples: friends' score predictions revealed at kick-off, the same predictions in strict mode, drafts, scheduled content, secret columns, per-role shapes, a leaderboard and mixed projects - with what each role sees, live behaviour and pitfalls.
- [AI calls in actions](https://dabadata.com/docs/ai/index.md): dabadata AI calls in actions: call Claude (Anthropic), OpenAI or Gemini (Google) from a declared action with your API key kept as an encrypted project secret, no server of your own. The ai block, prompt placeholders, waiting or saving the answer to a row, responses, limits, errors, trace and security.
- [Identity and tokens](https://dabadata.com/docs/identity/index.md): The four kinds of dabadata caller - project key, user token, view token and anonymous - what each may do, how long tokens last, bringing your own identity provider, and where the project key belongs.
- [Sign-in for your app's users](https://dabadata.com/docs/end-user-auth/index.md): Hosted sign-in for your app's own users: enable auth.users, the /v1/auth/users routes, hosted pages, redirect URLs and app mode, db.auth in the JavaScript client with a complete example, managing users and rate limits.
- [Sign in with Google, Apple and more](https://dabadata.com/docs/sign-in-providers/index.md): Social sign-in for your app's users through your own OAuth apps: Google, Apple, Microsoft, GitHub, GitLab, Discord, LinkedIn and Slack. Setup at each provider, callback URLs, native apps with ID tokens, db.auth.signInWithProvider, account linking, errors and limits.
- [Projects and keys](https://dabadata.com/docs/projects/index.md): Hosted dabadata projects: the project id, live and test environments, publishable and secret keys, how a call finds its project, key rotation, allowed origins, export and project secrets.
- [Plans and limits](https://dabadata.com/docs/limits/index.md): The plan limits of hosted dabadata projects (Free, Starter, Pro, Scale, Enterprise) - connections, storage, egress, retention, request rate - what each call gets back at a limit, usage metering and the nightly job.
- [Billing](https://dabadata.com/docs/billing/index.md): How dabadata bills a workspace: free during the beta; when on, Stripe checkout, the customer portal, opt-in overages and failed payments.
- [Trace](https://dabadata.com/docs/trace/index.md): The dabadata trace - one row per mutation, read and subscription, with who did it, the rule, the decision, the explanation and the fan-out.
- [Live subscriptions](https://dabadata.com/docs/live/index.md): Live subscriptions in dabadata over one WebSocket - subscribe, rows, change, unsubscribe and errors - how updates and deletes reach subscribers, and how the client reconnects.
- [Safe concurrent writes](https://dabadata.com/docs/concurrency/index.md): Lost updates and how dabadata prevents them: atomic operators, conditional writes, serializable transactions and constraints, with measured results.
- [File storage](https://dabadata.com/docs/storage/index.md): dabadata file storage: buckets of files for your app's users (avatars, attachments, documents) with rules, trace and live updates: signed uploads straight to object storage, downloads, limits and the client API.
- [Sites](https://dabadata.com/docs/sites/index.md): dabadata Sites host your app's static frontend next to its data: a site at name.dabadata.site on every plan and your own domain from Starter. Deploy with the CLI or an AI agent, single-page apps, caching, rollback, custom domains and limits.
- [Webhooks](https://dabadata.com/docs/webhooks/index.md): Outbound webhooks: tell your own server (Vercel, Cloudflare Workers, any HTTPS endpoint) when rows change or actions run - Standard Webhooks signatures, retries, a delivery log with send again, and monthly allowances.
- [Scheduled actions](https://dabadata.com/docs/schedules/index.md): Scheduled actions: run one of your declared actions on a UTC cron - nightly cleanups, digests, rollups - with no cron job or server of your own; every run traced.
- [Call dabadata from your backend](https://dabadata.com/docs/backend/index.md): Call dabadata from Vercel, Cloudflare Workers or any server: forward a user token, use a restricted key for backend jobs, and receive webhooks for changes - which credential goes where.

## Docs: reference

- [HTTP API](https://dabadata.com/docs/api/index.md): Every dabadata endpoint - who may call it, the request, the response and the error codes - including the definitions and project API of hosted projects, the error body shape and CORS.
- [JavaScript client](https://dabadata.com/docs/client/index.md): The zero-dependency dabadata JavaScript client - loading it, createClient options (url, key, tokens, storage), db.auth for hosted sign-in, insert, update, delete, query, subscribe, errors and connection status.
- [Wire protocol](https://dabadata.com/docs/protocol/index.md): The dabadata wire protocol for SDK authors: HTTP basics, credentials and placement, token refresh timings, data routes, the /v1/live socket, the Centrifugo transport and recovery, end-user sign-in, errors, and the conformance suite.
- [MCP server](https://dabadata.com/docs/mcp/index.md): The hosted dabadata MCP server - turning it on with the mcp block, credentials and toolsets, tools, live widgets in ChatGPT and Claude, custom widgets - and the local stdio server for self-hosting.
- [WordPress plugin](https://dabadata.com/docs/wordpress/index.md): The dabadata WordPress plugin - connect a site to a project, WordPress users as project users, the Live table block and shortcode, privacy, and the mirror of the site's content changes.
- [Self-hosting](https://dabadata.com/docs/self-hosting/index.md): Run the whole of dabadata - API, viewer, site, docs and the live demo - on your own machine or server with one docker compose command or from a checkout with Bun, on your own Postgres.

## Machine-readable

- [OpenAPI 3.1](https://dabadata.com/v1/openapi.json): every /v1 route with its credentials, request and response shapes
- [All docs in brief](https://dabadata.com/llms-medium.txt): every page above with its description and each section's first paragraph
- [All docs in one file](https://dabadata.com/llms-full.txt): every page above, in order, as markdown
- [Templates](https://dabadata.com/v1/templates): curated starting points (definition + widgets), public JSON

## Optional

- [Pricing](https://dabadata.com/pricing/): plans and their limits
- [Live demo](https://dabadata.com/demo/): two people on one database, with the trace underneath
- [JavaScript client bundle](https://dabadata.com/client/dist/dabadata.js): ES module; `dabadata.iife.js` for a script tag