From 22815370baf7ddc2b38674111f155af0d152c554 Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Thu, 28 Mar 2024 15:08:13 +0100 Subject: [PATCH] doc: Clarify warning in cleanup tool (#543) --- .../cleanup/javadsl/EventSourcedCleanup.scala | 10 ++++--- .../scaladsl/EventSourcedCleanup.scala | 10 +++++-- docs/src/main/paradox/cleanup.md | 30 +++++++++++-------- 3 files changed, 30 insertions(+), 20 deletions(-) diff --git a/core/src/main/scala/akka/persistence/r2dbc/cleanup/javadsl/EventSourcedCleanup.scala b/core/src/main/scala/akka/persistence/r2dbc/cleanup/javadsl/EventSourcedCleanup.scala index 0c4f461b..3e94e8fd 100644 --- a/core/src/main/scala/akka/persistence/r2dbc/cleanup/javadsl/EventSourcedCleanup.scala +++ b/core/src/main/scala/akka/persistence/r2dbc/cleanup/javadsl/EventSourcedCleanup.scala @@ -17,11 +17,13 @@ import akka.annotation.ApiMayChange import akka.persistence.r2dbc.cleanup.scaladsl /** - * Java API: Tool for deleting all events and/or snapshots for a given list of `persistenceIds` without using persistent - * actors. It's important that the actors with corresponding `persistenceId` are not running at the same time as using - * the tool. + * Java API: Tool for deleting events and/or snapshots for a given list of `persistenceIds` without using persistent + * actors. * - * WARNING: deleting events is generally discouraged in event sourced systems. + * When running an operation with `EventSourcedCleanup` that deletes all events for a persistence id, the actor with + * that persistence id must not be running! If the actor is restarted it would in that case be recovered to the wrong + * state since the stored events have been deleted. Delete events before snapshot can still be used while the actor is + * running. * * If `resetSequenceNumber` is `true` then the creating entity with the same `persistenceId` will start from 0. * Otherwise it will continue from the latest highest used sequence number. diff --git a/core/src/main/scala/akka/persistence/r2dbc/cleanup/scaladsl/EventSourcedCleanup.scala b/core/src/main/scala/akka/persistence/r2dbc/cleanup/scaladsl/EventSourcedCleanup.scala index 1138ee9c..18660af5 100644 --- a/core/src/main/scala/akka/persistence/r2dbc/cleanup/scaladsl/EventSourcedCleanup.scala +++ b/core/src/main/scala/akka/persistence/r2dbc/cleanup/scaladsl/EventSourcedCleanup.scala @@ -24,9 +24,13 @@ import akka.persistence.r2dbc.R2dbcSettings import akka.persistence.r2dbc.internal.R2dbcExecutorProvider /** - * Scala API: Tool for deleting all events and/or snapshots for a given list of `persistenceIds` without using - * persistent actors. It's important that the actors with corresponding `persistenceId` are not running at the same time - * as using the tool. + * Scala API: Tool for deleting events and/or snapshots for a given list of `persistenceIds` without using persistent + * actors. + * + * When running an operation with `EventSourcedCleanup` that deletes all events for a persistence id, the actor with + * that persistence id must not be running! If the actor is restarted it would in that case be recovered to the wrong + * state since the stored events have been deleted. Delete events before snapshot can still be used while the actor is + * running. * * If `resetSequenceNumber` is `true` then the creating entity with the same `persistenceId` will start from 0. * Otherwise it will continue from the latest highest used sequence number. diff --git a/docs/src/main/paradox/cleanup.md b/docs/src/main/paradox/cleanup.md index 60c9c85c..ee4ca739 100644 --- a/docs/src/main/paradox/cleanup.md +++ b/docs/src/main/paradox/cleanup.md @@ -2,15 +2,9 @@ ## Event Sourced cleanup tool -@@@ warning - -When running any operation with `EventSourcedCleanup` for a persistence id, the actor with that persistence id must -not be running! - -@@@ - If possible, it is best to keep all events in an event sourced system. That way new @extref:[Akka Projection R2DBC](akka-projection:r2dbc.html) -can be re-built. +can be re-built. A @ref[Projection can also start or continue from a snapshot](./query.md#eventsbyslicesstartingfromsnapshots), +and then events can be deleted before the snapshot. In some cases keeping all events is not possible or must be removed for regulatory reasons, such as compliance with GDPR. `EventSourcedBehavior`s can automatically snapshot state and delete events as described in the @@ -32,6 +26,15 @@ not emit further events after that and typically stop itself if it receives more * Delete events before snapshot for one or many persistence ids * Delete events before a timestamp +@@@ warning + +When running an operation with `EventSourcedCleanup` that deletes all events for a persistence id, +the actor with that persistence id must not be running! If the actor is restarted it would in that +case be recovered to the wrong state since the stored events have been deleted. Delete events before +snapshot can still be used while the actor is running. + +@@@ + The cleanup tool can be combined with the @ref[query plugin](./query.md) which has a query to get all persistence ids. Java @@ -42,15 +45,16 @@ Scala ## Durable State cleanup tool +@apidoc[DurableStateCleanup] operations include: + +* Delete state for one or many persistence ids + @@@ warning When running any operation with `DurableStateCleanup` for a persistence id, the actor with that persistence id must -not be running! +not be running! If the actor is restarted it would in that case be recovered to the wrong state since the stored state +hase been deleted. @@@ -@apidoc[DurableStateCleanup] operations include: - -* Delete state for one or many persistence ids - The cleanup tool can be combined with the @ref[query plugin](./query.md) which has a query to get all persistence ids.