Skip to content

Commit a8e9772

Browse files
benitavbenitav
committed
Leaner Readme
1 parent d2d7ee1 commit a8e9772

File tree

1 file changed

+23
-135
lines changed

1 file changed

+23
-135
lines changed

‎packages/powersync/README.md

Lines changed: 23 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,39 @@
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>
214

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
256

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.
278

28-
### Implement a backend connector and initialize the PowerSync database
9+
This package (`powersync`) is the PowerSync SDK for Dart/Flutter clients.
2910

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).
3412

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
4114

42-
late PowerSyncDatabase db;
15+
```bash
16+
flutter pub add powersync
17+
```
4318

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
4720

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.
6122

62-
openDatabase() async {
63-
final dir = await getApplicationSupportDirectory();
64-
final path = join(dir.path, 'powersync-dart.db');
23+
# Changelog
6524

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).
6926

70-
// Connect to backend
71-
db.connect(connector: MyBackendConnector(db));
72-
}
73-
```
27+
# API Reference
7428

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).
9130

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
10632

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.
13034

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?
15136

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

Comments
 (0)