From 15b18db7517e4218cb89ab5609f170b6ef8d7959 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=96=BD=E5=9B=BD=E9=B9=8F?= <1033404553@qq.com>
Date: Wed, 13 Oct 2021 12:20:34 +0800
Subject: [PATCH] Update migrations.md

---
 docs/migrations.md | 93 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 78 insertions(+), 15 deletions(-)

diff --git a/docs/migrations.md b/docs/migrations.md
index 8736cdb4..fcce717d 100644
--- a/docs/migrations.md
+++ b/docs/migrations.md
@@ -9,33 +9,96 @@ At last, use `addMigrations()` on the obtained database builder to add migration
 Don't forget to trigger the code generator again, to create the code for handling the new entity.
 
 ```dart
-// update entity with new 'nickname' field
-@Entity(tableName: 'person')
-class Person {
+////////////////////////////////////////
+// version 1   
+// create base table posts
+////////////////////////////////////////
+@Entity(tableName: 'posts')
+class PostEntity {
   @PrimaryKey(autoGenerate: true)
   final int id;
 
-  @ColumnInfo(name: 'custom_name')
-  final String name;
+  final String content;
 
-  final String nickname;
+  PostEntity(this.id, this.content);
+}
+
+@Database(version: 1, entities: [PostEntity])
+abstract class AppDatabase extends FloorDatabase {
+  // dao...
+}
+
+// version 1 can auto create table
+final database = await $FloorAppDatabase
+    .databaseBuilder('app_database.db')
+    .build();
+    
+////////////////////////////////////////
+// version 2
+// => add new comments table
+////////////////////////////////////////
++@Entity(tableName: 'comments')
++class CommentEntity {
++  @PrimaryKey(autoGenerate: true)
++  final int id;
++
++  final String content;
++
++  CommentEntity(this.id, this.content);
++}
+
+// version 1 => 2, entities => add CommentEntity
+// here, floor can auto create all table on new install app
+// !!! If is to upgrade, need your own hand writing logic
++@Database(version: 2, entities: [PostEntity, CommentEntity])
+abstract class AppDatabase extends FloorDatabase {
+  // dao...
+}
+
++final migration1to2 = Migration(1, 2, (database) async {
++ // you can copy database.g.dart generate sql code
++ await database.execute('create table comments');
++});
+
+final database = await $FloorAppDatabase
+    .databaseBuilder('app_database.db')
++   .addMigrations([migration1to2])
+    .build();
+ 
+////////////////////////////////////////
+// version 3
+// => update entity with new 'nickname' field
+////////////////////////////////////////
+@Entity(tableName: 'comments')
+class CommentEntity {
+  @PrimaryKey(autoGenerate: true)
+  final int id;
+
+  final String content;
+  
++ final String nickname;
 
-  Person(this.id, this.name, this.nickname);
++ CommentEntity(this.id, this.content, this.nickname);
 }
 
-// bump up database version
-@Database(version: 2)
+// version 2 => 3
+// here, floor can auto create all table on new install app (Including the newly added field nickname)
+// !!! If is to upgrade, need your own hand writing logic
++@Database(version: 3, entities: [PostEntity, CommentEntity])
 abstract class AppDatabase extends FloorDatabase {
-  PersonDao get personDao;
+  // dao...
 }
 
-// create migration
-final migration1to2 = Migration(1, 2, (database) async {
-  await database.execute('ALTER TABLE person ADD COLUMN nickname TEXT');
-});
++final migration2to3 = Migration(2, 3, (database) async {
++  await database.execute('ALTER TABLE person ADD COLUMN nickname TEXT');
++});
 
+// now has 3 case
+// case 1: new install  => floor can auto create all table (You don't need to care about anything)
+// case 2: 1 upgrade 3  => floor can exec migration1to2 and migration2to3
+// case 3: 2 upgrade 3  => floor only exec migration2to3
 final database = await $FloorAppDatabase
     .databaseBuilder('app_database.db')
-    .addMigrations([migration1to2])
++   .addMigrations([migration1to2, migration2to3])
     .build();
 ```