\n\nQuick Guide: Use
\n@powersync/react-nativefor offline-first apps backed by local SQLite. Define schemas withTableandcolumn.text/integer/real(id column is auto-created). UsePowerSyncDatabasefor reads/writes,useQueryfrom@powersync/reactfor reactive watched queries. Connect to your backend via a connector implementingfetchCredentials+uploadData. Conflict resolution defaults to last-write-wins per field -- customize inuploadData. Use@powersync/op-sqlitefor SQLCipher encryption.
<critical_requirements>
\n\n\nAll code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
\nimport type, named constants)
(You MUST define schemas with new Table({ ... }) using column.text, column.integer, column.real -- NEVER declare an id column, PowerSync creates it automatically)
(You MUST call powersync.connect(connector) after init() to start syncing -- without it the database is local-only with no sync)
(You MUST implement both fetchCredentials() and uploadData() in your backend connector -- missing either breaks the sync loop)
(You MUST use useQuery from @powersync/react for reactive queries -- raw getAll() does NOT re-render on data changes)
</critical_requirements>
\nAuto-detection: PowerSync, powersync, @powersync/react-native, @powersync/react, @powersync/op-sqlite, PowerSyncDatabase, useQuery, usePowerSync, useStatus, useSuspenseQuery, PowerSyncBackendConnector, fetchCredentials, uploadData, column.text, column.integer, column.real, Schema, Table, sync rules, bucket_definitions, offline-first SQLite, watched query, CrudEntry, CrudTransaction, AttachmentQueue, AttachmentTable, local-only table
\nWhen to use:
\nKey patterns covered:
\nTable, column types, indexes, and local-only tablesPowerSyncDatabase setup with default or OP-SQLite adapteruseQuery, useSuspenseQuery, useStatus, usePowerSyncfetchCredentials() + uploadData() implementationexecute(), get(), getAll(), getOptional()AttachmentTable and AttachmentQueueWhen NOT to use:
\nDetailed Resources:
\n<decision_framework>
\nWhat kind of data are you storing?\n|\n+-> Relational data that needs offline + cloud sync?\n| +-> YES -> PowerSync + SQLite (this skill)\n| +-> NO -> Key-value pairs only?\n| +-> YES -> Use a key-value store (not this skill)\n| +-> NO -> Files/media only?\n| +-> YES -> Use the filesystem\n|\n+-> Do you need reactive queries in React?\n| +-> YES -> Use useQuery from @powersync/react\n| +-> NO -> Use powersync.getAll() / get() directly\n|\n+-> Do you need on-device encryption?\n| +-> YES -> Use @powersync/op-sqlite with SQLCipher\n| +-> NO -> Use the default SQLite adapter\n|\n+-> Do you have file attachments?\n| +-> YES -> Use AttachmentTable + AttachmentQueue\n| +-> NO -> Standard schema is sufficient\n|\n+-> How should conflicts be resolved?\n +-> Simple apps -> Last-write-wins (default)\n +-> Collaborative editing -> Field-level merge or CRDTs\n +-> Business-critical -> Server-side validation + conflict recording\n| Scenario | \nAPI | \n
|---|---|
| Reactive component data | \nuseQuery() from @powersync/react | \n
| Reactive with Suspense | \nuseSuspenseQuery() from @powersync/react | \n
| One-time fetch (no reactivity) | \nuseQuery() with runQueryOnce: true | \n
| Service/utility reads | \npowersync.getAll() / get() / getOptional() | \n
| Write operations | \npowersync.execute() | \n
| Connection status | \nuseStatus() from @powersync/react | \n
| Database instance access | \nusePowerSync() from @powersync/react | \n
</decision_framework>
\n<red_flags>
\nHigh Priority Issues:
\nid column in schema -- PowerSync auto-creates id as text primary key. Declaring it causes conflicts.execute() for reads (SELECT) instead of getAll() / useQuery() -- execute() does not return query results in a usable formatpowersync.connect(connector) -- database works locally but nothing syncs, easy to miss in developmentgetAll() in React components expecting reactivity -- raw reads do not watch for changes, use useQuery() insteadtransaction.complete() in uploadData() -- unacknowledged transactions retry indefinitely, causing duplicate uploadsMedium Priority Issues:
\nfetchCredentials() returning null -- happens when auth session expires, must re-authenticateAttachmentTable for files, keep SQLite for metadatacolumn.integer for booleans without consistent 0/1 values -- SQLite has no native boolean typeGotchas & Edge Cases:
\nuuid() is a PowerSync SQL function, not a JavaScript function -- use it in SQL strings, not in JScolumn.real stores IEEE 754 doubles -- be aware of floating-point precision for currency (use integer cents instead)request.user_id() to access the authenticated user ID from the JWT -- not a custom functiongetNextCrudTransaction() returns null when the upload queue is empty -- always check before iteratingexecute() with views may return rowsAffected: 0 even on success -- use RETURNING clause for confirmationclientImplementation: SyncClientImplementation.JAVASCRIPT to use the legacy JS clientdisconnectAndClear() removes all local data -- use disconnect() to stop sync while preserving local datalocalOnly: true on Table options) are never synced -- useful for draft data or app state</red_flags>
\n<critical_reminders>
\n\n\nAll code must follow project conventions in CLAUDE.md
\n
(You MUST define schemas with new Table({ ... }) using column.text, column.integer, column.real -- NEVER declare an id column, PowerSync creates it automatically)
(You MUST call powersync.connect(connector) after init() to start syncing -- without it the database is local-only with no sync)
(You MUST implement both fetchCredentials() and uploadData() in your backend connector -- missing either breaks the sync loop)
(You MUST use useQuery from @powersync/react for reactive queries -- raw getAll() does NOT re-render on data changes)
Failure to follow these rules will cause silent sync failures, missing data, and non-reactive UIs.
\n</critical_reminders>
\n","files":[{"path":"examples/attachments.md","sizeBytes":6649,"isText":true},{"path":"examples/core.md","sizeBytes":10488,"isText":true},{"path":"examples/sync.md","sizeBytes":9833,"isText":true},{"path":"reference.md","sizeBytes":6449,"isText":true},{"path":"SKILL.md","sizeBytes":19202,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-29T15:31:15.031738Z","sha256":"FD8F482CC79D10B5A931E53E93AE482ABCEA20A9022AAA98BC610842325D46FC","sizeBytes":18609},"review":null,"source":{"repositoryUrl":"https://github.com/agents-inc/skills","path":"dist/plugins/mobile-storage-sqlite-powersync/skills/mobile-storage-sqlite-powersync","license":"MIT","commit":"3a51ef571e996b18294bf776d53dbdad26de0617","subtreeSha":"CF1E6B71B6E9B800F555C422B75172123D909F9285AA8071E12D1B9F07BCC775","lastSyncedAt":"2026-09-29T15:27:48.914434Z"},"reviewedAt":"2026-09-29T15:37:46.691746Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/mobile-storage-sqlite-powersync/skills/mobile-storage-sqlite-powersync"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart"},{"target":"git","command":"git clone https://github.com/agents-inc/skills.git"}]}