Migrations

Overview

This topic explains how to use LaunchDarkly SDKs to manage migrations or modernizations. You might use this feature if you are optimizing queries, upgrading to new tech stacks, migrating from one database to another, or other similar technology changes. This feature is available for server-side and edge SDKs only.

Prerequisites

Before you configure your SDK to manage a migration, you must complete the following prerequisites:

  • Create a migration feature flag. This is a temporary flag used to migrate data or systems while keeping your application available and disruption free. Migration flags break up the switch from an old to a new implementation into a series of recommended stages where movement from one stage to the next is done in incremental steps.
  • Determine how many stages your migration will have. You can select from the following options as part of creating a migration feature flag:
    • Two stages: For migrations where you cannot run the new system and old system at the same time
    • Four stages: For migrations that can run both the new and old systems at the same time
    • Six stages: For migrations where you need to migrate READS and WRITES separately

To learn more, read Migration flags.

Use SDKs to manage a migration

Depending on how you created your migration feature flag, your migration will have two, four, or six stages. At each stage, you will be reading data from the old destination, the new destination, or both. You will also be writing data to the old destination, the new destination, or both. At each stage, only one of these destinations is considered the authoritative source. In the LaunchDarkly SDK, you can determine which stage of the migration your application is currently in, execute the appropriate read and write methods, and then compare the results to check correctness and view any errors or changes in latency.

The following table describes the stages and which destination is authoritative. Remember that not all migrations will use all stages.

StageRead fromWrite toAuthoritative
offoldoldold
dualwriteoldold, newold
shadowbothold, newold
livebothnew, oldnew
rampdownnewnew, oldnew
completenewnewnew

To manage your migration:

  1. Configure the migration. In your SDK configuration, define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.
  2. Call the read and write methods you defined, using the SDK’s migrator. The migrator determines the migration stage of the feature flag controlling the migration, and performs reads and writes to the old and new systems based on the migration stage.

For details of how to perform each step, read Server-side SDKs or Edge SDKs, below.

During the migration, you can check the consistency, errors, and latency as you manage your migration. This information is available from the flag’s Targeting tab. To learn more, read Migration flags.

Customize your migration

Customizing your migration is rare. If you have additional metrics that you want to track, or if your migration or modernization involves reading and writing from the new and old systems in a different configuration than the two, four, or six -stage migrations provided, you can also use the SDK to customize your migration.

Here’s how:

  1. Configure the migration. In your SDK configuration, define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.
  2. Use the migrationVariation method to evaluate your feature flag and determine the migration stage.
  3. Use your own logic to perform the appropriate migration operations for the stage. Record any metrics that you are interested in.
  4. When the migration operation is complete, call the trackMigration method to record your metrics.

For details of how to perform each step, read Server-side SDKs or Edge SDKs, below.

Server-side SDKs

This feature is available in the following server-side SDKs:

.NET (server-side)

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call Read or Write. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

.NET SDK v8.0 (C#)
1LDContext context = Context.Builder("context-key-123abc")
2    .Build();
3
4// this is the migration stage to use if the flag's migration stage
5// is not available from LaunchDarkly
6var defaultStage = MigrationStage.Off
7
8var readResult = migration.Read("migration-flag-key-123abc", context, defaultStage, payload);
9
10var writeResult = migration.Write("migration-flag-key-123abc", context, defaultStage, payload);

To learn more, read Read and Write.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the MigrationVariation method to evaluate your feature flag and determine its migration stage. This method returns the migration stage and a tracker that you can use to build the analytics event to send back to LaunchDarkly.

Here’s how:

.NET SDK v8.0 (C#)
1LDContext context = Context.Builder("context-key-123abc")
2    .Build();
3
4var (stage, tracker) = client.MigrationVariation("migration-flag-key-123abc", context, MigrationStage.Off);

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

.NET SDK v8.0 (C#)
1// define the combination of reads and writes from the new and old systems
2// that should occur at each migration stage
3
4switch (stage)
5    {
6        case MigrationStage.Off:
7        case MigrationStage.DualWrite:
8        case MigrationStage.Shadow:
9        case MigrationStage.Live:
10        case MigrationStage.RampDown:
11        case MigrationStage.Complete:
12        default:
13            // throw an error
14    }

Finally, when the migration operation is complete, call the TrackMigration method to record your metrics:

.NET SDK v8.0 (C#)
1client.TrackMigration(tracker);

To learn more, read IMigration, MigrationVariation, and TrackMigration.

Go

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call Read or Write. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

Go SDK v7.0
1context := ldcontext.New("context-key-123abc")
2
3// this is the migration stage to use if the flag's migration stage
4// is not available from LaunchDarkly
5defaultStage := ldmigration.Off
6
7readResult := migrator.Read("migration-flag-key-123abc", context, defaultStage, nil)
8
9writeResult := migrator.Write("migration-flag-key-123abc", context, defaultStage, nil)

To learn more, read Read and Write.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the MigrationVariation method to evaluate your feature flag and determine its migration stage. This method returns the migration stage, a tracker that you can use to build the analytics event to send back to LaunchDarkly, and an error.

Here’s how:

Go SDK v7
1context := ldcontext.New("context-key-123abc")
2stage, tracker, err := client.MigrationVariation("migration-flag-key-123abc", context, ldmigration.Off)

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

Go SDK v7
1// define the combination of reads and writes from the new and old systems
2// that should occur at each migration stage
3
4switch stage {
5  case ldmigration.Off:
6  case ldmigration.DualWrite:
7  case ldmigration.Shadow:
8  case ldmigration.Live:
9  case ldmigration.RampDown:
10  case ldmigration.Complete:
11  default: {
12    // throw an error
13  }
14}

Finally, when the migration operation is complete, call the TrackMigrationOp method to record your metrics:

Go SDK v7
1event, _ := tracker.Build();
2
3err := client.TrackMigrationOp(*event);

To learn more, read Migration and TrackMigrationOp.

Java

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call read or write. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

Java SDK v7.0
1LDContext context = LDContext.builder("context-key-123abc")
2  .build();
3
4// this is the migration stage to use if the flag's migration stage
5// is not available from LaunchDarkly
6MigrationStage defaultStage = MigrationStage.OFF
7
8Migration.MigrationResult<String> readResult = migration.read("migration-flag-key-123abc", context, defaultStage);
9
10Migration.MigrationWriteResult<String> writeResult = migration.write("migration-flag-key-123abc", context, defaultStage);

To learn more, read Migration.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the migrationVariation method to evaluate your feature flag and determine its migration stage. This method returns the migration stage, a tracker that you can use to build the analytics event to send back to LaunchDarkly, and an error.

Here’s how:

Java SDK v7.0
1LDContext context = LDContext.builder("context-key-123abc")
2  .build();
3
4MigrationVariation migrationVariation = client.migrationVariation("migration-flag-key-123abc", context, MigrationStage.OFF);

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

Java SDK v7.0
1// define the combination of reads and writes from the new and old systems
2// that should occur at each migration stage
3
4switch (migrationVariation.getStage()) {
5  case OFF:
6  case DUAL_WRITE:
7  case SHADOW:
8  case LIVE:
9  case RAMP_DOWN:
10  case COMPLETE:
11  default: {
12    // throw an error
13  }
14}

Finally, when the migration operation is complete, call the trackMigration method to record your metrics:

Java SDK v7.0
1MigrationOpTracker tracker = migrationVariation.getTracker();
2
3client.trackMigration(tracker);

To learn more, read migrationVariation and trackMigration.

Node.js (server-side)

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call the read or write methods from the LDMigration interface. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

Node.js (server-side) SDK v9
1const ld = require('@launchdarkly/node-server-sdk');
2
3const context: ld.LDContext = {
4   kind: 'user',
5   key: 'user-key-123abc',
6   name: 'Sandy',
7};
8
9// this is the migration stage to use if the flag's migration stage
10// is not available from LaunchDarkly
11let defaultStage: ld.LDMigrationStage = LDMigrationStage.Off;
12
13const migration = ld.createMigration(client, options);
14
15// when you need to perform a read in your application
16migration.read(
17  'migration-flag-key-123abc',
18  context,
19  defaultStage
20);
21
22// when you need to perform a write in your application
23migration.write(
24  'migration-flag-key-123abc',
25  context,
26  defaultStage
27);

To learn more, read LDMigration.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the migrationVariation method to evaluate your feature flag and determine its migration stage. This method returns a promise that is resolved with the result LDMigrationVariation. This result includes the migration stage and a tracker that you can use to build the analytics event to send back to LaunchDarkly.

Here’s how:

Node.js (server-side) SDK v9
1  const ld = require('@launchdarkly/node-server-sdk');
2
3  const context: ld.LDContext = {
4     kind: 'user',
5     key: 'user-key-123abc',
6     name: 'Sandy',
7  };
8
9  const { value, tracker } = await client.migrationVariation(
10    'migration-flag-key-123abc',
11    context,
12    false
13  );

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

Node.js (server-side) SDK v9
1// define the combination of reads and writes from the new and old systems
2// that should occur at each migration stage
3
4switch (value) {
5  case LDMigrationStage.Off: { },
6  case LDMigrationStage.DualWrite: { },
7  case LDMigrationStage.Shadow: { },
8  case LDMigrationStage.Live: { },
9  case LDMigrationStage.RampDown: { },
10  case LDMigrationStage.Complete: { },
11  default: {
12    // throw an error
13  }
14}

Finally, when the migration operation is complete, call the trackMigration method to record your metrics:

Node.js (server-side) SDK v9
1const event = tracker.createEvent();
2
3if (event) {
4  client.trackMigration(event);
5}

To learn more, read LDMigration. and LDMigrationOpEvent.

PHP

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call the read or write methods from the Migrator interface. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

PHP SDK v6
1$context = LaunchDarkly\LDContext::builder("context-key-123abc")->build();
2
3// this is the migration stage to use if the flag's migration stage
4// is not available from LaunchDarkly
5$defaultStage = Migrations\Stage::OFF;
6
7$result = $builder->build();
8if (!$result->isSuccessful()) {
9    throw new \Exception($result->error);
10}
11
12$migrator = $result->value;
13
14// if you need to pass additional information from the call site
15// to your read/write methods, use a mixed type payload
16$payload = ['index' => 'useful information'];
17
18// when you need to perform a read in your application
19$migrator->read('migration-flag-key-123abc', $context, $defaultStage, $payload);
20
21// when you need to perform a write in your application
22$migrator->write('migration-flag-key-123abc', $context, $defaultStage, $payload);

To learn more, read Migrator.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the migrationVariation method to evaluate your feature flag and determine its migration stage. This method returns the migration stage and a tracker that you can use to build the analytics event to send back to LaunchDarkly.

Here’s how:

PHP SDK v6
1$context = LaunchDarkly\LDContext::builder("context-key-123abc")->build();
2
3$result = $client->migrationVariation('migration-flag-key-123abc', $context, Migrations\Stage::OFF);
4
5/** @var Migrations\Stage */
6$stage = $result['stage'];
7/** @var Migrations\OpTracker */
8$tracker = $result['tracker'];

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

PHP SDK v6
1// define the combination of reads and writes from the new and old systems
2// that should occur at each migration stage
3
4switch ($stage) {
5  case Migrations\Stage::OFF:
6  case Migrations\Stage::DUALWRITE:
7  case Migrations\Stage::SHADOW:
8  case Migrations\Stage::LIVE:
9  case Migrations\Stage::RAMPDOWN:
10  case Migrations\Stage::COMPLETE:
11  default:
12    // throw an error
13}

Finally, when the migration operation is complete, call the trackMigrationOperation method to record your metrics:

PHP SDK v6
1$client->trackMigrationOperation($tracker);

To learn more, read Migrator and trackMigrationOperation.

Python

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call the read or write methods from the Migrator interface. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

Python SDK v9
1from ldclient import Stage
2
3context = Context.builder("context-key-123abc").build()
4
5
6# this is the migration stage to use if the flag's migration stage
7# is not available from LaunchDarkly
8default_stage = Stage.OFF
9
10migrator = builder.build()
11
12# when you need to perform a read in your application
13migrator.read(
14    'migration-flag-key-123abc',
15    context,
16    default_stage
17)
18
19# when you need to perform a write in your application
20migrator.write(
21    'migration-flag-key-123abc',
22    context,
23    default_stage
24)

To learn more, read ldclient.migrations.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the migration_variation method to evaluate your feature flag and determine its migration stage. This method returns the migration stage and a tracker that you can use to build the analytics event to send back to LaunchDarkly.

Here’s how:

Python SDK v9
1context = Context.builder("context-key-123abc").build()
2
3stage, tracker = ldclient.get().migration_variation('migration-flag-key-123abc', context, Stage.OFF)

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

Python SDK v9
1# define the combination of reads and writes from the new and old systems
2# that should occur at each migration stage
3
4if stage == Stage.OFF:
5elif stage == Stage.DUALWRITE:
6elif stage == Stage.SHADOW:
7elif stage == Stage.LIVE:
8elif stage == Stage.RAMPDOWN:
9elif stage == Stage.COMPLETE:
10else:
11  # throw an error

Finally, when the migration operation is complete, call the track_migration_op method to record your metrics:

Python SDK v9
1ldclient.get().track_migration_op(tracker)

To learn more, read ldclient.migrations and track_migration_op.

Ruby

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call read or write. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

Ruby SDK v8.0
1context = LaunchDarkly::LDContext.create({key: "user-key-123abc", kind:"user"})
2
3# this is the migration stage to use if the flag's migration stage
4# is not available from LaunchDarkly
5default_stage = LaunchDarkly::Migrations::STAGE_OFF
6
7read_result = migrator.read("migration-flag-key-123abc", context, default_stage, payload)
8
9write_result = migration.write("migration-flag-key-123abc", context, default_stage, payload)

To learn more, read read and write.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the migration_variation method to evaluate your feature flag and determine its migration stage. This method returns the migration stage and a tracker that you can use to build the analytics event to send back to LaunchDarkly.

Here’s how:

Ruby SDK v8.0
1context = LaunchDarkly::LDContext.create({key: "user-key-123abc", kind:"user"})
2
3stage, tracker = client.migration_variation(
4  "migration-flag-key-123abc",
5  context,
6  LaunchDarkly::Migrations::STAGE_OFF
7)

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

Ruby SDK v8.0
1# define the combination of reads and writes from the new and old systems
2# that should occur at each migration stage
3
4case stage
5when LaunchDarkly::Migrations::STAGE_OFF
6when LaunchDarkly::Migrations::STAGE_DUALWRITE
7when LaunchDarkly::Migrations::STAGE_SHADOW
8when LaunchDarkly::Migrations::STAGE_LIVE
9when LaunchDarkly::Migrations::STAGE_RAMPDOWN
10when LaunchDarkly::Migrations::STAGE_COMPLETE
11else
12  # throw an error
13end

Finally, when the migration operation is complete, call the track_migration_op method to record your metrics:

Ruby SDK v8.0
1client.track_migration_op(tracker);

To learn more, read Migrator and track_migration_op.

Rust

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call read or write. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

Rust SDK v2.2
1let context = ContextBuilder::new("user-key-123abc")
2    .kind("user")
3    .build()
4    .expect("Context failed to build");
5
6// this is the migration stage to use if the flag's migration stage
7// is not available from LaunchDarkly
8let default_stage = Stage::Off;
9
10let read_result = migrator
11    .read(
12        &context,
13        "migration-flag-key-123abc".into(),
14        default_stage,
15        "example-payload".into(),
16    )
17    .await;
18
19let write_result = migrator
20    .write(
21        &context,
22        "migration-flag-key-123abc".into(),
23        default_stage,
24        "example-payload".into(),
25    )
26    .await;

To learn more, read read and write.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the migration_variation method to evaluate your feature flag and determine its migration stage. This method returns the migration stage and a tracker that you can use to build the analytics event to send back to LaunchDarkly.

Here’s how:

Rust SDK v2.2
1let context = ContextBuilder::new("user-key-123abc")
2    .kind("user")
3    .build()
4    .expect("Context failed to build");
5
6let (stage, tracker) =
7    client.migration_variation(&context, "migration-flag-key-123abc", Stage::Off);

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

Rust SDK v2.2
1// define the combination of reads and writes from the new and old systems
2// that should occur at each migration stage
3
4match stage {
5    Stage::Off => todo!(),
6    Stage::DualWrite => todo!(),
7    Stage::Live => todo!(),
8    Stage::Shadow => todo!(),
9    Stage::Rampdown => todo!(),
10    Stage::Complete => todo!(),
11    _ => todo!(),
12};

Finally, when the migration operation is complete, call the track_migration_op method to record your metrics:

Rust SDK v2.2
1client.track_migration_op(tracker);

To learn more, read Migrator and track_migration_op.

Edge SDKs

This feature is available in the following edge SDKs:

Akamai

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call the read or write methods from the LDMigration interface. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

Akamai SDK v1.0.9+
1import {
2  createMigration,
3  LDContext,
4  LDMigrationStage,
5} from '@launchdarkly/akamai-server-edgekv-sdk';
6
7const context: LDContext = {
8   kind: 'user',
9   key: 'user-key-123abc',
10   name: 'Sandy',
11};
12
13// this is the migration stage to use if the flag's migration stage
14// is not available from LaunchDarkly
15let defaultStage: LDMigrationStage = LDMigrationStage.Off;
16
17const migration = createMigration(client, options);
18
19// when you need to perform a read in your application
20migration.read(
21  'migration-flag-key-123abc',
22  context,
23  defaultStage
24);
25
26// when you need to perform a write in your application
27migration.write(
28  'migration-flag-key-123abc',
29  context,
30  defaultStage
31);

To learn more, read LDMigration.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the migrationVariation method to evaluate your feature flag and determine its migration stage. This method returns a promise that is resolved with the result LDMigrationVariation. This result includes the migration stage. It also returns a tracker, which you can ignore. (The tracker is normally used to build an analytics event to send back to LaunchDarkly. However, the Akamai SDK does not support sending events, so there is no need to build one.)

Here’s how:

Akamai SDK v1.0.9+
1  import {
2    LDContext,
3  } from '@launchdarkly/akamai-server-edgekv-sdk';
4
5  const context: LDContext = {
6     kind: 'user',
7     key: 'user-key-123abc',
8     name: 'Sandy',
9  };
10
11  const { value, tracker } = await client.migrationVariation(
12    'migration-flag-key-123abc',
13    context,
14    false
15  );

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

Akamai SDK v1.0.9+
1import { LDMigrationStage } from '@launchdarkly/akamai-server-edgekv-sdk';
2
3// define the combination of reads and writes from the new and old systems
4// that should occur at each migration stage
5
6switch (value) {
7  case LDMigrationStage.Off: { },
8  case LDMigrationStage.DualWrite: { },
9  case LDMigrationStage.Shadow: { },
10  case LDMigrationStage.Live: { },
11  case LDMigrationStage.RampDown: { },
12  case LDMigrationStage.Complete: { },
13  default: {
14    // throw an error
15  }
16}

To learn more, read LDMigration.

Cloudflare

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call the read or write methods from the LDMigration interface. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

Cloudflare SDK v2.2.2+
1import {
2  createMigration,
3  LDContext,
4  LDMigrationStage,
5} from '@launchdarkly/cloudflare-server-sdk';
6
7const context: LDContext = {
8   kind: 'user',
9   key: 'user-key-123abc',
10   name: 'Sandy',
11};
12
13// this is the migration stage to use if the flag's migration stage
14// is not available from LaunchDarkly
15let defaultStage: LDMigrationStage = LDMigrationStage.Off;
16
17const migration = createMigration(client, options);
18
19// when you need to perform a read in your application
20migration.read(
21  'migration-flag-key-123abc',
22  context,
23  defaultStage
24);
25
26// when you need to perform a write in your application
27migration.write(
28  'migration-flag-key-123abc',
29  context,
30  defaultStage
31);

To learn more, read LDMigration.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the migrationVariation method to evaluate your feature flag and determine its migration stage. This method returns a promise that is resolved with the result LDMigrationVariation. This result includes the migration stage and a tracker that you can use to build the analytics event to send back to LaunchDarkly.

Here’s how:

Cloudflare SDK v2.2.2+
1  import {
2    LDContext,
3  } from '@launchdarkly/cloudflare-server-sdk'
4
5  const context: LDContext = {
6     kind: 'user',
7     key: 'user-key-123abc',
8     name: 'Sandy',
9  };
10
11  const { value, tracker } = await client.migrationVariation(
12    'migration-flag-key-123abc',
13    context,
14    false
15  );

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

Cloudflare SDK v2.2.2+
1import { LDMigrationStage } from '@launchdarkly/cloudflare-server-sdk';
2
3// define the combination of reads and writes from the new and old systems
4// that should occur at each migration stage
5
6switch (value) {
7  case LDMigrationStage.Off: { },
8  case LDMigrationStage.DualWrite: { },
9  case LDMigrationStage.Shadow: { },
10  case LDMigrationStage.Live: { },
11  case LDMigrationStage.RampDown: { },
12  case LDMigrationStage.Complete: { },
13  default: {
14    // throw an error
15  }
16}

Finally, when the migration operation is complete, call the trackMigration method to record your metrics:

Cloudflare SDK v2.2.2+
1import {
2  LDClient,
3  LDMigrationTracker,
4} from '@launchdarkly/cloudflare-server-sdk';
5
6const event = tracker.createEvent();
7
8if (event) {
9  client.trackMigration(event);
10}

To learn more, read LDMigration and LDMigrationOpEvent.

Vercel

To manage your migration, first you need to define how to read from and write to the old and new systems, how to check whether two reads are a match, and whether to track errors and latency metrics. To learn more, read Migration configuration.

Then, whenever you need to perform a read or write in the systems that you are modernizing or migrating, call the read or write methods from the LDMigration interface. The SDK evaluates the flag, determines which migration stage the flag is in, and performs the reads or writes in the appropriate system.

Here’s how:

Vercel SDK v1.1.6+
1import {
2  createMigration,
3  LDContext,
4  LDMigrationStage,
5} from '@launchdarkly/vercel-server-sdk';
6
7const context: LDContext = {
8   kind: 'user',
9   key: 'user-key-123abc',
10   name: 'Sandy',
11};
12
13// this is the migration stage to use if the flag's migration stage
14// is not available from LaunchDarkly
15let defaultStage: LDMigrationStage = LDMigrationStage.Off;
16
17const migration = createMigration(client, options);
18
19// when you need to perform a read in your application
20migration.read(
21  'migration-flag-key-123abc',
22  context,
23  defaultStage
24);
25
26// when you need to perform a write in your application
27migration.write(
28  'migration-flag-key-123abc',
29  context,
30  defaultStage
31);

To learn more, read LDMigration.

You can check for consistency, errors, or latency under “Migration insights” on the Targeting tab of your migration flag in the LaunchDarkly user interface. To learn more, read Migration flags.

Customizing your migration


Customizing your migration is rare. If you want to customize your migration, configure your migration information as before.

Then, use the migrationVariation method to evaluate your feature flag and determine its migration stage. This method returns a promise that is resolved with the result LDMigrationVariation. This result includes the migration stage and a tracker that you can use to build the analytics event to send back to LaunchDarkly.

Here’s how:

Vercel SDK v1.1.6+
1  import {
2    LDContext,
3  } from '@launchdarkly/vercel-server-sdk';
4
5  const context: LDContext = {
6     kind: 'user',
7     key: 'user-key-123abc',
8     name: 'Sandy',
9  };
10
11  const { value, tracker } = await client.migrationVariation(
12    'migration-flag-key-123abc',
13    context,
14    false
15  );

Next, perform the migration for the appropriate stage. At each stage, the migration may involve reading or writing from one or both systems. You must define the behavior for each stage. To learn more about how LaunchDarkly defines the stages, read Use SDKs to manage a migration, above.

The structure looks like this:

Vercel SDK v1.1.6+
1import { LDMigrationStage } from '@launchdarkly/vercel-server-sdk';
2
3// define the combination of reads and writes from the new and old systems
4// that should occur at each migration stage
5
6switch (value) {
7  case LDMigrationStage.Off: { },
8  case LDMigrationStage.DualWrite: { },
9  case LDMigrationStage.Shadow: { },
10  case LDMigrationStage.Live: { },
11  case LDMigrationStage.RampDown: { },
12  case LDMigrationStage.Complete: { },
13  default: {
14    // throw an error
15  }
16}

Finally, when the migration operation is complete, call the trackMigration method to record your metrics:

Vercel SDK v1.1.6+
1import {
2  LDMigrationTracker,
3  LDClient
4} from '@launchdarkly/vercel-server-sdk';
5
6const event = tracker.createEvent();
7
8if (event) {
9  client.trackMigration(event);
10}

To learn more, read LDMigration and LDMigrationOpEvent.

Built with