|
1 | | -# PowerSync SDK for Dart/Flutter |
2 | | - |
3 | | -[PowerSync](https://powersync.co) is a service and set of SDKs that keeps PostgreSQL databases in sync with on-device SQLite databases. |
4 | | - |
5 | | -## SDK Features |
6 | | - |
7 | | -* Real-time streaming of changes. |
8 | | -* Direct access to the SQLite database - use SQL on the client and server. |
9 | | -* Operations are asynchronous by default - does not block the UI. |
10 | | -* Supports one write and many reads concurrently. |
11 | | -* No need for client-side database migrations - these are handled automatically. |
12 | | -* Subscribe to queries for live updates. |
13 | | - |
14 | | -## Examples |
15 | | - |
16 | | -For complete app examples, see our [example app gallery](https://docs.powersync.com/resources/demo-apps-example-projects#flutter) |
17 | | - |
18 | | -For examples of some common patterns, see our [example snippets](./example/README.md) |
19 | | - |
20 | | -## Getting started |
| 1 | +<p align="center"> |
| 2 | + <a href="https://www.powersync.com" target="_blank"><img src="https://github.com/powersync-ja/.github/assets/19345049/602bafa0-41ce-4cee-a432-56848c278722"/></a> |
| 3 | +</p> |
21 | 4 |
|
22 | | -You'll need to create a PowerSync account and set up a PowerSync instance. You can do this at [https://www.powersync.com/](https://www.powersync.com/). |
23 | | - |
24 | | -### Install the package |
| 5 | +# PowerSync SDK for Dart/Flutter |
25 | 6 |
|
26 | | -`flutter pub add powersync` |
| 7 | +[PowerSync](https://powersync.com) is a service and set of SDKs that keeps Postgres databases in sync with on-device SQLite databases. |
27 | 8 |
|
28 | | -### Implement a backend connector and initialize the PowerSync database |
| 9 | +This package (`powersync`) is the PowerSync SDK for Dart/Flutter clients. |
29 | 10 |
|
30 | | -```dart |
31 | | -import 'package:powersync/powersync.dart'; |
32 | | -import 'package:path_provider/path_provider.dart'; |
33 | | -import 'package:path/path.dart'; |
| 11 | +See a summary of features [here](https://docs.powersync.com/client-sdk-references/flutter). |
34 | 12 |
|
35 | | -// Define the schema for the local SQLite database. |
36 | | -// You can automatically generate this schema based on your sync rules: |
37 | | -// In the PowerSync dashboard, right-click on your PowerSync instance and then click "Generate client-side schema" |
38 | | -const schema = Schema([ |
39 | | - Table('customers', [Column.text('name'), Column.text('email')]) |
40 | | -]); |
| 13 | +# Installation |
41 | 14 |
|
42 | | -late PowerSyncDatabase db; |
| 15 | +```bash |
| 16 | +flutter pub add powersync |
| 17 | +``` |
43 | 18 |
|
44 | | -// You must implement a backend connector to define how PowerSync communicates with your backend. |
45 | | -class MyBackendConnector extends PowerSyncBackendConnector { |
46 | | - PowerSyncDatabase db; |
| 19 | +# Getting Started |
47 | 20 |
|
48 | | - MyBackendConnector(this.db); |
49 | | - @override |
50 | | - Future<PowerSyncCredentials?> fetchCredentials() async { |
51 | | - // implement fetchCredentials to obtain a JWT from your authentication service |
52 | | - // see https://docs.powersync.com/usage/installation/authentication-setup |
53 | | - } |
54 | | - @override |
55 | | - Future<void> uploadData(PowerSyncDatabase database) async { |
56 | | - // Implement uploadData to send local changes to your backend service |
57 | | - // You can omit this method if you only want to sync data from the server to the client |
58 | | - // see https://docs.powersync.com/usage/installation/upload-data |
59 | | - } |
60 | | -} |
| 21 | +Our [full SDK reference](https://docs.powersync.com/client-sdk-references/flutter) contains everything you need to know to get started implementing PowerSync in your project. |
61 | 22 |
|
62 | | -openDatabase() async { |
63 | | - final dir = await getApplicationSupportDirectory(); |
64 | | - final path = join(dir.path, 'powersync-dart.db'); |
| 23 | +# Changelog |
65 | 24 |
|
66 | | - // Setup the database. |
67 | | - db = PowerSyncDatabase(schema: schema, path: path); |
68 | | - await db.initialize(); |
| 25 | +A changelog for this SDK is available [here](https://releases.powersync.com/announcements/flutter-client-sdk). |
69 | 26 |
|
70 | | - // Connect to backend |
71 | | - db.connect(connector: MyBackendConnector(db)); |
72 | | -} |
73 | | -``` |
| 27 | +# API Reference |
74 | 28 |
|
75 | | -### Subscribe to changes in data |
76 | | - |
77 | | -```dart |
78 | | -StreamBuilder( |
79 | | - // you can watch any SQL query |
80 | | - stream: return db.watch('SELECT * FROM customers order by id asc'), |
81 | | - builder: (context, snapshot) { |
82 | | - if (snapshot.hasData) { |
83 | | - // TODO: implement your own UI here based on the result set |
84 | | - return ...; |
85 | | - } else { |
86 | | - return const Center(child: CircularProgressIndicator()); |
87 | | - } |
88 | | - }, |
89 | | -) |
90 | | -``` |
| 29 | +The full API reference for this SDK can be found [here](https://pub.dev/documentation/powersync/latest/powersync/powersync-library.html). |
91 | 30 |
|
92 | | -### Insert, update, and delete data in the SQLite database as you would normally |
93 | | - |
94 | | -```dart |
95 | | -FloatingActionButton( |
96 | | - onPressed: () async { |
97 | | - await db.execute( |
98 | | - 'INSERT INTO customers(id, name, email) VALUES(uuid(), ?, ?)', |
99 | | - ['Fred', 'fred@example.org'], |
100 | | - ); |
101 | | - }, |
102 | | - tooltip: '+', |
103 | | - child: const Icon(Icons.add), |
104 | | -); |
105 | | -``` |
| 31 | +# Examples |
106 | 32 |
|
107 | | -### Send changes in local data to your backend service |
108 | | - |
109 | | -```dart |
110 | | -// Implement the uploadData method in your backend connector |
111 | | -@override |
112 | | -Future<void> uploadData(PowerSyncDatabase database) async { |
113 | | - final batch = await database.getCrudBatch(); |
114 | | - if (batch == null) return; |
115 | | - for (var op in batch.crud) { |
116 | | - switch (op.op) { |
117 | | - case UpdateType.put: |
118 | | - // Send the data to your backend service |
119 | | - // replace `_myApi` with your own API client or service |
120 | | - await _myApi.put(op.table, op.opData!); |
121 | | - break; |
122 | | - default: |
123 | | - // TODO: implement the other operations (patch, delete) |
124 | | - break; |
125 | | - } |
126 | | - } |
127 | | - await batch.complete(); |
128 | | -} |
129 | | -``` |
| 33 | +For example projects built with PowerSync and Flutter, see our [Demo Apps / Example Projects](https://docs.powersync.com/resources/demo-apps-example-projects#flutter) gallery. Most of these projects can also be found in the [`demos/`](../demos/) directory. |
130 | 34 |
|
131 | | -### Logging |
132 | | - |
133 | | -You can enable logging to see what's happening under the hood |
134 | | -or to debug connection/authentication/sync issues. |
135 | | - |
136 | | -```dart |
137 | | -Logger.root.level = Level.INFO; |
138 | | -Logger.root.onRecord.listen((record) { |
139 | | - if (kDebugMode) { |
140 | | - print('[${record.loggerName}] ${record.level.name}: ${record.time}: ${record.message}'); |
141 | | -
|
142 | | - if (record.error != null) { |
143 | | - print(record.error); |
144 | | - } |
145 | | - if (record.stackTrace != null) { |
146 | | - print(record.stackTrace); |
147 | | - } |
148 | | - } |
149 | | -}); |
150 | | -``` |
| 35 | +# Found a bug or need help? |
151 | 36 |
|
| 37 | +- Join our [Discord server](https://discord.gg/powersync) where you can browse topics from our community, ask questions, share feedback, or just say hello :) |
| 38 | +- Please open a [GitHub issue](https://github.com/powersync-ja/powersync.dart/issues) when you come across a bug. |
| 39 | +- Have feedback or an idea? [Submit an idea](https://roadmap.powersync.com/tabs/5-roadmap/submit-idea) via our public roadmap or [schedule a chat](https://calendly.com/powersync/powersync-chat) with someone from our product team. |
0 commit comments