Skip to content

Sync from docs: add Convex as experimental source database (powersync-docs #456)#46

Open
bean1352 wants to merge 1 commit into
mainfrom
drift/docs-456-convex-source-db
Open

Sync from docs: add Convex as experimental source database (powersync-docs #456)#46
bean1352 wants to merge 1 commit into
mainfrom
drift/docs-456-convex-source-db

Conversation

@bean1352

Copy link
Copy Markdown
Collaborator

Generated by Claude. Review carefully before merging.

Source docs PR: powersync-ja/powersync-docs#456

What changed in docs

powersync-docs #456 adds comprehensive documentation for Convex as a new experimental source database, covering connection setup (deployment URL + deploy key), a required checkpoint table/mutation, polling-based replication via document_deltas, client UUID ID mapping, Convex-specific Sync Streams patterns, and the Convex mutation write path.

Skill updates in this PR

  • skills/powersync/AGENTS.md — added Convex to the preflight database list in the Do/Don't compliance table; added Convex as a named path in Onboarding Playbook step 2 (pointing to powersync-service.md § "Convex Quick Start" and noting no custom REST API needed for writes)
  • skills/powersync/references/powersync-service.md — added convex to metadata tags; added Convex Quick Start section covering the powersync_checkpoints table + mutation prerequisite, deploy key permission requirements, self-hosted service YAML (type: convex), client UUID ID mapping, polling latency, and the table-drop limitation
  • skills/powersync/references/sync-config.md — added convex to metadata tags; added Convex-Specific Patterns section covering UUID ID mapping, Int64 casting to SQLite integer, Convex Auth JWT subject extraction (substring(auth.user_id(), 1, 32)), and table name qualification, with a full example
  • skills/powersync/references/custom-backend.md — added a Convex exception note in the Architecture Recap section clarifying that for Convex the write path uses Convex mutations directly (no REST API), and that Convex Auth requires client_auth.audience: [convex]

Notes for reviewer

  • Convex is marked Experimental in the docs; the skill edits reflect this but do not block usage — the agent will surface the experimental status via the Quick Start section warning.
  • The onboarding-custom.md reference path was deliberately not modified — Convex does not fit the "custom REST backend" pattern and is now routed through the new Convex-specific bullet in AGENTS.md step 2.
  • No new skill file was created for Convex; the existing source-database and sync-config coverage is sufficient for the patterns documented. If a dedicated Convex onboarding reference (parallel to onboarding-supabase.md) is warranted in future, that would be a separate PR.
  • The type mapping table from sync/types.mdx (Id→text, Int64→text/INTEGER, Float64→real, Boolean→integer/0/1, Bytes→base64 text, Array/Object/Record→JSON text) is not reproduced in full in the skills — the Sync Streams example covers the actionable casting patterns an agent needs. If reviewers want the full table, it could be added to a dedicated Convex reference file.
  • Cloud Dashboard connection flow for Convex was not added to skill files (it mirrors the PowerSync Cloud setup path already described); the docs link in the Quick Start section covers it.

Generated by Claude Code

- AGENTS.md: add Convex to preflight database list and Onboarding Playbook step 2
- powersync-service.md: add convex tag + Convex Quick Start section
- sync-config.md: add convex tag + Convex-specific Sync Streams patterns section
- custom-backend.md: add Convex write-path exception note
@bean1352 bean1352 requested a review from michaelbarnes June 10, 2026 10:51
@bean1352 bean1352 self-assigned this Jun 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant