Use case example: Pre seeded sqlite use case #314
+106
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
kobiebotha
requested changes
Dec 18, 2025
| "usage/use-case-examples/raw-tables", | ||
| "usage/use-case-examples/custom-write-checkpoints" | ||
| "usage/use-case-examples/custom-write-checkpoints", | ||
| "usage/use-case-examples/pre-seeded-sqlite" |
Collaborator
There was a problem hiding this comment.
the use case examples are roughly ordered alphabetically, with data pipelines at the bottom since it's enterprise only. could you put this between postgis and prioritized sync?
| @@ -0,0 +1,103 @@ | |||
| --- | |||
| title: "Pre-Seeding SQLite Databases" | |||
| description: "Optimizing Initial Sync by pre-Seeding SQLite Databases." | |||
|
|
||
| To achieve this, you can run server-side processes to pre-generate and seed SQLite files. These files can then be uploaded to blob storage, such as AWS S3, Azure Blob Storage, or Google Cloud Storage, to be downloaded directly by the client applications, bypassing the initial sync process. | ||
|
|
||
| The [PowerSync Node.js SDK](/client-sdk-references/node) comes in handy in these scenarios, because you can use it to on the server in Node.js applications. |
|
|
||
| The [PowerSync Node.js SDK](/client-sdk-references/node) comes in handy in these scenarios, because you can use it to on the server in Node.js applications. | ||
|
|
||
| <Card title="nodejs-react-native-sqlite-seeder" icon="github" href="https://github.com/powersync-community/nodejs-react-native-sqlite-seeder"> |
Collaborator
There was a problem hiding this comment.
This card appears without context, should it be accompanied with some description text?
| # Main Concepts | ||
|
|
||
| ## Generate a client specific JWT token | ||
| In the event you want to dynamically populate the SQLite database with data, you can generate a JWT token that is scoped to a specific client device. On the servier side application you would typically query the source database directly and fetch the IDs required in your sync rules to satisfy the conditions of the parameter queries. |
|
|
||
| ## Client Side Usage | ||
|
|
||
| When the client applicaitons boot, before connecting to the PowerSync instance, check if the pre-seeded SQLite database exists in the blob storage. If it does, download it and use when initializing the PowerSyncDatabase class. |
| When the client applicaitons boot, before connecting to the PowerSync instance, check if the pre-seeded SQLite database exists in the blob storage. If it does, download it and use when initializing the PowerSyncDatabase class. | ||
|
|
||
| <Warning> | ||
| It's important to note that when the client downloads the pre-seeded SQLite database that it's stored in a permanent location on the device. This means that the database will not be deleted when the app is uninstalled or restarted. |
Collaborator
There was a problem hiding this comment.
if you uninstall from iOS all app data will be deleted, this is not possible. I think this only caters for crashes/restarts, not uninstall
| Depending on which PowerSync SDK you are using, you may need to use framework specific methods to store the file in a permanent location on the device. For example, in React Native + Expo you can use the [`expo-file-system`](https://docs.expo.dev/versions/latest/sdk/filesystem/) module to store the file in a permanent location on the device. | ||
| </Warning> | ||
|
|
||
| Once the database is downloaded, insert a new client_id key into the ps_kv table and connect to the PowerSync instance. |
Collaborator
There was a problem hiding this comment.
would be good to use backtick formatting for client_id and ps_kv
| It's important that you insert a new client_id key into the ps_kv table to avoid conflicts when the client connects to the PowerSync instance. | ||
| </Tip> | ||
|
|
||
| At this point the client should be able to connect to the PowerSync instance and sync the data as normal, bypassing the initial sync process. |
Collaborator
There was a problem hiding this comment.
suggest rephrasing to make this more clear. what does "as normal" mean? it means resume syncing from where the snapshot was created and where the service operation history is at, right?
| # Main Concepts | ||
|
|
||
| ## Generate a client specific JWT token | ||
| In the event you want to dynamically populate the SQLite database with data, you can generate a JWT token that is scoped to a specific client device. On the servier side application you would typically query the source database directly and fetch the IDs required in your sync rules to satisfy the conditions of the parameter queries. |
Collaborator
There was a problem hiding this comment.
is the token scoped to a device or a user?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This pull request adds documentation for a new use case example on pre-seeding SQLite databases to optimize initial sync times, and updates the documentation index to include this new example.
Documentation updates:
pre-seeded-sqlite.mdx, explaining how to pre-generate and distribute SQLite databases to clients, including server-side preparation, JWT usage, and client-side integration.usage/use-case-examples.mdxto include "Pre-seeded SQLite Databases" as a new card.docs.jsonto add the new pre-seeded SQLite example to the documentation navigation structure.