# teenybase

> teenybase is a teeny tiny Supabase for your own Cloudflare account: an open-source (Apache-2.0) backend framework for Cloudflare Workers and D1. You define tables, fields, auth, access rules and actions in one TypeScript file, `teenybase.ts`, and teenybase turns it into a REST API with OpenAPI docs, generated SQL migrations, auth endpoints and an admin panel.

teenybase is early (v0.1): APIs may change before 1.0. The `teenybase` npm package ships the CLI (run it as `npx teenybase <command>`; after `npm i -g teenybase` the short name `teeny` works too). Never run `npx teeny`: that downloads an unrelated npm package. Coding agents can read the bundled docs and skills offline with `npx teenybase docs` and `npx teenybase skills`.

Every docs page below links to its Markdown version (the page URL with `.md`). All docs in one file: [llms-full.txt](https://teenybase.com/llms-full.txt).

**Get started** (Node.js 22 or newer; no Cloudflare account needed to run locally):

```
npx teenybase create my-app --yes
cd my-app
npx teenybase deploy --local --yes
npx teenybase dev
```

The API runs at `http://localhost:8787/api/v1`, with Swagger UI at `/api/v1/doc/ui` and the admin panel at `/api/v1/pocket/`. To deploy to your own Cloudflare account, run `npx wrangler login`, then `npx teenybase deploy --remote --yes`. With no Cloudflare account, `npx teenybase deploy --temporary --yes` deploys to a temporary Cloudflare account without a login and prints the live URL and a claim link: claim it within 60 minutes to keep it, otherwise Cloudflare deletes it with its data.

**What you get:**

- **One config file:** schema, auth, access rules, actions and extensions live in `teenybase.ts`, with full TypeScript types.
- **Migrations by diffing the config:** `npx teenybase generate` compares your config with the last applied state and writes the SQL migration (`deploy` runs it for you).
- **Access rules compile to SQL:** rules like `auth.uid == owner_id` are parsed and compiled to parameterized SQL `WHERE` clauses. A table with no rules is denied until you add rules or mark it `public: true`.
- **REST API and OpenAPI:** CRUD endpoints for every table (select, list, view, insert, update, edit, delete), an OpenAPI 3.1 spec and Swagger UI.
- **Auth:** email and password with JWTs and refresh tokens, email verification and password reset, OAuth (Google, GitHub, Discord, LinkedIn).
- **File uploads:** file fields stored in Cloudflare R2.
- **Admin panel:** a data browser at `/api/v1/pocket/`, a fork of the PocketBase admin UI.
- **Full-text search:** SQLite FTS5.
- **Your data:** it lives in Cloudflare D1 (SQLite) in your account; `npx teenybase backup` exports schema and data as SQL (remote export is blocked for databases with FTS5 tables, a Cloudflare limitation).
- **Cost:** teenybase is free. You pay Cloudflare directly for Workers, D1 and R2 usage; the Workers free plan is enough to start.

**Limits:** Cloudflare D1 is the only database the CLI and migrations support today. A D1 database is capped at 10 GB (500 MB on the free plan) and has a single primary location. There are no realtime subscriptions: the API is REST only.

**How it compares:**

- **Supabase** is a Postgres platform (hosted or self-hosted) where access control is written as SQL policies and schema usually lives in its dashboard or SQL migrations. teenybase keeps schema, auth and rules in a TypeScript file in your repo and runs on your Cloudflare account. Supabase is the better fit for Postgres features, realtime and a larger ecosystem.
- **Firebase** is a proprietary Google Cloud service with a document database. teenybase is open source and relational (SQLite), and your data can be exported as SQL. Firebase is the better fit for realtime sync and mobile SDKs.
- **PocketBase** also puts schema, auth and rules in one place with an admin UI (teenybase's admin UI is a fork of it). PocketBase is a single Go binary you host yourself, manages schema in its admin UI and has realtime; teenybase is config-as-code in TypeScript on Cloudflare Workers with no server to manage. PocketBase is more mature.

## Getting Started

- [What is teenybase?](https://teenybase.com/docs/index.md): teenybase turns one TypeScript file into a REST API, auth, access rules, migrations and an admin panel on Cloudflare Workers and D1, in your own account.
- [Quickstart](https://teenybase.com/docs/getting-started/quickstart.md): Create a teenybase project, run it locally with no Cloudflare account, add a table, call the API with curl, then deploy it to your own Cloudflare account.
- [Agent Quickstart](https://teenybase.com/docs/getting-started/quickstart-agent.md): One page to paste into Claude Code, Cursor or Codex: how to run the teenybase CLI, set up a project, write teenybase.ts, test locally and deploy.
- [Add teenybase to an Existing Project](https://teenybase.com/docs/getting-started/existing-project.md): Add a teenybase backend to an app you already have: npx teenybase create backend scaffolds a self-contained backend folder you run and deploy on its own.
- [Getting Started (full guide)](https://teenybase.com/docs/getting-started.md): From an empty folder to a local teenybase API you can call with curl, then a deploy to your Cloudflare account, for a new or an existing project.
- [Why teenybase](https://teenybase.com/docs/why-teenybase.md): What teenybase replaces, who it is for, when not to use it, and how it compares with Supabase, Firebase and PocketBase.

## Guides

- [Connect Your Frontend](https://teenybase.com/docs/guides/frontend.md): A drop-in fetch client for a teenybase API with token refresh, plus copy-paste sign-up, login, protected request and CRUD examples.
- [Google Sign In (Custom Frontend)](https://teenybase.com/docs/guides/google-oauth-custom.md): Add a “Continue with Google” button with the OAuth redirect flow: Google Cloud credentials, secrets, authProviders config and the auth cookie.
- [Google One Tap / SPA](https://teenybase.com/docs/guides/google-oauth-onetap.md): Add Google One Tap or SPA sign-in to teenybase: Google gives the browser a credential and your frontend sends it to teenybase to sign the user in.
- [Row-Level Security (RLS)](https://teenybase.com/docs/guides/rls.md): teenybase rules are row-level security: expressions like auth.uid == owner_id that compile to SQL WHERE clauses, with patterns for common access cases.
- [Actions](https://teenybase.com/docs/guides/actions.md): Define server-side actions in teenybase.ts and call them at POST /api/v1/action/{name}: counters, transactions, aggregations, in SQL or steps mode.
- [File Uploads](https://teenybase.com/docs/guides/file-uploads.md): Store images, PDFs and other files in Cloudflare R2 from teenybase records: the file field, the R2 binding, and uploads from the browser and curl.
- [Email Verification & Password Reset](https://teenybase.com/docs/guides/email-flows.md): Set up outgoing email for teenybase auth and test password reset and email verification end to end, locally with mock email and after deploy.
- [Deployment Checklist](https://teenybase.com/docs/deployment-checklist.md): The steps from a working local teenybase app to production on your Cloudflare account: wrangler login, secrets, first deploy, appUrl, pre-launch checks.
- [Frontend Guide (full)](https://teenybase.com/docs/frontend-guide.md): Call a teenybase REST API from React, Vue, Svelte, plain JS or mobile: base URL, auth flow, CRUD, file uploads, query parameters, errors, CORS and OAuth.
- [Add teenybase to a Hono + Workers Project](https://teenybase.com/docs/existing-hono-project.md): Integrate teenybase into an existing Hono app on Cloudflare Workers by hand: install, D1 binding, config, path alias and the worker entry point.
- [Google Sign In: Pick a Flow](https://teenybase.com/docs/google-oauth.md): Compare teenybase's two Google sign-in flows, OAuth redirect and One Tap / SPA, then follow the shared Google Cloud, secrets and config setup.
- [OAuth & Google Login](https://teenybase.com/docs/oauth-guide.md): Configure Google One Tap, the OAuth2 redirect flow (Google, GitHub, Discord, LinkedIn) and bearer token login in teenybase, with cookie-based auth.

## Recipes

- [Recipe: Full CRUD App with Auth](https://teenybase.com/docs/recipes/full-app.md): A complete teenybase.ts and SSR worker: sign-up and login, public and private items, full-text search, file uploads, actions, email and OAuth.
- [Recipe: Counter / View Tracker](https://teenybase.com/docs/recipes/counter.md): Count page views or clicks in teenybase: mark the counter field noUpdate so CRUD cannot change it, and increment it through an action.
- [Recipe: Multi-Table Blog](https://teenybase.com/docs/recipes/blog.md): A teenybase blog schema with posts, comments and tags: relations, indexes, cascading deletes, and rules that show published posts and keep drafts private.
- [Recipe: Full-Text Search](https://teenybase.com/docs/recipes/full-text-search.md): Add full-text search to a teenybase table with SQLite FTS5: configure the indexed fields, then query with the @@ operator.
- [Recipe: File Upload Gallery](https://teenybase.com/docs/recipes/file-gallery.md): An image gallery on teenybase: upload images with metadata to R2, serve them back, and delete the files when the record is deleted.
- [Recipe: Soft Delete](https://teenybase.com/docs/recipes/soft-delete.md): Mark teenybase records as deleted instead of removing them, for audit trails, undo or retention, and hide them from normal reads with rules.
- [Recipe: User Preferences (Upsert)](https://teenybase.com/docs/recipes/upsert.md): Store per-user settings in teenybase with upsert: the edit/:id endpoint with or: 'INSERT' creates the row if it is missing and updates it if it exists.
- [Recipe: Key-Value Store](https://teenybase.com/docs/recipes/key-value-store.md): A settings or feature-flag table in teenybase with manual IDs, where the key is the record id.
- [Recipe: Aggregation Dashboard](https://teenybase.com/docs/recipes/aggregation.md): Run aggregate SQL in teenybase actions, such as monthly signups, daily counts and totals, which the CRUD endpoints cannot do.
- [Recipe: Leaderboard with Ranking](https://teenybase.com/docs/recipes/leaderboard.md): Top N users by score with rank numbers in teenybase, using a ROW_NUMBER() window function in a raw SQL action.
- [Recipe: Cascading Delete](https://teenybase.com/docs/recipes/cascading-delete.md): Delete a user and their posts, comments and files in teenybase with onDelete: 'CASCADE' foreign keys.
- [Recipe: Email Verification Flow](https://teenybase.com/docs/recipes/email-verification.md): Sign up, verify the email address and log in with teenybase's built-in auth extension and an email provider.
- [Recipe: Rate Limiting (Manual)](https://teenybase.com/docs/recipes/rate-limiting.md): teenybase has no built-in rate limiting yet. This workaround splits a public endpoint into a check action and a work action.
- [Recipe: Scheduled Cleanup](https://teenybase.com/docs/recipes/scheduled-cleanup.md): Delete expired teenybase records on a schedule by calling an action from an external cron: GitHub Actions, cron-job.org or a Workers Cron Trigger.
- [Recipes & Patterns](https://teenybase.com/docs/guides/recipes.md): Copy-paste teenybase configs and API calls for common patterns: counters, soft delete, RBAC, blogs, uploads, upsert, search, leaderboards and more.

## Reference

- [Configuration Reference](https://teenybase.com/docs/reference/config-reference.md): Every option in teenybase.ts: DatabaseSettings, tables, field types, the auth and rules extensions, scaffolds, indexes, triggers, email and actions.
- [API Endpoints](https://teenybase.com/docs/reference/api-endpoints.md): Every teenybase REST endpoint under /api/v1: database-level routes, table CRUD (select, list, view, insert, update, edit, delete) and auth routes.
- [CLI Reference](https://teenybase.com/docs/reference/cli.md): Every teenybase CLI command and flag: create, init, generate, deploy (local, remote, temporary), dev, exec, backup, secrets, logs, docs and skills.
- [Auth Flow Overview](https://teenybase.com/docs/reference/auth-flows.md): Which teenybase auth flow to use: email and password, OAuth redirect, Google One Tap or login-token, and cookie auth versus bearer tokens.
- [Actions Reference](https://teenybase.com/docs/reference/actions-guide.md): Full reference for teenybase actions: SQL mode, steps mode, typed parameters, access control, sensitive field filtering and the action API.
- [Integrate into an Existing Worker](https://teenybase.com/docs/reference/integrate-existing-worker.md): Mount teenybase inside an existing Cloudflare Worker (usually a Hono app): init, wiring, D1 and R2 bindings, sub-path mounting and deploy.
- [Cost Breakdown](https://teenybase.com/docs/reference/cost-breakdown.md): What a teenybase app costs on your Cloudflare bill, with the math for three sizes: the free plan, about 1,000 daily users and about 10,000.
- [Troubleshooting](https://teenybase.com/docs/reference/troubleshooting.md): Fixes for common teenybase errors: connection, email verification, deploy failures, local development, versions, config, CRUD and rule errors.
- [Security Policy](https://teenybase.com/docs/reference/security.md): How to report a teenybase vulnerability, which versions get fixes, how auth and rules are designed, the known limitations, and deployment best practices.
- [Config Cheat Sheet](https://teenybase.com/docs/config.md): A one-page summary of teenybase.ts: top-level settings, tables, fields, the auth and rules extensions, auth providers, email and actions.
- [API Cheat Sheet](https://teenybase.com/docs/api.md): teenybase API requests on one page: CRUD, sign-up, login, refresh, password reset, email verification, OAuth, files and actions, with curl examples.

## Project

- [GitHub](https://github.com/teenybase/teenybase): source code, issues and changelog
- [npm](https://www.npmjs.com/package/teenybase): the `teenybase` package (CLI and library)
- [X](https://x.com/teenybase): announcements