summaryrefslogtreecommitdiff
path: root/doc/development
diff options
context:
space:
mode:
authorGrzegorz Bizon <grzesiek.bizon@gmail.com>2017-07-20 13:45:13 +0200
committerGrzegorz Bizon <grzesiek.bizon@gmail.com>2017-07-20 13:46:13 +0200
commit367a89551165c5ca5d540bf58c2b428db1b57462 (patch)
tree283bfbdcc2655fcbdf2d8c552d761acde8c95470 /doc/development
parent001dd56e7bfd04d22f5437569ba8aa60a0317a3e (diff)
downloadgitlab-ce-367a89551165c5ca5d540bf58c2b428db1b57462.tar.gz
Extend background migration development guidelines
Diffstat (limited to 'doc/development')
-rw-r--r--doc/development/background_migrations.md30
1 files changed, 30 insertions, 0 deletions
diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md
index 72a34aa7de9..a4bf0287412 100644
--- a/doc/development/background_migrations.md
+++ b/doc/development/background_migrations.md
@@ -31,6 +31,18 @@ It's also possible for different migrations to be executed at the same time.
This means that different background migrations should not migrate data in a
way that would cause conflicts.
+## Idempotence
+
+Background migrations are executed in a context of a Sidekiq process.
+Usual Sidekiq rules apply, especially the rule that jobs should be small
+and idempotent.
+
+See [Sidekiq best practices guidelines](https://github.com/mperham/sidekiq/wiki/Best-Practices)
+for more details.
+
+Make sure that in case that your migration job is going to be retried a data
+integrity is guarateed.
+
## How It Works
Background migrations are simple classes that define a `perform` method. A
@@ -212,3 +224,21 @@ end
This migration will then process any jobs for the ExtractServicesUrl migration
and continue once all jobs have been processed. Once done you can safely remove
the `services.properties` column.
+
+## Testing
+
+It is possible to test a background migrations scheduling migration and a
+cleanup migration using `:migration` RSpec tag. See README in specs/migration/
+directory.
+
+When you do that, keep in mind that `before` and `after` RSpec hooks are going
+to migrate you database down and up, which can result in another background
+migrations being called. That means that using `spy` test doubles with
+`have_received` is encouraged, instead of using regular test doubles, because
+your expectation defined in a `it` block can conflict with what is being
+called in RSpec hooks. See gitlab-org/gitlab-ce#35351 for more details.
+
+## Best practices
+
+1. Make sure that background migration jobs are idempotent.
+1. Make sure that tests you write are not false positives.