add-graphjin-database

---
name: add-graphjin-database
description: Use when adding a new GraphJin database, warehouse, or CQL/NoSQL backend; building a simulator because no live service is available; wiring a dialect, discovery, tests, scripts, README/CONFIG/FEATURES, or website database support surfaces.
---

# Add GraphJin Database

Use this skill to add a database end to end without leaving half-public support behind. GraphJin is a compiler, not a resolver stack: push behavior into dialect, discovery, schema metadata, and tests.

## Workflow

1. Ground in docs and repo truth.
   - Read the database's official SQL, DDL, type, catalog, and limitations docs before coding.
   - Inspect existing GraphJin seams: config validation, dialect factory, introspection, `tests/dbint_test.go`, hosted emulators, scripts, README, CONFIG, FEATURES, and website components.
   - Decide and state the public support level: experimental queries, mutations, subscriptions, full support, or simulator-only.

2. Build a simulator first when live service access is unavailable or slow.
   - Add `tests/hostedemu/<db>` and `tests/<db>emu` around `hostedemu.NewConnector`.
   - Add `tests/<db>.sql` using database-native DDL, types, constraints, and metadata features.
   - Keep parser/translator code owned by the target database. Reuse hosted emulator patterns, not another database's grammar, unless docs prove the syntax is identical.
   - Translate setup and discovery into DuckDB, but expose the database's real discovery surfaces.
   - Add parser, type mapping, metadata, discovery, wrapper, default-fixture, and large-catalog tests.

3. Use the simulator to build public support.
   - Register the DB type in `core/config.go`, the psql dialect factory, subscription dialect lookup, introspection switches, and schema-DDL/diff code if public DDL support is claimed.
   - Add a DB-owned dialect. Inherit behavior only after target-specific tests prove it.
   - Add discovery using the docs-recommended catalog path first, with fallbacks only where needed.
   - Wire `tests/dbint_test.go`, focused skip helpers for unsupported features, and `scripts/test-<db>.sh`.
   - Keep GraphJin's collision-free managed artifact SQLite database runtime-only. Its identifier is allocated at startup and must never become an application source, primary database candidate, catalog source, or security-report database.

4. Update public surfaces only after the runtime is wired.
   - Update README, CONFIG, FEATURES, website database logos/frontpage copy, website database matrix, and test-parallel scripts.
   - If the database uses `graphjin serve new --db-url`, update the URL parser and the rendered `cmd/tmpl/prod.yml` and `cmd/tmpl/agentic.yml` sources. Verify a real generated app loads without test-only placeholder replacement.
   - Make feature claims match tests. Use "experimental" and "query/discovery only" when writes, subscriptions, GIS, full-text, or migrations are not verified.
   - Preserve unrelated dirty worktree edits. Patch on top; never revert user changes.
   - Do not add artifact, watch, agent, stateful-MCP, or primitive-tool enablement to new `dev.yml` / `agentic.yml` examples; parsed mode defaults already provide them. Configure an artifact source only when documenting a shared clustered store.

5. Verify and leave evidence.
   - Run simulator tests, dialect/introspection tests, the new `scripts/test-<db>.sh`, and affected shared suites.
   - If shared compiler or introspection code changed, run existing dialect scripts likely to be affected.
   - Before finalizing, recheck docs/website claims against the support level that actually passed.

## References

- Read `references/checklist.md` for the detailed implementation checklist and Redshift-specific notes.