database 0.2.7

  • Readme
  • Changelog
  • Example
  • Installing
  • new71

Pub Package Github Actions CI

Introduction #

Warning: this package isn't ready for use!

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.

Available adapters #

In this package #

In other packages #

The following packages are currently far from passing tests:

Available middleware classes #

In this package #

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 #

[0.2.7] - January 16, 2020

  • Improves documentation.

[0.2.6] - January 15, 2020

  • Improves the SQL API a bit.

[0.2.5] - January 15, 2020

  • Adds initial API for SQL databases.
  • Adds PostgreSQL support.

[0.2.4] - January 14, 2020

  • Fixes issues spotted during testing.

[0.2.3] - January 14, 2020

  • Fixes various small issues and improves documentation.

[0.2.2] - January 14, 2020

  • Fixes various issues.

[0.2.1] - January 13, 2020

  • Small improvements in documentation.

[0.2.0] - January 13, 2020

  • Initial release

example/example.dart

import 'package:database/database.dart';

void main() async {
  // Choose a database
  final database = MemoryDatabase();

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

  // Print results
  for (var snapshot in response.snapshots) {
    print('Employee ID: ${snapshot.document.documentId}');
    print('Employee name: ${snapshot.data['name']}');
    print('');
  }
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  database: ^0.2.7

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:database/database.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
43
Health:
Code health derived from static analysis. [more]
97
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
71
Learn more about scoring.

We analyzed this package on Jan 19, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.0
  • pana: 0.13.4

Health suggestions

Fix lib/src/database/primitives/timestamp.dart. (-2.96 points)

Analysis of lib/src/database/primitives/timestamp.dart reported 6 hints, including:

line 27 col 38: 'timezone' is deprecated and shouldn't be used.

line 31 col 49: 'timezone' is deprecated and shouldn't be used.

line 31 col 67: 'timezone' is deprecated and shouldn't be used.

line 39 col 12: 'timezone' is deprecated and shouldn't be used.

line 39 col 37: 'timezone' is deprecated and shouldn't be used.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.6.0 <3.0.0
built_collection ^4.0.0 4.3.2
built_value >=5.0.0 <8.0.0 7.0.8
charcode ^1.1.0 1.1.2
collection ^1.14.0 1.14.12
fixnum ^0.10.0 0.10.11
meta ^1.1.0 1.1.8
protobuf >=0.13.0 <2.0.0 1.0.1
universal_html ^1.1.0 1.1.12
universal_io ^0.8.5 0.8.6
Transitive dependencies
async 2.4.0
convert 2.1.1
csslib 0.16.1
html 0.14.0+3
matcher 0.12.6
path 1.6.4
petitparser 3.0.0
quiver 2.1.2+1
source_span 1.6.0
stack_trace 1.9.3
term_glyph 1.1.0
typed_data 1.1.6
xml 3.7.0
zone_local 0.1.2
Dev dependencies
pedantic ^1.8.0
test ^1.8.0