Tabularis driver plugin for Google Cloud Firestore — read, query (SQL subset), and edit Firestore collections from Tabularis. https://tabularis.dev
  • Rust 97.1%
  • Just 2.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
NewtTheWolf 736c31eaa7
Merge feature/multi-db: schemas = Firestore databases (v0.5.0)
v0.4.0: list_databases JSON-RPC for connection-form database discovery.
v0.5.0: schemas map 1:1 to Firestore databases under the project; one
FirestoreDb client per database, lazily built; every metadata/query/CRUD
handler accepts a schema param and routes through resolve_for(schema).
SchemaCacheKey/CountKey/QueryKey now carry database_id so cross-schema
cache hits can't collide. .tabularium capabilities.schemas: true.

admin::list_databases prod-path still stubs the bearer-token + REST call
to firestore.googleapis.com/v1/projects/{id}/databases — emulator mode
short-circuits, production falls back to the configured database_id so
the schema picker always has one usable entry. Auth wiring is a single
file to extend.
2026-05-31 16:24:00 +02:00
.github fully tabularium: drop manifest.json, .tabularium is the only source 2026-05-31 12:42:06 +02:00
assets feat(manifest): adopt Tabularium .tabularis registry format, bump 0.2.0 2026-05-20 18:55:06 +02:00
docs docs(brainstorm): schemaful mode — opt-in schema discipline 2026-05-09 20:49:34 +02:00
just build(just): nested module structure 2026-05-09 20:16:54 +02:00
src feat: schemas = Firestore databases (v0.5.0 multi-client) 2026-05-31 16:19:48 +02:00
tasks docs(todo): pin next-session priority order at top 2026-05-09 20:18:54 +02:00
tests test: integration suite via bun-orchestrated Firestore emulator 2026-05-09 20:06:35 +02:00
.firebaserc test: integration suite via bun-orchestrated Firestore emulator 2026-05-09 20:06:35 +02:00
.gitignore test: integration suite via bun-orchestrated Firestore emulator 2026-05-09 20:06:35 +02:00
.tabularium feat: schemas = Firestore databases (v0.5.0 multi-client) 2026-05-31 16:19:48 +02:00
Cargo.lock feat(manifest): adopt Tabularium .tabularis registry format, bump 0.2.0 2026-05-20 18:55:06 +02:00
Cargo.toml feat: schemas = Firestore databases (v0.5.0 multi-client) 2026-05-31 16:19:48 +02:00
CLAUDE.md build(just): nested module structure 2026-05-09 20:16:54 +02:00
CONTRIBUTING.md docs: public-ready README + LICENSE + CONTRIBUTING 2026-05-10 09:47:15 +02:00
firebase.json test: integration suite via bun-orchestrated Firestore emulator 2026-05-09 20:06:35 +02:00
justfile build(just): nested module structure 2026-05-09 20:16:54 +02:00
LICENSE docs: public-ready README + LICENSE + CONTRIBUTING 2026-05-10 09:47:15 +02:00
package.json test: integration suite via bun-orchestrated Firestore emulator 2026-05-09 20:06:35 +02:00
README.md docs: public-ready README + LICENSE + CONTRIBUTING 2026-05-10 09:47:15 +02:00
rust-toolchain.toml Initial commit: Firestore driver scaffold + Phase 1 design 2026-05-08 10:14:48 +02:00

Firestore — Tabularis Plugin

Driver plugin for Tabularis that connects to Google Cloud Firestore.

The plugin is a standalone Rust binary that Tabularis spawns as a child process and talks to over JSON-RPC 2.0 on stdio. It maps Firestore's collection/document model onto Tabularis' relational worldview so you get table browsing, schema inference, SQL-flavoured queries, and CRUD against any Firestore project.

Status: Phases 1–3 shipped (read-only browser, query layer, CRUD). Phase 4 (multi-DB / subcollections / live mode) is on the roadmap.

Install

git clone ssh://[email protected]/NewtTheWolf/firestore-tabularis.git
cd firestore-tabularis
just plugin install   # debug build + copy into the Tabularis plugin folder

Restart Tabularis (or toggle the plugin in Settings) and pick Firestore from the connection picker.

Plugin folders by platform:

OS Path
Linux ~/.local/share/tabularis/plugins/firestore
macOS ~/Library/Application Support/com.debba.tabularis/plugins/firestore
Windows %APPDATA%\com.debba.tabularis\plugins\firestore

Authentication

The plugin uses the standard Google authentication chain. Pick whichever fits your setup:

  1. Service account JSON — set the path in plugin settings.
  2. Application Default Credentials — gcloud auth application-default login.
  3. GOOGLE_APPLICATION_CREDENTIALS env var — path to a JSON key.
  4. Local emulator — set the Firestore Emulator Host setting (e.g. localhost:8080) and skip credentials entirely.

Required IAM role for production: roles/datastore.viewer (read-only) or roles/datastore.user (read + write).

What's implemented

Method Status Notes
initialize, test_connection, ping ✅ Connection lifecycle.
get_databases ✅ Returns the configured database id.
get_tables ✅ Lists root collections, alphabetical.
get_columns ✅ Samples N docs, infers types, caches per-process. Honours schema-overrides if configured.
get_schema_snapshot ✅ ER-diagram batch endpoint with inferred reference foreign keys.
execute_query ✅ SELECT with WHERE / AND / OR / NOT / IN / NOT IN / ARRAY_CONTAINS / ARRAY_CONTAINS_ANY / six comparison ops / parens / TIMESTAMP literals / ORDER BY / LIMIT / OFFSET / cursor pagination.
explain_query ✅ Returns Firestore EXPLAIN/ANALYZE plan with documents_returned, documents_scanned, index_used, execution_duration_ms.
insert_record / update_record / delete_record ✅ Including doc-id rename via id-cell-edit (read → create → delete).
Required-field validation ✅ Pre-insert check via schema overrides.
DDL generators (get_*_sql, drop_*) ⛔ Not applicable — Firestore is schemaless.
get_views*, get_routines*, get_indexes, get_foreign_keys ✅ (empty) Firestore has no relational analogues.

DML over SQL (INSERT INTO …, UPDATE … SET …, DELETE FROM …) currently returns a friendly redirect explaining to use Tabularis' grid actions instead. Real DML SQL is on the roadmap together with the sqlparser migration — see tasks/todo.md.

Settings

Configured per plugin install in Plugin Settings → Firestore:

Key Required Description
project_id ✅ GCP project that hosts the Firestore database.
database_id Defaults to (default). Set if you use named Firestore databases.
service_account_path Optional. Falls back to ADC / GOOGLE_APPLICATION_CREDENTIALS.
emulator_host Optional. e.g. localhost:8080. Routes traffic to the emulator.
sample_size Number of documents sampled per collection for type inference (default 50).
schema_overrides_dir Optional. Directory holding per-(project, db) override JSON files. See docs/schema-overrides.md.

Layout

src/
├── main.rs              thin async stdio loop
├── rpc.rs               method dispatch + response helpers
├── error.rs             plugin error type
├── models.rs            ConnectionParams + common shapes
├── client.rs            connection config — builds FirestoreDb from settings
├── state.rs             globals: SETTINGS, CLIENT, SCHEMA_CACHE, CURSOR_CACHE, COUNT_CACHE, SCHEMA_OVERRIDES
├── cache.rs             generic TTL+LRU cache
├── coercion.rs          JSON → Firestore proto value (insert/update side)
├── firestore_error.rs   gRPC status mapping with missing-index URL extraction
├── firestore_filter.rs  WHERE-tree → firestore-rs filter
├── query_parser.rs      hand-rolled SELECT parser (sqlparser migration on roadmap)
├── schema_infer.rs      sample-based column inference
├── schema_overrides.rs  per-(project, db) JSON override files
├── handlers/
│   ├── metadata.rs      databases, tables, columns, schema_snapshot, etc.
│   ├── query.rs         test_connection, execute_query, explain_query
│   ├── crud.rs          insert/update/delete + doc-id rename
│   └── ddl.rs           CREATE/ALTER/DROP generators (mostly not_implemented)
└── utils/
    ├── identifiers.rs
    └── pagination.rs
tests/
├── firestore_emulator.rs   integration suite (gated #[ignore], run via `just emulator test`)
└── fixtures/               bun-native fixture seeder + free-port helper

Development

Workflows live in a root justfile plus three modules under just/. Run just --list for the root, just --list <module> for a module.

just build              # cargo build (and ui/ if present)
just release            # release build with LTO + symbol stripping
just test               # cargo test (unit tests only — integration tests are gated)
just cov                # region-level coverage via cargo-llvm-cov
just lint               # cargo clippy --all-targets -- -D warnings
just fmt                # cargo fmt --all
just plugin install     # debug build + install into Tabularis plugin folder
just emulator test      # self-contained integration suite (random port, seed, run, clean up)

The integration suite needs bun + Java 21+ (firebase-tools v15 requirement). See docs/integration-tests.md for the full setup.

Documentation

Contributing

Issues and patches welcome — see CONTRIBUTING.md. The roadmap and todo file flag good first contributions.

License

Apache-2.0 — see LICENSE.