@balena/pinejs 20.0.0 → 20.0.1-build-rollbackable-migrations-guide-3ca5787deb64488fb03a0a6aa1a22633f4a61bec-2

package/.versionbot/CHANGELOG.yml

@@ -1,3 +1,15 @@
+- commits:
+    - subject: "Migrations.md: Update the rollbackable migrations guide"
+      hash: 3ca5787deb64488fb03a0a6aa1a22633f4a61bec
+      body: ""
+      footer:
+        Change-type: patch
+        change-type: patch
+      author: Thodoris Greasidis
+      nested: []
+  version: 20.0.1
+  title: ""
+  date: 2025-01-14T08:03:27.861Z
 - commits:
     - subject: Update node engines entry to clarify we don't actively support 21.x
       hash: bb75825da9bf23f38f1c0fe2bae301d171d84de6
@@ -50,7 +62,7 @@
       nested: []
   version: 20.0.0
   title: ""
-  date: 2025-01-10T11:35:44.131Z
+  date: 2025-01-10T18:15:01.199Z
 - commits:
     - subject: Use for-of loops in preference of lodash `_.forEach`
       hash: cef68084a2670d797559c2fd4a36825be67b7729
@@ -2175,6 +2187,7 @@
 
 
 
+
 
 
                                                                 As balena-lint
@@ -2221,6 +2234,7 @@
 
 
 
+
 
 
                                                                 As engine and npm is
@@ -2282,6 +2296,7 @@
 
 
 
+
 
 
                                                                 Ensure that the
@@ -2406,6 +2421,7 @@
 
 
 
+
 
 
                                                                 This also deprecates
@@ -2458,6 +2474,7 @@
 
 
 
+
 
 
                                                                 It can in fact be a
@@ -2511,6 +2528,7 @@
 
 
 
+
 
 
                                                                 We know what type
@@ -2569,6 +2587,7 @@
 
 
 
+
 
 
                                                                 Update
@@ -2738,6 +2757,7 @@
 
 
 
+
 
 
                                                                 This also deprecates

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file
 automatically by Versionist. DO NOT EDIT THIS FILE MANUALLY!
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+# v20.0.1
+## (2025-01-14)
+
+* Migrations.md: Update the rollbackable migrations guide [Thodoris Greasidis]
+
 # v20.0.0
 ## (2025-01-10)
 

package/VERSION

@@ -1 +1 @@
-20.0.0
+20.0.1

package/docs/Migrations.md

@@ -65,23 +65,6 @@ Async migrations are stored in the migrations folder, alongside synchronous migr
 The async migration query must have a `LIMIT` statement to limit the maximum number of affected rows per batch.
 
 
-### Async migration procedure
-* Deployment 1
-	- Add new column (with independent sync migration) to contain new data and add code accessing the new column.
-	- Update the service's implementation to set both the old & new column on each write.
-	- The service's implementation should only read the old column since the async migration still migrates data from old column to new column.
-	- Async migrator runs forever.
-* Deployment 2
-	- Finalize async migration => only sync migration part gets executed.
-	- Sync migration migrates all left over data from old column to new column.
-	- Update the service's implementation to only read the new column, but still write the old one as well.
-	- Mark the old field as optional in the sbvr if it isn't, or set a default value for it.
-* Deployment 3
-	- Update the service's implementation to stop settings the old column and remove it from the sbvr.
-	- Make the old field NULLable if it isn't.
-* Deployment 4
-	- Delete the old column with a sync migration.
-
 ### TS migration file format with SQL query string
 
 The placeholder `%%ASYNC_BATCH_SIZE%%` will be replaced with the value specified by asyncBatchSize parameter
@@ -147,4 +130,34 @@ export = {
 
 ```
 ### SQL query file (plain text)
-Plain SQL files are not supported as they cannot bundle async and sync migration statements in one file. Moreover they cannot carry migration metadata.
+Plain SQL files are not supported as they cannot bundle async and sync migration statements in one file. Moreover they cannot carry migration metadata.
+
+## Rollbackable no-down-time suggested migration procedure
+
+* Deployment 1
+	- Add the new column with an independent sync migration.
+	- Add an Async migrator that starts migrating data from the old column to new column (optional optimization for big tables).
+	- Update the service's implementation to set both the old & new column on each write.  
+	  The service's implementation should only read the old column, since not all data has been migrated to the new column yet.
+* Deployment 2
+	- Complete the data migration from the old to the new column:
+		- Either finalize the async migration from deployment 1 if you are using one.  
+		  This causes the sync part of the migration to execute.
+		- Or write a sync migration otherwise.
+	- Mark the new column as non-NULL if applicable as part of the above migration.
+	- Update the service's implementation to only read the new column, but still write to the old one as well.
+	- Test that the implementation works even if we keep the old column as NOT NULLable.  
+	  This makes sure that older service instances can still work during the deployment.
+	- Mark the old field as NULLable if it isn't.
+* Deployment 3
+	- Update the service's implementation to stop writing to the old column
+	- Remove the old column from the SBVR, leaving a TODO to also DROP if from the DB in a follow-up.  
+	  The old column needs to stay in the DB so that older service instances can still work during the deployment.
+* Deployment 4
+	- DROP the old column with a sync migration.
+
+### Testing rollbacks
+For each step, be sure and utilize testing to ensure you can safely rollback to previous versions of your service even with the updated database schemas (with data) deployed.
+Before merging each step, try rolling back your development environment to the previous deployment and make sure that everything still works without issues.
+The old deployment should be able to operate with DB records created by the new deployment and leave the DB in a valid state.
+Eg: While testing the PR for deployment 2 on your development environment, make sure that if you push deplpoyment 1 everything still works without issues.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balena/pinejs",
-  "version": "20.0.0",
+  "version": "20.0.1-build-rollbackable-migrations-guide-3ca5787deb64488fb03a0a6aa1a22633f4a61bec-2",
   "main": "out/server-glue/module.js",
   "type": "module",
   "repository": "git@github.com:balena-io/pinejs.git",
@@ -148,6 +148,6 @@
     "recursive": true
   },
   "versionist": {
-    "publishedAt": "2025-01-10T11:35:45.108Z"
+    "publishedAt": "2025-01-14T08:03:28.831Z"
   }
 }