sqlbrite

by square

square / sqlbrite

A lightweight wrapper around SQLiteOpenHelper which introduces reactive stream semantics to SQL oper...

4.7K Stars 447 Forks Last release: over 4 years ago (0.6.2) Apache License 2.0 304 Commits 24 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

SQL Brite

A lightweight wrapper around

SupportSQLiteOpenHelper
and
ContentResolver
which introduces reactive stream semantics to queries.

Deprecated

This library is no longer actively developed and is considered complete.

Its database features (and far, far more) are now offered by SQLDelight and its upgrading guide offers some migration help.

For content provider monitoring please use Copper instead.

Usage

Create a

SqlBrite
instance which is an adapter for the library functionality.
SqlBrite sqlBrite = new SqlBrite.Builder().build();

Pass a

SupportSQLiteOpenHelper
instance and a
Scheduler
to create a
BriteDatabase
.
BriteDatabase db = sqlBrite.wrapDatabaseHelper(openHelper, Schedulers.io());

A

Scheduler
is required for a few reasons, but the most important is that query notifications can trigger on the thread of your choice. The query can then be run without blocking the main thread or the thread which caused the trigger.

The

BriteDatabase.createQuery
method is similar to
SupportSQLiteDatabase.query
except it takes an additional parameter of table(s) on which to listen for changes. Subscribe to the returned
Observable
which will immediately notify with a
Query
to run.
Observable users = db.createQuery("users", "SELECT * FROM users");
users.subscribe(new Consumer() {
  @Override public void accept(Query query) {
    Cursor cursor = query.run();
    // TODO parse data...
  }
});

Unlike a traditional

query
, updates to the specified table(s) will trigger additional notifications for as long as you remain subscribed to the observable. This means that when you insert, update, or delete data, any subscribed queries will update with the new data instantly.
final AtomicInteger queries = new AtomicInteger();
users.subscribe(new Consumer() {
  @Override public void accept(Query query) {
    queries.getAndIncrement();
  }
});
System.out.println("Queries: " + queries.get()); // Prints 1

db.insert("users", SQLiteDatabase.CONFLICT_ABORT, createUser("jw", "Jake Wharton")); db.insert("users", SQLiteDatabase.CONFLICT_ABORT, createUser("mattp", "Matt Precious")); db.insert("users", SQLiteDatabase.CONFLICT_ABORT, createUser("strong", "Alec Strong"));

System.out.println("Queries: " + queries.get()); // Prints 4

In the previous example we re-used the

BriteDatabase
object "db" for inserts. All insert, update, or delete operations must go through this object in order to correctly notify subscribers.

Unsubscribe from the returned

Subscription
to stop getting updates.
final AtomicInteger queries = new AtomicInteger();
Subscription s = users.subscribe(new Consumer() {
  @Override public void accept(Query query) {
    queries.getAndIncrement();
  }
});
System.out.println("Queries: " + queries.get()); // Prints 1

db.insert("users", SQLiteDatabase.CONFLICT_ABORT, createUser("jw", "Jake Wharton")); db.insert("users", SQLiteDatabase.CONFLICT_ABORT, createUser("mattp", "Matt Precious")); s.unsubscribe();

db.insert("users", SQLiteDatabase.CONFLICT_ABORT, createUser("strong", "Alec Strong"));

System.out.println("Queries: " + queries.get()); // Prints 3

Use transactions to prevent large changes to the data from spamming your subscribers.

final AtomicInteger queries = new AtomicInteger();
users.subscribe(new Consumer() {
  @Override public void accept(Query query) {
    queries.getAndIncrement();
  }
});
System.out.println("Queries: " + queries.get()); // Prints 1

Transaction transaction = db.newTransaction(); try { db.insert("users", SQLiteDatabase.CONFLICT_ABORT, createUser("jw", "Jake Wharton")); db.insert("users", SQLiteDatabase.CONFLICT_ABORT, createUser("mattp", "Matt Precious")); db.insert("users", SQLiteDatabase.CONFLICT_ABORT, createUser("strong", "Alec Strong")); transaction.markSuccessful(); } finally { transaction.end(); }

System.out.println("Queries: " + queries.get()); // Prints 2

Note: You can also use try-with-resources with a

Transaction
instance.

Since queries are just regular RxJava

Observable
objects, operators can also be used to control the frequency of notifications to subscribers.
users.debounce(500, MILLISECONDS).subscribe(new Consumer() {
  @Override public void accept(Query query) {
    // TODO...
  }
});

The

SqlBrite
object can also wrap a
ContentResolver
for observing a query on another app's content provider.
BriteContentResolver resolver = sqlBrite.wrapContentProvider(contentResolver, Schedulers.io());
Observable query = resolver.createQuery(/*...*/);

The full power of RxJava's operators are available for combining, filtering, and triggering any number of queries and data changes.

Philosophy

SQL Brite's only responsibility is to be a mechanism for coordinating and composing the notification of updates to tables such that you can update queries as soon as data changes.

This library is not an ORM. It is not a type-safe query mechanism. It won't serialize the same POJOs you use for Gson. It's not going to perform database migrations for you.

Some of these features are offered by SQL Delight which can be used with SQL Brite.

Download

implementation 'com.squareup.sqlbrite3:sqlbrite:3.2.0'

For the 'kotlin' module that adds extension functions to

Observable
:
groovy
implementation 'com.squareup.sqlbrite3:sqlbrite-kotlin:3.2.0'

Snapshots of the development version are available in Sonatype's

snapshots
repository.

License

Copyright 2015 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.