From e43a5dea60764780e6f6d1d6e725122a06c2c724 Mon Sep 17 00:00:00 2001
From: Simon Binder <simon@binder-online.biz>
Date: Thu, 28 Feb 2019 22:28:46 +0100
Subject: [PATCH] Copy updated readme

---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.md b/README.md
index 79743827..53eb8a53 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,34 @@ If a column is nullable or has a default value (this includes auto-increments),
 can be omitted. All other fields must be set and non-null. The `insert` method will throw
 otherwise.
 
+### Custom statements
+You can also issue custom queries by calling `customUpdate` for update and deletes and
+`customSelect` or `customSelectStream` for select statements. Using the todo example
+above, here is a simple custom query that loads all categories and how many items are
+in each category:
+```dart
+class CategoryWithCount {
+  final Category category;
+  final int count; // amount of entries in this category
+
+  CategoryWithCount(this.category, this.count);
+}
+
+// then, in the database class:
+Stream<List<CategoryWithCount>> categoriesWithCount() {
+    // select all categories and load how many associated entries there are for
+    // each category
+    return customSelectStream(
+        'SELECT *, (SELECT COUNT(*) FROM todos WHERE category = c.id) AS "amount" FROM categories c;',
+        readsFrom: Set.of([todos, categories])).map((rows) {
+      // when we have the result set, map each row to the data class
+      return rows
+          .map((row) => CategoryWithCount(Category.fromData(row.data, this), row.readInt('amount')))
+          .toList();
+    });
+  }
+```
+
 ## Migrations
 Sally provides a migration API that can be used to gradually apply schema changes after bumping
 the `schemaVersion` getter inside the `Database` class. To use it, override the `migration`
@@ -226,6 +254,8 @@ You can also add individual tables or drop them.
 
 ## TODO-List and current limitations
 ### Limitations (at the moment)
+Please note that a workaround for most on this list exists with custom statements.
+
 - No joins
 - No `group by` or window functions
 - Custom primary key support is very limited