database 0.2.4

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

Introduction

Warning: this package is not ready for general use yet.

The package aims to be usable with:

• SQL databases
• Document databases (like Google Cloud Firestore)
• Search engines (like ElasticSearch/Lucene)

The current iteration of the API has a single API for all three database paradigms. This is somewhat unconventional and carries a risk of confusion when developers read documentation or make assumptions about behavior. We evaluate the current approach, and if it doesn't seem right, split the unified API into two or three libraries.

Any feedback on the design is appreciated. The project is licensed under the Apache License 2.0. If this project interests you, please consider becoming a developer/maintainer.

API reference

• pub.dev/documentation/database/latest/

Available adapters

In this package

• BrowserDatabase (Github)
  • Stores data using browser APIs.
• MemoryDatabase (Github)
  • Stores data in memory.

In other packages

• database_adapter_elasticsearch (Github)
  • For using Elasticsearch.
• Have a package? Add it here!

The following packages are currently far from passing our shared test suite:

• database_adapter_algolia (Github)
  • For using Algolia.
• database_adapter_azure (Github)
  • For using Azure Cosmos DB.
  • For using Azure Cognitive Search.
• database_adapter_gcloud (Github)
  • For using Google Cloud Database.
• database_adapter_grpc (Github)
  • For communicating with a server using a GRPC channel.
• database_adapter_firestore (Github)
  • For using Google Cloud Firestore.
• database_adapter_firestore_flutter (Github)
  • For using Google Cloud Firestore.

Available middleware classes

In this package

• CachingDatabase (Github)
  • Caches data in another database (such as MemoryDatabase).
• SchemaUsingDatabase (Github)
  • Enforces schemas on reads/writes.

Other packages

• search (Github)
  • An minimalistic search engine for small collections.
• Have a package? Add it here!

Contributing

This is an open-source community project. Anyone, even beginners, can contribute.

This is how you contribute:

1. Fork github.com/dint-dev/dint by pressing fork button.
2. Clone your fork to your computer: git clone github.com/your_username/database
3. Run ./tool/pub_get.sh to get dependencies for all packages.
4. Do your changes.
5. When you are done, commit changes with git add -A and git commit.
6. Push changes to your personal repository: git push origin
7. Go to github.com/dint-dev/dint and create a pull request.

Contributors may be added to the Github organization team so they can save time by pushing directly to the repository.

Getting started

Add dependency

In pubspec.yaml, add:

dependencies:
  database: any

Construct instance

import 'package:database/database.dart';

Future<void> main() async {
  //
  // Use in-memory database
  //
  final database = MemoryDatabase();

  // ...
}

Write and read documents

// Insert
final document = await database.collection('employee').insert({
  'name': 'Jane',
  'title': 'software developer',
  'skills': ['dart'],
});

// Update
await document.update({
  // ...
});

// Read
await snapshot = document.get();

// DElete
await document.delete();

Query documents

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

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

Introduction to 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)
  • RangeFilter(min:3, max:4, isExclusiveMin:true, isExclusiveMax:true)
  • GeoPointFilter(near:GeoPoint(1.23, 3.45)
• SQL filters
  • SqlFilter('SELECT * FROM table WHERE x ', 3.14)
• Natural language filters
  • KeywordFilter('example')
    • Keyword queries (KeyFilter) are very expensive unless you have configured a search engine such as ElasticSearch/Lucene. The default implementation visits every document in the collection and does a substring search.
    • To prevent unintentional visit to every document, remote databases should throw UnsuportedError unless they support keyword search.

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.

Supported primitives

• null
• bool
• int
• Int64
• double
• Date
• DateTime
• Timestamp
• GeoPoint
• String
• Uint8List
• List
• Map<String,Object>