database 0.2.0

A vendor-agnostic database API. Various adapters are available, such as in-memory database, browser APIs, ElasticSearch, and others.

Introduction

This enables Dart developers to use document databases and information retrieval systems. The package works in all platforms (Flutter, browser, server). Licensed under the Apache License 2.0.

Warning: breaking changes are likely before the project freezes the APIs.

Contributing

Anyone can help this open-source project!

For the first contribution, create a pull request at Github.

Repeat contributors may be given Github permissions to push directly into the repository. If you have been granted such permission, code review is not necessary for you (but it's still a good habit).

API reference

• pub.dev/documentation/database/latest/

Available adapters

General-purpose

• BrowserDatabase (API, source)
  • Uses browser APIs such as window.localStorage.
• CachingDatabase (API, source)
  • Caches data in some other database.
• GrpcDatabase (API, source)
  • A GRPC client. You can also find a server implementation.
• MemoryDatabase (API, source)
  • Stores data in memory.
• SchemaUsingDatabase (API, source)
  • Enforces schemas on reads/writes.
• SearchableDatabase
  • A search engine for Flutter / web applications. Found in the package search.

For using various products

• Algolia (website)
  • Use adapter Algolia (API, source)
  • The adapter does not pass all tests. You can help!
• Azure Cosmos DB (website)
  • Use adapter AzureCosmosDB (API, source)
  • The adapter does not pass all tests. You can help!
• Azure Cognitive Search (website)
  • Use adapter AzureCognitiveSearch (API, source)
  • The adapter does not pass all tests. You can help!
• ElasticSearch (website)
  • Use adapter ElasticSearch (API, source)
  • The adapter does not pass all tests. You can help!
• Google Cloud Database (website)
  • Use adapter GoogleCloudDatastore (API, source)
  • The adapter does not pass all tests. You can help!
• Google Cloud Firestore (website)
  • In browser, use adapter Firestore (API, source)
  • In Flutter, use adapter FirestoreFlutter (source) in "package:firestore_adapter_cloud_firestore/adapter.dart".
  • The adapter does not pass all tests. You can help!

Getting started

Add dependency

In pubspec.yaml, add:

dependencies:
  database: any

Simple usage

import 'package:database/adapters.dart';
import 'package:database/database.dart';

Future<void> main() async {
  //
  // Set default database
  //
  Database.freezeDefaultInstance(
    MemoryDatabase(), // <-- Choose the right database for you
  );

  //
  // Insert documents
  //
  final database = Database.defaultInstance;
  database.collection('employee').newDocument().insert({
    'name': 'Jane',
    'title': 'software developer',
    'skills': ['dart'],
  });
  database.collection('employee').newDocument().insert({
    'name': 'John',
    'title': 'software developer',
    'skills': ['javascript'],
  });

  //
  // Search documents
  //
  final collection = database.collection('employee');
  final response = await collection.search(
    query: Query.parse(
      '"software developer" (dart OR javascript)'
      skip: 0,
      take: 10,
    ),
  );
}

Recipes

Insert, update, delete

// Generate a random 128-bit identifier for our document
final document = database.collection('greetings').newDocument();

// Insert
await document.insert(data:{
  'example': 'initial value',
});

// Upsert ("insert or update")
await document.upsert(data:{
  'example': 'upserted value',
});

// Update
await document.update(data:{
  'example': 'updated value',
})

// Delete
await document.delete();

Searching

final result = await database.collection('employee').search(
  query: Query.parse('name:(John OR Jane)')
);

for (var snapshot in result.snapshots) {
  // ...
}

Possible filters

• Logical
  • AndFilter([ValueFilter('f0'), ValueFilter('f1')])
  • OrFilter([ValueFilter('f0'), ValueFilter('f1')])
  • NotFilter(ValueFilter('example'))
• Structural
  • ListFilter(items: ValueFilter('value'))
  • MapFilter({'key': ValueFilter('value')})
• Primitive
  • ValueFilter(3.14)
  • RangeFilter(min:3, max:4)
  • RangeFilter(min:3, max:4, isExclusiveMin:true, isExclusiveMax:true)
• Natural language filters
  • KeywordFilter('example')

Parsing filters

The package supports parsing query strings. The syntax is inspired by Lucene and Google Search.

final query = Query.parse('New York Times date:>=2020-01-01');

Examples of supported queries:

• New York Times
  • Matches keywords "New", "York", and "Times". The underlying search engine may decide to focus on the three words separately, sequence "New York", or sequence "New York Times".
• "New York Times"
  • A quoted keyword ensures that the words must appear as a sequence.
• cat AND dog
  • Matches keywords "cat" and "dog" (in any order).
• cat OR dog
  • Matches keyword "cat", "dog", or both.
• pet -cat
  • Matches keyword "pet", but excludes documents that match keyword "cat".
• color:brown
  • Color matches keyword "brown".
• color:="brown"
  • Color is equal to "brown".
• weight:>=10
  • Weight is greater than or equal to 10.
• weight:[10 TO 20]
  • Weight is between 10 and 20, inclusive.
• weight:{10 TO 20}
  • Weight is between 10 and 20, exclusive.
• (cat OR dog) AND weight:>=10
  • An example of grouping filters.

Testing

import 'package:database/adapters.dart';
import 'package:database/database.dart';

void main() {
  setUp(() {
    Database.defaultInstance = MemoryDatabase();
    addTeardown(() {
      Database.defaultInstance = null;
    });
  });

  test('example #1', () {
    // ...
  });

  test('example #2', () {
    // ...
  });
}