Skip to main content
The PowerSync Client SDK is embedded into a software application. The Client SDK manages the client connection to the PowerSync Service, authenticating via a JWT. The connection between the client and the PowerSync Service is encrypted, and either uses HTTP streams or WebSockets (depending on the specific Client SDK being used) The Client SDK provides access to a managed SQLite database that is automatically kept in sync with the backend source database via the PowerSync Service, based on the Sync Rules that are active on the PowerSync Service instance.

​
Reading Data (SQLite)

App clients always read data from the client-side SQLite database. When the user is online and the app is connected to the PowerSync Service, changes on the source database reflect in real-time in the SQLite database, and Live Queries / Watch Queries allows the app UI to have real-time reactivity too.

​
Client-Side Schema and SQLite Database Structure

When you implement the PowerSync Client SDK in your application, you need to define a client-side schema with tables, columns and indexes that correspond to your Sync Rules. You provide this schema when the PowerSync-managed SQLite database is instantiated. The tables defined in your client-side schema are usable in SQL queries as if they were actual SQLite tables, while in reality they are created as SQLite views based on the schemaless JSON data being synced (see PowerSync Protocol). The PowerSync Client SDK automatically maintains the following tables in the SQLite database:
  1. ps_data__<table> - This contains the data for each “table”, in JSON format. Since JSON is being used, this table’s schema does not change when columns are added, removed or changed in the Sync Rules and client-side schema.
  2. ps_data_local__<table> - Same as the previous point, but for local-only tables.
  3. <table> (VIEW) - These are views on the above ps_data tables, with each defined column in the client-side schema extracted from the JSON. For example, a description text column would be CAST(data ->> '$.description' as TEXT).
  4. ps_untyped - Any synced table that does is not defined in the client-side schema is placed here. If the table is added to the schema at a later point, the data is then migrated to ps_data__<table>.
  5. ps_oplog - This is operation history data as received from the PowerSync Service, grouped per bucket.
  6. ps_crud - The client-side upload queue (see Writing Data below)
  7. ps_buckets - A small amount of metadata for each bucket.
  8. ps_migrations - Table keeping track of Client SDK schema migrations.
Most rows will be present in at least two tables — the ps_data__<table> table, and in ps_oplog. The copy of the row in ps_oplog may be newer than the one in ps_data__<table>. This is because of the checkpoint system in PowerSync that gives the system its consistency properties. When a full checkpoint has been downloaded, data is copied over from ps_oplog to the individual ps_data__<table> tables. It is possible for different buckets in Sync Rules to include overlapping data (for example, if multiple buckets query data from the same table). If rows with the same table and ID have been synced via multiple buckets, it may be present multiple times in ps_oplog, but only one will be preserved in the ps_data__<table> table (the one with the highest op_id).
Raw Tables Instead of JSON-Backed SQLite Views: If you run into limitations with the above JSON-based SQLite view system, check out the Raw Tables experimental feature which allows you to define and manage raw SQLite tables to work around some of the limitations of PowerSync’s default JSON-backed SQLite views system. We are actively seeking feedback on the raw tables functionality.

​
Writing Data (via SQLite Database and Upload Queue)

Any mutations on the SQLite database, namely updates, deletes and inserts, are immediately reflected in the SQLite database, and also also automatically placed into an upload queue by the Client SDK. The upload queue is a blocking FIFO queue. The upload queue is automatically managed by the PowerSync Client SDK. The Client SDK processes the upload queue by invoking an uploadData() function that you define when you integrate the Client SDK. Your uploadData() function implementation should call your backend application API to persist the mutations to the backend source database. The reason why we designed PowerSync this way is that it allows you to apply your own backend business logic, validations and authorization to any mutations going to your source database. The PowerSync Client SDK automatically takes care of network failures and retries. If processing the upload queue fails (e.g. because the user is offline), it is automatically retried.