Node.js (server-side) SDK 8.x to 9.0 migration guide

Overview

This topic explains the changes in the Node.js (server-side) SDK 9.0 release and how to migrate to that version.

Version 9.0 includes breaking changes. It removes the deprecated LDUser. To learn more, read Understanding what was removed. Additionally, if you use the Relay Proxy, you must update your Relay Proxy to version 8.0 before you update your SDK to version 9.0. To learn more, read the Relay Proxy 8.0 release notes.

Version 9.0 also introduces the ability to manage migrations or modernizations. You might use this functionality if you are optimizing queries, upgrading to new tech stacks, migrating from one database to another, or other similar technology changes.

You will need this functionality to use migration flags. A migration flag is a temporary flag used to migrate data or systems while keeping your application available and disruption free. To learn more, read Migration flags.

Finally, version 9.0 includes type safe variation methods for use with TypeScript.

Before you migrate to version 9.0, we recommend updating to the latest 8.x version. If you update to the latest 8.x version, deprecation warnings appear in areas of your code that need to be changed for 9.0, for example, any use of LDUser. You can update these areas at your own pace while still using 8.x, rather than migrating everything simultaneously. To learn more about updating to the latest 8.x version, visit the SDK's GitHub repository.

Understanding how 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 system, the new system, or both. You will also be writing data to the old system, the new system, 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.

To manage your migration:

• Configure the migration
• Call the read and write methods you defined

Configuring the migration

There are two categories of migration options that you can configure for each LaunchDarkly SDK:

• Options for reading and writing data: You can define how to read from and write to both the old system and the new system. You can also define a method to check whether the two reads are a match, and whether the migration should execute serially or concurrently. To learn how these options apply to each migration stage, read Using SDKs to manage a migration.
• Options for tracking metrics: You can configure whether the SDK should track latency and errors, so that you can monitor the performance of your application during the migration.

Each of the readOld, readNew, writeOld, and writeNew functions accept an optional argument, which is typically used to define what to read or write. They should return LDMigrationSuccess or LDMigrationError, or can throw an exception. The code sample below uses a mix to illustrate these possibilities.

Here's how to configure each of these options:

import * as ld from '@launchdarkly/node-server-sdk';
const options: ld.LDMigrationOptions = {
  readNew: async(key?: string) => {
    console.log("Reading from new: ", key);
    return LDMigrationSuccess(true);
  },
  readOld: async(key?: string) => {
    console.log("Reading from new: ", key);
    return LDMigrationSuccess(true);
  },
  writeNew: async(params?: {key: string, value: string}) => {
    console.log("Writing to new: ", params);
    // if failure
    throw new Exception("example exception")
  },
  writeOld: async(params?: {key: string, value: string}) => {
    console.log("Writing to old: ", params);
    // if failure
    return LDMigrationError(new Error('example error'));
  },
  check: (old, new) => {
    // Define your consistency check for read operations
    // and return a boolean. Depending on your migration,
    // this may be as simple as 'return a === b;'
  },
  execution: new LDConcurrentExecution(),
    // or new LDSerialExecution(LDExecutionOrdering.Random),
    // or new LDSerialExecution(LDExecutionOrdering.Fixed),
  latencyTracking: true, // defaults to true
  errorTracking: true, // defaults to true
}
const client = ld.init('sdk-key-123abc');
const migration = ld.createMigration(client, options);
COPY

To learn more, read Migration configuration.

Reading and writing during the migration

As your migration proceeds, use the SDK's migrator to call the read and write methods you defined. 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.

Here's how:

const ld = require('@launchdarkly/node-server-sdk');
const context: ld.LDContext = {
   kind: 'user',
   key: 'user-key-123abc',
   name: 'Sandy',
};
// this is the migration stage to use if the flag's migration stage
// is not available from LaunchDarkly
let defaultStage: ld.LDMigrationStage = LDMigrationStage.Off;
const migration = ld.createMigration(client, options);
// when you need to perform a read in your application
migration.read(
  'migration-flag-key-123abc',
  context,
  defaultStage
);
// when you need to perform a write in your application
migration.write(
  'migration-flag-key-123abc',
  context,
  defaultStage
);
COPY

To learn more, read Migrations.

During the migration, you can check the consistency, errors, and latency as you manage your migration. This information is available in the "Migration insights" section of the flag's Targeting tab. To learn more, read Migration flags.

Understanding changes to variation methods

Version 9.0 now includes type safe variation methods for use with TypeScript.

Understanding what was removed

Version 9.0 removes the deprecated LDUser. Version 7 of the Node.js (server-side) SDK replaced users with contexts. Starting in version 9, the deprecated LDUser is removed.

Here's how to construct a basic context, as compared with constructing a user:

const user = {
  key: 'user-key-123abc'
};
COPY

And here's how to evaluate a flag using a context:

client.variation('flag-key-123abc', context, false,
  (err, value) => {
    // check value and proceed accordingly
  });
COPY

To learn more about replacing users with contexts, read the Node.js (server-side) SDK 6.x to 7.0 migration guide and Best practices for upgrading users to contexts.