Skip to main content

Migrating from Legacy Go SDK to Go Core

This guide will help you migrate from the legacy Go Server SDK to the new Go Core SDK. The Go Core SDK offers significant performance improvements and new features, as it's built on a shared Rust core library.

Why Migrate?​

  • Performance: Go Core achieves faster evaluation times and lower CPU consumption, making it more efficient than the legacy SDK.
  • New Features: Access to Parameter Stores
  • Future Support: All new features and improvements will only be available in Go Core
  • Maintenance: The legacy Go SDK is in maintenance mode and will only receive critical bug fixes

Installation Differences​

Legacy Go SDK​

go get github.com/statsig-io/go-sdk

Or, add a dependency in go.mod:

require (
  github.com/statsig-io/go-sdk v1.26.0
)

Go Core SDK​

Go Core requires the new package and additional setup:

You can install the latest version of the SDK:

go get github.com/statsig-io/statsig-server-core/statsig-go@latest

or a specific version of the SDK:

go get github.com/statsig-io/statsig-server-core/statsig-go@v0.7.2

Or, add a dependency on the most recent version of the SDK in go.mod:

require (
  github.com/statsig-io/statsig-server-core/statsig-go v0.7.2
)

See the Releases tab in GitHub for the latest versions.

Run the following commands to install the necessary binaries and set environment variables:

go install github.com/statsig-io/statsig-server-core/statsig-go/cmd/post-install@latest
post-install

The system should prompt you to set the environment variables using a statsig.env or statsig.env.ps1 file that was generated during the post-install script. Follow the instructions to set the environment variables.

// E.g. - the command will look something like this:

macOS: 
source /Users/Your-User-Name/.statsig_env

Windows (PowerShell): 
. "C:\Users\Your-User-Name\.statsig_env.ps1"

Users can also add in the variables to their .bashrc, .zshrc, or .ps1 file to load them automatically.

note

You may need to have gcc installed on your system in order to run the SDK on Windows. See FAQ for more information.

See FAQ if you run into any issues with installation.

API Differences​

Key Package and Import Changes​

FeatureLegacy Go SDKGo Core SDK
Importgithub.com/statsig-io/go-sdkgithub.com/statsig-io/statsig-server-core/statsig-go/src
Main Packagestatsigstatsig
InitializationStatic statsig.Initialize()Instance-based statsig.Initialize()
Options&Options{}statsig.NewStatsigOptionsBuilder().With*().Build()
User Creationstatsig.User{}statsig.NewStatsigUserBuilder().With*().Build()

Initialization​

import (
  statsig "github.com/statsig-io/go-sdk"
)

statsig.Initialize("server-secret-key")

// Or, if you want to initialize with certain options
statsig.InitializeWithOptions("server-secret-key", &Options{Environment: Environment{Tier: "staging"}})

Checking Gates​

import (
  statsig "github.com/statsig-io/go-sdk"
)

user := statsig.User{
  UserID: "123",
  Email: "test@example.com",
}

// Check if a gate is enabled
enabled := statsig.CheckGate(user, "my_gate")

Getting Dynamic Configs​

import (
  statsig "github.com/statsig-io/go-sdk"
)

user := statsig.User{
  UserID: "123",
  Email: "test@example.com",
}

// Get a dynamic config
config := statsig.GetConfig(user, "my_config")
value := config.Get("key", "default_value")

Getting Experiments​

import (
  statsig "github.com/statsig-io/go-sdk"
)

user := statsig.User{
  UserID: "123",
  Email: "test@example.com",
}

// Get an experiment
experiment := statsig.GetExperiment(user, "my_experiment")

Logging Events​

import (
  statsig "github.com/statsig-io/go-sdk"
)

user := statsig.User{
  UserID: "123",
  Email: "test@example.com",
}

// Log an event
statsig.LogEvent(Event{
		User: user,
		EventName: "add_to_cart",
                Value: "SKU_12345",
		Metadata: map[string]string{"price": "9.99","item_name": "diet_coke_48_pack"},
	})

Key Migration Steps​

  1. Update Dependencies: Change from github.com/statsig-io/go-sdk to github.com/statsig-io/statsig-server-core/statsig-go/src

  2. Run Post-Install: Execute the post-install script to set up environment variables and pull down the latest version of the Rust core library.

  3. Update Initialization:

    • Use the builder pattern to create user and options
    • Replace statsig.User with statsig.NewStatsigUserBuilder().With*().Build()
    • Initialize with statsig.NewStatsig() and call Initialize()

  4. Test Thoroughly:

    • Verify all feature gates, experiments, and configs work as expected
    • Check that event logging is functioning correctly

New Features Available in Go Core​

  • Parameter Stores: Access to dynamic parameter management
  • Improved Performance: 5-10x faster evaluation times
  • Better Error Handling: More robust error management

Need Help?​

If you encounter any issues during migration, please reach out to us in Slack or check our GitHub repository for the latest updates and examples.