Add rollback (w db) steps to upgrade page#397
Conversation
| 1. Check out the migration files for the target kagent version. | ||
| ```bash | ||
| git clone https://github.com/kagent-dev/kagent.git | ||
| cd kagent && git checkout v$ROLLBACK_VERSION | ||
| ``` | ||
|
|
||
| 2. Run `golang-migrate` down to the target schema version for each track. You can check the `go/core/pkg/migrations/core/` directory in the target release to find the highest migration version number. | ||
| ```bash | ||
| # Core track | ||
| migrate -path go/core/pkg/migrations/core \ | ||
| -database "$DATABASE_URL" \ | ||
| goto <target-migration-version> | ||
|
|
||
| # Vector track (if vector features are enabled) | ||
| migrate -path go/core/pkg/migrations/vector \ | ||
| -database "$DATABASE_URL" \ | ||
| goto <target-vector-migration-version> | ||
| ``` |
There was a problem hiding this comment.
I think the steps laid out here are slightly easier and can be combined with this section. For example, I'm not sure you need to checkout the migration files locally if you don't want.
|
|
||
| 3. After the database is at the correct schema version, roll back the kagent application by following the steps in the [previous section](#steps-to-roll-back). | ||
|
|
||
| > **Note**: Database migration version numbers do not correspond directly to kagent release versions. Always check the migration files in the target release to identify the correct target migration version. |
There was a problem hiding this comment.
Can you clarify this? I'm not sure why they wouldn't line up. I believe we use the same versioning for the git tags as we do for the release.
Rachael-Graham
force-pushed
the
rlg-db
branch
2 times, most recently
from
08311e4 to
b5c2d34
Compare
Rachael-Graham
force-pushed
the
rlg-db
branch
2 times, most recently
from
04a0df7 to
33f4b1a
Compare
| kubectl -n kagent scale deploy/kagent-controller --replicas=0 | ||
| ``` | ||
|
|
||
| 4. Reset the core track. The `github://` source references the migration files directly from the release tag without a local checkout. Replace `<rollback-migration-version>` with the highest migration sequence number in the `go/core/pkg/migrations/core/` directory of your target (rollback) release, which you can browse at `https://github.com/kagent-dev/kagent/tree/v<target-version>/go/core/pkg/migrations/core/`. For the database connection string, see [Database configuration](/docs/kagent/operations/operational-considerations#database-configuration). |
There was a problem hiding this comment.
For something like: https://github.com/kagent-dev/kagent/tree/v<target-version>/go/core/pkg/migrations/core/, would it be better to put the rollback version ("target version") in step 1's export as an env var and reference it here?
So something like:
export CURRENT_VERSION=<current-version>
export ROLLBACK_VERSION=<previous-version>Then use it in the step's text with: https://github.com/kagent-dev/kagent/tree/v${ROLLBACK_VERSION}/go/core/pkg/migrations/core/
I feel like it is clearer to provide env vars instead of something like <rollback-migration-version> or <target-version> in general, but maybe that's just me. I think it probably matters more in the bash blocks, but just a suggestion.
|
|
||
| The source must be the current (newer) version that you are rolling back from, because it contains the down migrations needed to reverse the schema changes. The `goto` target is the highest migration sequence number present in the version that you are rolling back to. | ||
|
|
||
| For example, if you are rolling back from `v0.10.2` (migrations up to `10`) to `v0.9.4` (migrations up to `8`), you use the `v0.10.2` source and `goto 8`. |
There was a problem hiding this comment.
Maybe we ground this in a real example if we are doing it in the docs
There was a problem hiding this comment.
So let's say you go back from 0.9.7 to 0.9.6 (where 0.9.7 added migration 5 to the core track).
You would have goto 4 in that case.
|
|
||
| ### Reset the database before rolling back further | ||
|
|
||
| If you need to roll back more than one minor kagent version, you must first reset the database schema to match the target version before rolling back the application. Use `golang-migrate` directly against the migration files. |
There was a problem hiding this comment.
One more thing, you need to roll back one minor at a time and there might be data loss going more than one minor back as our approach is backwards compatibility of one minor version back.
There was a problem hiding this comment.
Added in a note on 133 and in the original desc on 94
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Co-authored-by: Art <artberger@users.noreply.github.com> Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Co-authored-by: Art <artberger@users.noreply.github.com> Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Co-authored-by: Art <artberger@users.noreply.github.com> Signed-off-by: Rachael Graham <rachael.graham@solo.io>
3 participants
for kagent-dev/kagent#1963