Skip to content

Commit b1b795f

Browse files
chrispaderchrispader
committed
refactor: update README and add deprecation warning
1 parent ef09582 commit b1b795f

File tree

2 files changed

+27
-331
lines changed

2 files changed

+27
-331
lines changed

‎README.md‎

Lines changed: 10 additions & 331 deletions
Original file line numberDiff line numberDiff line change
@@ -1,338 +1,17 @@
1-
![screenshot](https://raw.githubusercontent.com/margelo/react-native-quick-sqlite/main/header2.png)
1+
## 🚧 `react-native-quick-sqlite` (DEPRECATED)
22

3-
<div align="center">
4-
<pre align="center">
5-
bun add react-native-quick-sqlite
6-
npx pod-install</pre>
7-
<a align="center" href="https://github.com/mrousavy?tab=followers">
8-
<img src="https://img.shields.io/github/followers/mrousavy?label=Follow%20%40mrousavy&style=social" />
9-
</a>
10-
<br />
11-
<a align="center" href="https://twitter.com/margelo_io">
12-
<img src="https://img.shields.io/twitter/follow/margelo_io?label=Follow%20%40margelo_io&style=social" />
13-
</a>
14-
</div>
15-
<br />
3+
> [!IMPORTANT]
4+
> `react-native-quick-sqlite` has been deprecated in favor of [`react-native-nitro-sqlite`](https://github.com/margelo/react-native-nitro-sqlite).
5+
>
166
17-
Quick SQLite embeds the latest version of SQLite and provides a low-level JSI-backed API to execute SQL queries.
7+
Please go to the [`react-native-nitro-sqlite`](https://github.com/margelo/react-native-nitro-sqlite) repository instead.
188

19-
Performance metrics are intentionally not presented, [anecdotic testimonies](https://dev.to/craftzdog/a-performant-way-to-use-pouchdb7-on-react-native-in-2022-24ej) suggest anywhere between 2x and 5x speed improvement. On small queries you might not notice a difference with the old bridge but as you send large data to JS the speed increase is considerable.
9+
This is our new [Nitro module](https://nitro.margelo.com/) implementation of this library.
2010

21-
Starting on version `8.0.0` only React-Native `0.71` onwards is supported. This is due to internal changes to React-Native artifacts. If you are on < `0.71` use the latest `7.x.x` version.
11+
Nitro modules is a React Native library that let's us make the codebase more readable and easier to maintain. This way, we're able to fix bugs faster and implement new features! 🚀
2212

23-
TypeORM is officially supported, however, there is currently a parsing issue with React-Native 0.71 and its babel configuration and therefore it will not work, nothing wrong with this package, this is purely an issue on TypeORM.
13+
### Future releases
2414

25-
## API
15+
From major version `9.0.0` on, this library will be shipped in the NPM package `react-native-nitro-sqlite`. New features are going to be implemented there.
2616

27-
```typescript
28-
import {open} from 'react-native-quick-sqlite'
29-
30-
const db = open('myDb.sqlite')
31-
32-
// The db object now contains the following methods:
33-
34-
db = {
35-
close: () => void,
36-
delete: () => void,
37-
attach: (dbNameToAttach: string, alias: string, location?: string) => void,
38-
detach: (alias: string) => void,
39-
transaction: (fn: (tx: Transaction) => void) => Promise<void>,
40-
execute: (query: string, params?: any[]) => QueryResult,
41-
executeAsync: (
42-
query: string,
43-
params?: any[]
44-
) => Promise<QueryResult>,
45-
executeBatch: (commands: SQLBatchParams[]) => BatchQueryResult,
46-
executeBatchAsync: (commands: SQLBatchParams[]) => Promise<BatchQueryResult>,
47-
loadFile: (location: string) => FileLoadResult;,
48-
loadFileAsync: (location: string) => Promise<FileLoadResult>
49-
}
50-
```
51-
52-
### Simple queries
53-
54-
The basic query is **synchronous**, it will block rendering on large operations, further below you will find async versions.
55-
56-
```typescript
57-
import { open } from 'react-native-quick-sqlite';
58-
59-
try {
60-
const db = open('myDb.sqlite');
61-
62-
let { rows } = db.execute('SELECT somevalue FROM sometable');
63-
64-
rows.forEach((row) => {
65-
console.log(row);
66-
});
67-
68-
let { rowsAffected } = await db.executeAsync(
69-
'UPDATE sometable SET somecolumn = ? where somekey = ?',
70-
[0, 1]
71-
);
72-
73-
console.log(`Update affected ${rowsAffected} rows`);
74-
} catch (e) {
75-
console.error('Something went wrong executing SQL commands:', e.message);
76-
}
77-
```
78-
79-
### Transactions
80-
81-
Throwing an error inside the callback will ROLLBACK the transaction.
82-
83-
If you want to execute a large set of commands as fast as possible you should use the `executeBatch` method, it wraps all the commands in a transaction and has less overhead.
84-
85-
```typescript
86-
await QuickSQLite.transaction('myDatabase', (tx) => {
87-
const { status } = tx.execute(
88-
'UPDATE sometable SET somecolumn = ? where somekey = ?',
89-
[0, 1]
90-
);
91-
92-
// offload from JS thread
93-
await tx.executeAsync = tx.executeAsync(
94-
'UPDATE sometable SET somecolumn = ? where somekey = ?',
95-
[0, 1]
96-
);
97-
98-
// Any uncatched error ROLLBACK transaction
99-
throw new Error('Random Error!');
100-
101-
// You can manually commit or rollback
102-
tx.commit();
103-
// or
104-
tx.rollback();
105-
});
106-
```
107-
108-
### Batch operation
109-
110-
Batch execution allows the transactional execution of a set of commands
111-
112-
```typescript
113-
const commands = [
114-
['CREATE TABLE TEST (id integer)'],
115-
['INSERT INTO TEST (id) VALUES (?)', [1]],
116-
[('INSERT INTO TEST (id) VALUES (?)', [2])],
117-
[('INSERT INTO TEST (id) VALUES (?)', [[3], [4], [5], [6]])],
118-
];
119-
120-
const res = QuickSQLite.executeSqlBatch('myDatabase', commands);
121-
122-
console.log(`Batch affected ${result.rowsAffected} rows`);
123-
```
124-
125-
### Dynamic Column Metadata
126-
127-
In some scenarios, dynamic applications may need to get some metadata information about the returned result set.
128-
129-
This can be done by testing the returned data directly, but in some cases may not be enough, for example when data is stored outside
130-
SQLite datatypes. When fetching data directly from tables or views linked to table columns, SQLite can identify the table declared types:
131-
132-
```typescript
133-
let { metadata } = QuickSQLite.executeSql(
134-
'myDatabase',
135-
'SELECT int_column_1, bol_column_2 FROM sometable'
136-
);
137-
138-
metadata.forEach((column) => {
139-
// Output:
140-
// int_column_1 - INTEGER
141-
// bol_column_2 - BOOLEAN
142-
console.log(`${column.columnName} - ${column.columnDeclaredType}`);
143-
});
144-
```
145-
146-
### Async operations
147-
148-
You might have too much SQL to process and it will cause your application to freeze. There are async versions for some of the operations. This will offload the SQLite processing to a different thread.
149-
150-
```ts
151-
QuickSQLite.executeAsync(
152-
'myDatabase',
153-
'SELECT * FROM "User";',
154-
[]).then(({rows}) => {
155-
console.log('users', rows);
156-
})
157-
);
158-
```
159-
160-
### Attach or Detach other databases
161-
162-
SQLite supports attaching or detaching other database files into your main database connection through an alias.
163-
You can do any operation you like on this attached database like JOIN results across tables in different schemas, or update data or objects.
164-
These databases can have different configurations, like journal modes, and cache settings.
165-
166-
You can, at any moment, detach a database that you don't need anymore. You don't need to detach an attached database before closing your connection. Closing the main connection will detach any attached databases.
167-
168-
SQLite has a limit for attached databases: A default of 10, and a global max of 125
169-
170-
References: [Attach](https://www.sqlite.org/lang_attach.html) - [Detach](https://www.sqlite.org/lang_detach.html)
171-
172-
```ts
173-
QuickSQLite.attach('mainDatabase', 'statistics', 'stats', '../databases');
174-
175-
const res = QuickSQLite.executeSql(
176-
'mainDatabase',
177-
'SELECT * FROM some_table_from_mainschema a INNER JOIN stats.some_table b on a.id_column = b.id_column'
178-
);
179-
180-
// You can detach databases at any moment
181-
QuickSQLite.detach('mainDatabase', 'stats');
182-
if (!detachResult.status) {
183-
// Database de-attached
184-
}
185-
```
186-
187-
### Loading SQL Dump Files
188-
189-
If you have a plain SQL file, you can load it directly, with low memory consumption.
190-
191-
```typescript
192-
const { rowsAffected, commands } = QuickSQLite.loadFile(
193-
'myDatabase',
194-
'/absolute/path/to/file.sql'
195-
);
196-
```
197-
198-
Or use the async version which will load the file in another native thread
199-
200-
```typescript
201-
QuickSQLite.loadFileAsync('myDatabase', '/absolute/path/to/file.sql').then(
202-
(res) => {
203-
const { rowsAffected, commands } = res;
204-
}
205-
);
206-
```
207-
208-
## Use built-in SQLite
209-
210-
On iOS you can use the embedded SQLite, when running `pod-install` add an environment flag:
211-
212-
```
213-
QUICK_SQLITE_USE_PHONE_VERSION=1 npx pod-install
214-
```
215-
216-
On Android, it is not possible to link (using C++) the embedded SQLite. It is also a bad idea due to vendor changes, old android bugs, etc. Unfortunately, this means this library will add some megabytes to your app size.
217-
218-
## TypeORM
219-
220-
This library is pretty barebones, you can write all your SQL queries manually but for any large application, an ORM is recommended.
221-
222-
You can use this library as a driver for [TypeORM](https://github.com/typeorm/typeorm). However, there are some incompatibilities you need to take care of first.
223-
224-
Starting on Node14 all files that need to be accessed by third-party modules need to be explicitly declared, TypeORM does not export its `package.json` which is needed by Metro, we need to expose it and make those changes "permanent" by using [patch-package](https://github.com/ds300/patch-package):
225-
226-
```json
227-
// package.json stuff up here
228-
"exports": {
229-
"./package.json": "./package.json", // ADD THIS
230-
".": {
231-
"types": "./index.d.ts",
232-
// The rest of the package json here
233-
```
234-
235-
After you have applied that change, do:
236-
237-
```sh
238-
bun patch-package --exclude 'nothing' typeorm
239-
```
240-
241-
Now every time you install your node_modules that line will be added.
242-
243-
Next, we need to trick TypeORM to resolve the dependency of `react-native-sqlite-storage` to `react-native-quick-sqlite`, on your `babel.config.js` add the following:
244-
245-
```js
246-
plugins: [
247-
// w/e plugin you already have
248-
...,
249-
[
250-
'module-resolver',
251-
{
252-
alias: {
253-
"react-native-sqlite-storage": "react-native-quick-sqlite"
254-
},
255-
},
256-
],
257-
]
258-
```
259-
260-
You will need to install the babel `module-resolver` plugin:
261-
262-
```sh
263-
bun add babel-plugin-module-resolver
264-
```
265-
266-
Finally, you will now be able to start the app without any metro/babel errors (you will also need to follow the instructions on how to setup TypeORM), now we can feed the driver into TypeORM:
267-
268-
```ts
269-
import { typeORMDriver } from 'react-native-quick-sqlite'
270-
271-
datasource = new DataSource({
272-
type: 'react-native',
273-
database: 'typeormdb',
274-
location: '.',
275-
driver: typeORMDriver,
276-
entities: [...],
277-
synchronize: true,
278-
});
279-
```
280-
281-
# Loading existing DBs
282-
283-
The library creates/opens databases by appending the passed name plus, the [documents directory on iOS](https://github.com/margelo/react-native-quick-sqlite/blob/733e876d98896f5efc80f989ae38120f16533a66/ios/QuickSQLite.mm#L34-L35) and the [files directory on Android](https://github.com/margelo/react-native-quick-sqlite/blob/main/android/src/main/java/com/margelo/rnquicksqlite/QuickSQLiteBridge.java#L16), this differs from other SQL libraries (some place it in a `www` folder, some in androids `databases` folder, etc.).
284-
285-
If you have an existing database file you want to load you can navigate from these directories using dot notation. e.g. `../www/myDb.sqlite`. Note that on iOS the file system is sand-boxed, so you cannot access files/directories outside your app bundle directories.
286-
287-
Alternatively, you can place/move your database file using one of the many react-native fs libraries.
288-
289-
## Enable compile-time options
290-
291-
By specifying pre-processor flags, you can enable optional features like FTS5, Geopoly, etc.
292-
293-
### iOS
294-
295-
Add a `post_install` block to your `<PROJECT_ROOT>/ios/Podfile` like so:
296-
297-
```ruby
298-
post_install do |installer|
299-
installer.pods_project.targets.each do |target|
300-
if target.name == "react-native-quick-sqlite" then
301-
target.build_configurations.each do |config|
302-
config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] << 'SQLITE_ENABLE_FTS5=1'
303-
end
304-
end
305-
end
306-
end
307-
```
308-
309-
Replace the `<SQLITE_FLAGS>` part with the flags you want to add.
310-
For example, you could add `SQLITE_ENABLE_FTS5=1` to `GCC_PREPROCESSOR_DEFINITIONS` to enable FTS5 in the iOS project.
311-
312-
### Android
313-
314-
You can specify flags via `<PROJECT_ROOT>/android/gradle.properties` like so:
315-
316-
```
317-
quickSqliteFlags="<SQLITE_FLAGS>"
318-
```
319-
320-
## Additional configuration
321-
322-
### App groups (iOS only)
323-
324-
On iOS, the SQLite database can be placed in an app group, in order to make it accessible from other apps in that app group. E.g. for sharing capabilities.
325-
326-
To use an app group, add the app group ID as the value for the `RNQuickSQLite_AppGroup` key in your project's `Info.plist` file. You'll also need to configure the app group in your project settings. (Xcode -> Project Settings -> Signing & Capabilities -> Add Capability -> App Groups)
327-
328-
## Community Discord
329-
330-
[Join the Margelo Community Discord](https://discord.gg/6CSHz2qAvA) to chat about react-native-quick-sqlite or other Margelo libraries.
331-
332-
## Oscar
333-
334-
react-native-quick-sqlite was originally created by [Oscar Franco](https://github.com/ospfranco). Thanks Oscar!
335-
336-
## License
337-
338-
MIT License.
17+
We will still provide bug fixes to `[email protected]` for the coming weeks/months.

‎package/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
## 🚧 `react-native-quick-sqlite` (DEPRECATED)
2+
3+
> [!IMPORTANT]
4+
> `react-native-quick-sqlite` has been deprecated in favor of [`react-native-nitro-sqlite`](https://github.com/margelo/react-native-nitro-sqlite).
5+
>
6+
7+
Please go to the [`react-native-nitro-sqlite`](https://github.com/margelo/react-native-nitro-sqlite) repository instead.
8+
9+
This is our new [Nitro module](https://nitro.margelo.com/) implementation of this library.
10+
11+
Nitro modules is a React Native library that let's us make the codebase more readable and easier to maintain. This way, we're able to fix bugs faster and implement new features! 🚀
12+
13+
### Future releases
14+
15+
From major version `9.0.0` on, this library will be shipped in the NPM package `react-native-nitro-sqlite`. New features are going to be implemented there.
16+
17+
We will still provide bug fixes to `[email protected]` for the coming weeks/months.

0 commit comments

Comments
 (0)