GSAB — Google Sheets as a Backend

A database-like interface for Google Sheets — schemas, validation, field encryption, async CRUD, server-side queries, and a friction-free CLI. Sign in once; no Google Cloud setup required.

🌐 gsab.ajmalaksar.com  ·  📖 Docs  ·  🗺️ Roadmap

Install

pip install gsab          # core
pip install "gsab[pandas]"  # + DataFrame support

Get started

gsab auth login           # browser sign-in (drive.file scope) — that's the whole setup
gsab init my-app          # scaffold a runnable starter (add --fastapi for a CRUD API)
gsab doctor --live        # prove it works end to end

Then define a schema and read/write your sheet. Full usage, examples and the API → the documentation. gsab import data.csv loads a CSV, and gsab cookbook list shows ready recipes.

Features

• Friction-free auth — gsab auth login opens a browser and uses the minimal drive.file scope. No Cloud project, no JSON keys. DIY modes cover existing sheets, your own OAuth client, gcloud, and service accounts.
• Schemas, keys & validation — typed fields, validation rules, and enforced primary_key / unique columns checked on every write.
• Field encryption — flag a field encrypted=True and it's sealed before it reaches the sheet.
• Async CRUD + upsert — insert / read / update / delete plus upsert() for idempotent insert-or-update on a primary key, with rich filters ($gt / $in / $contains / $regex and more).
• Server-side queries — query() runs the Google Visualization query language (filter, sort, aggregate) on Google's side, not in Python. Values come back type-correct.
• Reactive watch() (Experimental) — an async generator that polls + diffs and emits {added, updated, removed}, seeing writes from any connection or the Google UI — drive a live, auto-updating UI. Polling (~1–2s), not push; one poller fans out to many viewers (see examples/realtime-demo/).
• pandas bridge — to_dataframe() / from_dataframe() and bulk_insert() for the whole analytics ecosystem.
• Native charts — chart() embeds a Google chart in the sheet; or hand to_dataframe() to matplotlib/Plotly.
• One-call public sharing — share(role=...) publishes a created sheet to a public link (reader/commenter/writer, default reader; csv_url for embedding); unshare() revokes. No extra scope — GSAB owns the sheets it makes.
• Access control (AccessPolicy) — pass guardrails to SheetManager, the MCP server or the TUI (and share them as a JSON profile): read-only mode, an allowed-sheets allowlist, a share-role cap, destructive-op confirmation, and an activity hook. A client-side guardrail for control + visibility — the OAuth scope stays the real boundary.
• Access-control TUI (Experimental) — gsab tui is a terminal cockpit over AccessPolicy: edit the guardrails, manage the allowlist, probe whether an op would be allowed or blocked (the real check the library and MCP run), and watch a live activity feed. Saves/loads the same profile gsab mcp --policy reads. pip install "gsab[tui]".
• Actionable errors — Google API errors become clear GSAB exceptions with retry/backoff and token refresh — readable by humans and LLM agents.
• Installable agent skills — gsab skill install drops GSAB skills into .claude/skills (or --portable for any LLM) so your coding agent knows the real API.
• MCP server — gsab mcp lets any MCP client (Claude, Codex, Cursor, Zed, …) use your Google Sheet as a database directly: create, insert, read, query, upsert, share. --read-only and --policy apply access controls. pip install "gsab[mcp]".
• Secure tokens — stored in your OS keychain (keyring), with a 0600-file fallback.

Roadmap

Shipped (v0.10.0): auth + CLI · schemas, validation & encryption · async CRUD · upsert + enforced primary keys · type-correct server-side query · reactive watch() (Experimental) · public sharing (reader/commenter/writer) · MCP server (gsab mcp, with --read-only / --policy) · access control (AccessPolicy) · access-control TUI (gsab tui, Experimental) · pandas bridge + bulk insert · native in-sheet charts · LLM-friendly errors + retry/backoff · installable agent skills · scaffolding & CSV import · keychain storage · security CI (bandit + pip-audit).

Coming next: rate-aware batching · improved/pipe-friendly CLI · a JavaScript client · one-click hosted sign-in.

Full roadmap with per-feature stability (and what's deliberately out of scope) → ROADMAP.md. Live summary → gsab.ajmalaksar.com/#roadmap.

Releases

Versioned with SemVer; see CHANGELOG.md. Tagged releases (vX.Y.Z) publish to PyPI automatically via GitHub Actions.

License

MIT — see LICENSE.md. GSAB is an independent project, not affiliated with Google LLC.