From cbcde53da63a9c085321ad09ad1493f5b6ddda09 Mon Sep 17 00:00:00 2001
From: Simon Binder <oss@simonbinder.eu>
Date: Sat, 28 May 2022 13:52:18 +0200
Subject: [PATCH] Docs: Describe how to export databases (#376)

---
 .../snippets/many_to_many_relationships.dart  |  4 +-
 .../pages/docs/Examples/existing_databases.md | 40 +++++++++++++++++--
 docs/pages/docs/Examples/relationships.md     |  5 ++-
 3 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/docs/lib/snippets/many_to_many_relationships.dart b/docs/lib/snippets/many_to_many_relationships.dart
index b284086a..68459071 100644
--- a/docs/lib/snippets/many_to_many_relationships.dart
+++ b/docs/lib/snippets/many_to_many_relationships.dart
@@ -22,9 +22,9 @@ class ShoppingCarts extends Table {
 @DataClassName('ShoppingCartEntry')
 class ShoppingCartEntries extends Table {
   // id of the cart that should contain this item.
-  IntColumn get shoppingCart => integer()();
+  IntColumn get shoppingCart => integer().references(ShoppingCarts, #id)();
   // id of the item in this cart
-  IntColumn get item => integer()();
+  IntColumn get item => integer().references(BuyableItems, #id)();
   // again, we could store additional information like when the item was
   // added, an amount, etc.
 }
diff --git a/docs/pages/docs/Examples/existing_databases.md b/docs/pages/docs/Examples/existing_databases.md
index 7e9c618b..deb1ad76 100644
--- a/docs/pages/docs/Examples/existing_databases.md
+++ b/docs/pages/docs/Examples/existing_databases.md
@@ -1,13 +1,23 @@
 ---
 data:
-  title: "Existing databases"
+  title: "Importing and exporting databases"
   description: Using drift with an existing database
 template: layouts/docs/single
 ---
 
 You can use drift with a pre-propulated database that you ship with your app.
+This page also describes how to export the underlying sqlite3 database used
+by drift into a file.
 
-## Including the database
+## Using an existing database
+
+You can use a `LazyDatabase` wrapper to run an asynchronous computation before drift
+opens a database.
+This is a good place to check if the target database file exists, and, if it doesnt,
+create one.
+This example shows how to do that from assets.
+
+### Including the database
 
 First, create the sqlite3 database you want to ship with your app.
 You can create a database with the [sqlite3 CLI tool](https://sqlite.org/cli.html)
@@ -24,7 +34,7 @@ flutter:
     - assets/my_database.db
 ```
 
-## Extracting the database
+### Extracting the database
 
 To initialize the database before using drift, you need to extract the asset from your
 app onto the device.
@@ -41,7 +51,7 @@ LazyDatabase _openConnection() {
     // for your app.
     final dbFolder = await getApplicationDocumentsDirectory();
     final file = File(p.join(dbFolder.path, 'app.db'));
-    
+
     if (!await file.exists()) {
         // Extract the pre-populated database file from assets
         final blob = await rootBundle.load('assets/my_database.db');
@@ -63,3 +73,25 @@ class MyDatabase extends _$MyDatabase {
 
   // ...
 ```
+
+## Exporting a databasee
+
+To export a sqlite3 database into a file, you can use the `VACUUM INTO` statement.
+Inside your database class, this could look like the following:
+
+```dart
+Future<void> exportInto(File file) async {
+  // Make sure the directory of the target file exists
+  await file.parent.create(recursive: true);
+
+  // Override an existing backup, sqlite expects the target file to be empty
+  if (file.existsSync()) {
+    file.deleteSync();
+  }
+
+  await customStatement('VACUUM INTO ?', [file.path]);
+}
+```
+
+You can now export this file containing the database of your app with another
+package like `flutter_share` or other backup approaches.
diff --git a/docs/pages/docs/Examples/relationships.md b/docs/pages/docs/Examples/relationships.md
index 6dbfb489..b9ec522e 100644
--- a/docs/pages/docs/Examples/relationships.md
+++ b/docs/pages/docs/Examples/relationships.md
@@ -15,7 +15,10 @@ queries in drift. First, we need to store some items that can be bought:
 {% include "blocks/snippet" snippets=snippets name="buyable_items" %}
 
 We're going to define two tables for shopping carts: One for the cart
-itself, and another one to store the entries in the cart:
+itself, and another one to store the entries in the cart.
+The latter uses [references]({{ '../Getting started/advanced_dart_tables.md#references' | pageUrl }})
+to express the foreign key constraints of referencing existing shopping
+carts or product items.
 
 {% include "blocks/snippet" snippets=snippets name="cart_tables" %}