You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: GRDB/Documentation.docc/Migrations.md
+8-10Lines changed: 8 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -85,9 +85,9 @@ try dbQueue.read { db in
85
85
86
86
## Good Practices for Defining Migrations
87
87
88
-
**A good migration is a migration that you never modify once it has shipped.**
88
+
**A good migration is a migration that is never modified once it has shipped.**
89
89
90
-
It is must easier to control the schema of all databases deployed on your users' devices when migrations define a stable timeline of schema versions. For this reason, make sure your the definition of your migrations define tables and columns with **strings**:
90
+
It is must easier to control the schema of all databases deployed on users' devices when migrations define a stable timeline of schema versions. For this reason, it is recommended that migrations define the database schema with **strings**:
91
91
92
92
```swift
93
93
migrator.registerMigration("createLibrary") { db in
@@ -105,11 +105,9 @@ migrator.registerMigration("createLibrary") { db in
105
105
}
106
106
```
107
107
108
-
Migrations should talk to the database, only to the database, and use the database language: **strings**. This makes sure you will never have to change the Swift code of your migrations in the future.
109
-
110
-
Migrations and the rest of the application code do not live at the same "moment". Migrations describe the past states of the database, while the rest of the application code targets the latest one. This difference is the reason why repeating a column name in a migration and in a Swift struct or class is a good practice. It is not a violation of the [DRY principle](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).
111
-
108
+
In other words, migrations should talk to the database, only to the database, and use the database language. This makes sure the Swift code of any given migrations will never have to change in the future.
112
109
110
+
Migrations and the rest of the application code do not live at the same "moment". Migrations describe the past states of the database, while the rest of the application code targets the latest one only. This difference is the reason why migrations should not depend on application types.
SQLite directly supports a [limited set of schema alterations](https://www.sqlite.org/lang.html). Many of them are available as `Database` methods such as ``Database/create(table:options:body:)``, etc.
138
136
139
-
> You should prefer the Swift API, because GRDB only enables apis that are available on SQLite version that ships on your target operating system.
137
+
> You should prefer the Swift API, because GRDB only enables apis that are available on SQLite version that ships on the target operating system.
140
138
141
139
Arbitrary changes to the schema design of any table are still possible, by recreating the table. For example:
142
140
@@ -176,15 +174,15 @@ The detailed sequence of operations for recreating a database table is:
176
174
## Foreign Key Checks
177
175
178
176
The technique described in the previous <doc:Migrations#Advanced-Database-Schema-Changes> chapter creates very undesired churn w.r.t. foreign keys:
179
-
by default, each migration temporarily disables foreign keys, and performs a full check of all foreign keys in your database before it is committed on disk.
177
+
by default, each migration temporarily disables foreign keys, and performs a full check of all foreign keys in the database before it is committed on disk.
180
178
181
-
When your database becomes very big, those checks may have a noticeable impact on migration performances. You'll know this by instrumenting your migrations, and looking for the time spent in the `checkForeignKeys` method.
179
+
When the database becomes very big, those checks may have a noticeable impact on migration performances. You'll know this by profiling migrations, and looking for the time spent in the `checkForeignKeys` method.
182
180
183
181
You can make those migrations faster, but this requires a little care.
184
182
185
183
**Your first mitigation technique is immediate foreign key checks.**
186
184
187
-
When you register a migration with `.immediate` foreign key checks, the migration does not temporarily disable foreign keys, and does not need to perform a deferred full check of all foreign keys in your database:
185
+
When you register a migration with `.immediate` foreign key checks, the migration does not temporarily disable foreign keys, and does not need to perform a deferred full check of all foreign keys in ther database:
188
186
189
187
```swift
190
188
migrator.registerMigration("Faster migration", foreignKeyChecks: .immediate) { db in... }
0 commit comments