From 8880348fd2ae2336bfb1adc36eb931686827a743 Mon Sep 17 00:00:00 2001 From: Patrick Doyle Date: Fri, 9 Feb 2024 17:13:06 -0500 Subject: [PATCH] Document Sequoia refurbish limitations. --- docs/USERS.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/USERS.md b/docs/USERS.md index 3dff48fb..f74b2bae 100644 --- a/docs/USERS.md +++ b/docs/USERS.md @@ -711,7 +711,7 @@ The second step is to ensure that any older versions of the server are shut down This will prevent _new_ objects from being created without the new field. The third step is to change external systems so they always supply the new field; -for `MongoDriver`, this is accomplished by calling `MongoDriver.refurbish()`. +for `MongoDriver`, this is accomplished by calling `MongoDriver.refurbish()`.[^1] This method rewrites the entire bosk state in the new format, which has the effect of adding the new field to all existing objects. Finally, you can remove the `@Polyfill` field, @@ -729,6 +729,11 @@ then a read from `/a/b` will return the polyfill node, but a write to `/a/b/c` will be ignored, which could be confusing. We hope to overcome this shortcoming in the near future. +[^1]: Note that if your database is using the Sequoia format, and you refurbish it to the Pando format, +there is a brief window (before the change events arrive) when writes to the old Sequoia driver will +be silently ignored. While refurbishing from Sequoia to a different format, +ensure the bosk is quiescent (not performing any updates), or is performing a `flush()` before each update. + #### Compliance rules `BoskDriver` implementations typically take the form of a stackable layer that accepts update requests, performs some sort of processing, and forwards the (possibly modified) requests to the next driver in the chain (the _downstream_) driver.