# Migrating from Legacy Go SDK to Go Core

This guide covers migrating from the legacy Go Server SDK to the Go Core SDK. The Go Core SDK offers significant performance improvements and new features, 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 are only available in Go Core.
* **Maintenance**: The legacy Go SDK is in maintenance mode and only receives critical bug fixes.

## Installation differences

### Legacy Go SDK

{% codetabs %}
```bash CLI
go get github.com/statsig-io/go-sdk
```

```go go.mod
require (
  github.com/statsig-io/go-sdk v1.26.0
)
```
{% /codetabs %}

### Go Core SDK

Go Core requires the new package and additional setup. Install the latest version of the SDK:

{% codetabs %}
```bash Latest Version
go get github.com/statsig-io/statsig-server-core/statsig-go@latest
```

```bash Specific Version
go get github.com/statsig-io/statsig-server-core/statsig-go@v0.7.2
```

```go go.mod
require (
  github.com/statsig-io/statsig-server-core/statsig-go v0.7.2
)
```
{% /codetabs %}

Go to the [Releases tab in GitHub](https://github.com/statsig-io/statsig-server-core/releases) for the latest versions.

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

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

Follow the prompts to set the environment variables using the `statsig.env` or `statsig.env.ps1` file generated during the post-install script.

{% codetabs %}
```bash macOS
source /Users/Your-User-Name/.statsig_env
```

```powershell Windows (PowerShell)
. "C:\Users\Your-User-Name\.statsig_env.ps1"
```
{% /codetabs %}

Add the variables to your `.bashrc`, `.zshrc`, or `.ps1` file to load them automatically.

{% callout type="note" %}
You may need to install gcc on your system to run the SDK on Windows. Refer to [FAQ](https://docs.statsig.com/server-core/go-core#faq) for more information.
{% /callout %}

Refer to [FAQ](https://docs.statsig.com/server-core/go-core#faq) if you encounter any issues with installation.

## API differences

### Key package and import changes

| Feature | Legacy Go SDK | Go Core SDK |
|---------|---------------|-------------|
| Import | `github.com/statsig-io/go-sdk` | `github.com/statsig-io/statsig-server-core/statsig-go/src` |
| Main Package | `statsig` | `statsig` |
| Initialization | Static `statsig.Initialize()` | Instance-based `statsig.Initialize()` |
| Options | `&Options{}` | `statsig.NewStatsigOptionsBuilder().With*().Build()` |
| User Creation | `statsig.User{}` | `statsig.NewStatsigUserBuilder().With*().Build()` |

### Initialization

{% codetabs %}
```go Legacy Go SDK
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"}})
```

```go Go Core SDK
import (
    statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)

// Create options (all optional)
options := statsig.NewStatsigOptionsBuilder().
    WithOutputLogLevel("DEBUG").
    WithSpecsSyncIntervalMs(10000).
    WithEventLoggingFlushIntervalMs(10000).
    Build()

// Create and initialize the SDK
s, err := statsig.NewStatsig("server-secret-key", options)
if err != nil {
    // Handle error
}

// Initialize the SDK
s.Initialize()

// Or if you want to initialize with details
details, err := s.InitializeWithDetails()
if err != nil {
    // Handle error
}
```
{% /codetabs %}

### Checking gates

{% codetabs %}
```go Legacy Go SDK
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")
```

```go Go Core SDK
import (
    statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)

s, err := statsig.NewStatsig("server-secret-key", statsig.StatsigOptions{})

user := statsig.NewStatsigUserBuilder().
    WithUserID("123").
    WithEmail("test@example.com").
    Build()

// Check if a gate is enabled
enabled := s.CheckGate(user, "my_gate")
```
{% /codetabs %}

### Getting dynamic configs

{% codetabs %}
```go Legacy Go SDK
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")
```

```go Go Core SDK
import (
    statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)

s, err := statsig.NewStatsig("server-secret-key", statsig.StatsigOptions{})

user := statsig.NewStatsigUserBuilder().
    WithUserID("123").
    WithEmail("test@example.com").
    Build()

// Get a dynamic config
config := s.GetDynamicConfig(user, "my_config")
```
{% /codetabs %}

### Getting experiments

{% codetabs %}
```go Legacy Go SDK
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")
```

```go Go Core SDK
import (
    statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)

s, err := statsig.NewStatsig("server-secret-key", statsig.StatsigOptions{})

user := statsig.NewStatsigUserBuilder().
    WithUserID("123").
    WithEmail("test@example.com").
    Build()

// Get an experiment
experiment := s.GetExperiment(user, "my_experiment")
```
{% /codetabs %}

### Logging events

{% codetabs %}
```go Legacy Go SDK
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"},
	})
```

```go Go Core SDK
import (
    statsig "github.com/statsig-io/statsig-server-core/statsig-go/src"
)

s, err := statsig.NewStatsig("server-secret-key", statsig.StatsigOptions{})

user := statsig.NewStatsigUserBuilder().
    WithUserID("123").
    WithEmail("test@example.com").
    Build()

event := map[string]interface{}{
		"name":  "sample event",
		"value": "event",
		"metadata": map[string]string{
			"val_1": "log val 1",
		},
	}

// Log an event
s.LogEvent(*user, event)
```
{% /codetabs %}

## 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 download 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, reach out [in Slack](https://statsig.com/slack) or go to the [GitHub repository](https://github.com/statsig-io/statsig-server-core) for the latest updates and examples.