|
2 | 2 |
|
3 | 3 | High-performance asynchronous interface for SQLite on Dart & Flutter. |
4 | 4 |
|
5 | | -[SQLite](https://www.sqlite.org/) is small, fast, has a lot of built-in functionality, and works |
6 | | -great as an in-app database. However, SQLite is designed for many different use cases, and requires |
7 | | -some configuration for optimal performance as an in-app database. |
8 | | - |
9 | | -The [sqlite3](https://pub.dev/packages/sqlite3) Dart bindings are great for direct synchronous access |
10 | | -to a SQLite database, but leaves the configuration up to the developer. |
11 | | - |
12 | | -This library wraps the bindings and configures the database with a good set of defaults, with |
13 | | -all database calls being asynchronous to avoid blocking the UI, while still providing direct SQL |
14 | | -query access. |
15 | | - |
16 | | -## Features |
17 | | - |
18 | | -- All operations are asynchronous by default - does not block the main isolate. |
19 | | -- Watch a query to automatically re-run on changes to the underlying data. |
20 | | -- Concurrent transactions supported by default - one write transaction and many multiple read transactions. |
21 | | -- Uses WAL mode for fast writes and running read transactions concurrently with a write transaction. |
22 | | -- Direct synchronous access in an isolate is supported for performance-sensitive use cases. |
23 | | -- Automatically convert query args to JSON where applicable, making JSON1 operations simple. |
24 | | -- Direct SQL queries - no wrapper classes or code generation required. |
25 | | - |
26 | | -See this [blog post](https://www.powersync.co/blog/sqlite-optimizations-for-ultra-high-performance), |
27 | | -explaining why these features are important for using SQLite. |
28 | | - |
29 | | -## Installation |
30 | | - |
31 | | -```sh |
32 | | -dart pub add sqlite_async |
33 | | -``` |
34 | | - |
35 | | -For flutter applications, additionally add `sqlite3_flutter_libs` to include the native SQLite |
36 | | -library. |
37 | | - |
38 | | -For other platforms, see the [sqlite3 package docs](https://pub.dev/packages/sqlite3#supported-platforms). |
39 | | - |
40 | | -Web is currently not supported. |
| 5 | +| package | build | pub | likes | popularity | pub points | |
| 6 | +|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| ------- | ------- | |
| 7 | +| sqlite_async | [](https://github.com/powersync-ja/sqlite_async.dart/actions?query=workflow%3Atest) | [](https://pub.dev/packages/sqlite_async) | [](https://pub.dev/packages/sqlite_async/score) | [](https://pub.dev/packages/sqlite_async/score) | [](https://pub.dev/packages/sqlite_async/score) |
| 8 | +| drift_sqlite_async | [](https://github.com/powersync-ja/sqlite_async/actions?query=workflow%3Atest) | [](https://pub.dev/packages/drift_sqlite_async) | [](https://pub.dev/packages/drift_sqlite_async/score) | [](https://pub.dev/packages/drift_sqlite_async/score) | [](https://pub.dev/packages/drift_sqlite_async/score) |
41 | 9 |
|
42 | 10 | ## Getting Started |
43 | 11 |
|
44 | | -```dart |
45 | | -import 'package:sqlite_async/sqlite_async.dart'; |
46 | | -
|
47 | | -final migrations = SqliteMigrations() |
48 | | - ..add(SqliteMigration(1, (tx) async { |
49 | | - await tx.execute( |
50 | | - 'CREATE TABLE test_data(id INTEGER PRIMARY KEY AUTOINCREMENT, data TEXT)'); |
51 | | - })); |
52 | | -
|
53 | | -void main() async { |
54 | | - final db = SqliteDatabase(path: 'test.db'); |
55 | | - await migrations.migrate(db); |
56 | | -
|
57 | | - // Use execute() or executeBatch() for INSERT/UPDATE/DELETE statements |
58 | | - await db.executeBatch('INSERT INTO test_data(data) values(?)', [ |
59 | | - ['Test1'], |
60 | | - ['Test2'] |
61 | | - ]); |
62 | | -
|
63 | | - // Use getAll(), get() or getOptional() for SELECT statements |
64 | | - var results = await db.getAll('SELECT * FROM test_data'); |
65 | | - print('Results: $results'); |
66 | | -
|
67 | | - // Combine multiple statements into a single write transaction for: |
68 | | - // 1. Atomic persistence (all updates are either applied or rolled back). |
69 | | - // 2. Improved throughput. |
70 | | - await db.writeTransaction((tx) async { |
71 | | - await tx.execute('INSERT INTO test_data(data) values(?)', ['Test3']); |
72 | | - await tx.execute('INSERT INTO test_data(data) values(?)', ['Test4']); |
73 | | - }); |
74 | | -
|
75 | | - await db.close(); |
76 | | -} |
77 | | -``` |
78 | | - |
79 | | -# Web |
80 | | - |
81 | | -Note: Web support is currently in Beta. |
82 | | - |
83 | | -Web support requires Sqlite3 WASM and web worker Javascript files to be accessible via configurable URIs. |
84 | | - |
85 | | -Default URIs are shown in the example below. URIs only need to be specified if they differ from default values. |
86 | | - |
87 | | -The compiled web worker files can be found in our Github [releases](https://github.com/powersync-ja/sqlite_async.dart/releases) |
88 | | -The `sqlite3.wasm` asset can be found [here](https://github.com/simolus3/sqlite3.dart/releases) |
89 | | - |
90 | | -Setup |
91 | | - |
92 | | -```Dart |
93 | | -import 'package:sqlite_async/sqlite_async.dart'; |
| 12 | +This monorepo uses [melos](https://melos.invertase.dev/) to handle command and package management. |
94 | 13 |
|
95 | | -final db = SqliteDatabase( |
96 | | - path: 'test.db', |
97 | | - options: SqliteOptions( |
98 | | - webSqliteOptions: WebSqliteOptions( |
99 | | - wasmUri: 'sqlite3.wasm', workerUri: 'db_worker.js'))); |
| 14 | +To configure the monorepo for development run `melos prepare` after cloning. |
100 | 15 |
|
101 | | -``` |
| 16 | +For detailed usage, check out the inner [sqlite_async](https://github.com/powersync-ja/sqlite_async.dart/tree/main/packages/sqlite_async) and [drift_sqlite_async](https://github.com/powersync-ja/sqlite_async.dart/tree/main/packages/drift_sqlite_async) packages. |
0 commit comments