> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade to data plane v2.x

> Upgrade your self-hosted Braintrust deployment to the data plane v2 series

Data plane v2.0 introduced many new features, including [trace-level scorers](/changelog#trace-level-scorers), [sandboxes for agent evals](/changelog#sandboxes-for-agent-evals), and [log indexing and full-text search](/changelog#log-indexing-and-full-text-search).

The current recommended target for the v2.x cutover is data plane v2.1.1. The module and chart versions below deploy v2.1.1 images unless noted otherwise.

This guide assumes a standard Braintrust deployment using the Braintrust Terraform modules or Helm chart to manage storage, identity, networking, and generated configuration. If your deployment customizes those layers, confirm the equivalent resources, permissions, network paths, and runtime environment are in place before applying the version upgrade. Braintrust components must be able to list, read, write, and delete the generated object-storage paths, including versioned deletes where object versioning is enabled.

<Note>
  Avoid bundling unrelated configuration or workload changes into the upgrade window. Validate the version upgrade first, then separately ramp new automations, scoring traffic, credential rotations, or storage and network policy changes.
</Note>

<Tabs>
  <Tab title="AWS - Lambda" icon="https://img.logo.dev/aws.amazon.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    This guide shows the process for upgrading the Braintrust data plane to v2.x in your AWS account.

    ## 1. Prepare for v2.x

    Before upgrading to data plane v2.x, you need to reach Terraform module v4.5.0 (data plane v1.1.32) and enable the efficient WAL format. v1.1.32 is the required foundation for v2.x. It ensures all Brainstore configuration is in place and verified before the upgrade.

    ### Upgrade Terraform module

    The goal of this step is to reach v4.5.0. Check your current module version in `main.tf`:

    ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    module "braintrust-data-plane" {
      source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v..." # your current version
    }
    ```

    Then follow the path for your starting point:

    | Starting version                    | Sub-steps to follow                                                     |
    | ----------------------------------- | ----------------------------------------------------------------------- |
    | TF module \< v3.0.0                 | 1 → 2 → 3                                                               |
    | TF module v3.x                      | 2 → 3                                                                   |
    | TF module v4.x (not v4.5.0)         | 3 only                                                                  |
    | TF module v4.5.0                    | Skip to [Enable efficient WAL format](#enable-efficient-wal-format-aws) |
    | TF module v5.0.0, v5.1.0, or v5.2.0 | Skip to [Upgrade to v2.x](#upgrade-to-v2-x-aws)                         |
    | TF module v5.2.1+                   | Skip to [Enable no-PostgreSQL mode](#enable-no-postgresql-mode-aws)     |

    <Steps>
      <Step title="Upgrade to Terraform module v3.1.3">
        This upgrades the data plane from v1.1.25 to v1.1.27. There are no breaking changes.

        ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        module "braintrust-data-plane" {
          source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v3.1.3"

          # ... other configuration
        }
        ```

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        terraform apply
        ```
      </Step>

      <Step title="Upgrade to Terraform module v4.0.0">
        This step upgrades the AWS provider from v5 to v6. **The Terraform state file changes made in this step are irreversible.** Apply at this version explicitly before proceeding, so that if anything goes wrong, it is clear whether the provider upgrade or the subsequent data plane bump caused it.

        ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        module "braintrust-data-plane" {
          source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v4.0.0"

          # ... other configuration
        }
        ```

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        terraform apply
        ```

        The data plane version does not change in this step.

        <Tip>
          For straightforward deployments, you can upgrade directly from v3.1.3 to v4.5.0, skipping the v4.0.0 stop. The intermediate stop is recommended for complex deployments to isolate the AWS provider migration. If something goes wrong in a single jump, it's harder to identify the cause.
        </Tip>
      </Step>

      <Step title="Upgrade to Terraform module v4.5.0">
        This upgrades the data plane to v1.1.32. v4.5.0 also introduces the `skip_pg_for_brainstore_objects` variable used in the Topics enablement step.

        ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        module "braintrust-data-plane" {
          source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v4.5.0"

          # ... other configuration
        }
        ```

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        terraform apply
        ```
      </Step>
    </Steps>

    <h3 id="enable-efficient-wal-format-aws">
      Enable efficient WAL format
    </h3>

    <Warning>
      This must be a separate `terraform apply` from the v4.5.0 upgrade. If you set `brainstore_wal_footer_version` in the same apply, Brainstore nodes that are still rolling out won't be able to read the new WAL format. Wait until all nodes are confirmed running v1.1.32 before applying this step.
    </Warning>

    Add `brainstore_wal_footer_version = "v1"` to your module and apply:

    ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    module "braintrust-data-plane" {
      source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v4.5.0"

      brainstore_wal_footer_version = "v1"

      # ... other configuration
    }
    ```

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    terraform apply
    ```

    After applying, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) and check the WAL footer version (`BRAINSTORE_WAL_FOOTER_VERSION`) row. On v1.1.32, it will show "Unable to verify setting. Please upgrade to configure." The setting is active; Brainstore v1.1.32 does not report it back to the control plane. It will show correctly after upgrading to v2.x.

    <Note>
      This step is strongly recommended but not mechanically enforced. Deployments running mixed WAL formats become increasingly difficult to tune at scale.
    </Note>

    ### Run the preflight check

    Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url). Verify the following expected statuses before proceeding:

    | Setting                                              | Expected status                                 |
    | ---------------------------------------------------- | ----------------------------------------------- |
    | License                                              | Configured                                      |
    | Telemetry                                            | Configured                                      |
    | Data plane service token                             | Configured                                      |
    | Brainstore default mode (`BRAINSTORE_DEFAULT`)       | Configured                                      |
    | Insert logs (`INSERT_LOGS2`)                         | Configured                                      |
    | Insert row references (`BRAINSTORE_INSERT_ROW_REFS`) | Configured                                      |
    | Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)      | Configured                                      |
    | Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)        | Configured                                      |
    | Proxy URL (`BRAINSTORE_AI_PROXY_URL`)                | Configured                                      |
    | Redis (`BRAINSTORE_REDIS_URI`)                       | Configured                                      |
    | Brainstore direct writes                             | "Upgrade to configure Brainstore direct writes" |

    <Note>
      On v1.1.32, items like WAL footer version, response cache URI, and code bundle URI are not displayed. They appear only after upgrading to v2.x. The HTTP/2 check may show a warning on v1.1.32. This resolves after upgrading.
    </Note>

    If any of the first ten rows are not green, resolve them before proceeding. Contact [Braintrust support](mailto:support@braintrust.dev) if you need help.

    <h2 id="upgrade-to-v2-x-aws">
      2\. Upgrade to v2.x
    </h2>

    With preflight complete, upgrade to Terraform module v5.2.1, which ships the recommended data plane v2.1.1 images. The WAL footer also bumps to v3 in the same apply.

    <Note>
      If you are already on Terraform module v5.2.1 with WAL footer version set to v3, skip to [Enable no-PostgreSQL mode](#enable-no-postgresql-mode-aws).
    </Note>

    ### Apply the upgrade

    Update your module to v5.2.1 and bump the WAL footer to v3. You can do both in the same apply. As long as WAL footer is already on v1 from the previous step, all v2.x nodes will understand the v3 format on startup.

    Because the latest module defaults no-PostgreSQL mode on, explicitly disable it for the base upgrade. Enable it only in the next step.

    ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    module "braintrust-data-plane" {
      source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v5.2.1"

      brainstore_wal_footer_version = "v3"
      skip_pg_for_brainstore_objects = ""

      # ... other configuration
    }
    ```

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    terraform apply
    ```

    ### Verify settings

    Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) and verify the following are all green:

    | Setting                                              | Expected status                      |
    | ---------------------------------------------------- | ------------------------------------ |
    | License                                              | Configured                           |
    | Telemetry                                            | Configured                           |
    | Data plane service token                             | Configured                           |
    | Brainstore default mode (`BRAINSTORE_DEFAULT`)       | Configured                           |
    | Insert logs (`INSERT_LOGS2`)                         | Configured                           |
    | Insert row references (`BRAINSTORE_INSERT_ROW_REFS`) | Configured                           |
    | Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)      | Configured                           |
    | Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)        | Configured                           |
    | Proxy URL (`BRAINSTORE_AI_PROXY_URL`)                | Configured                           |
    | Redis (`BRAINSTORE_REDIS_URI`)                       | Configured                           |
    | Response cache URI (`BRAINSTORE_RESPONSE_CACHE_URI`) | Configured                           |
    | Code bundle URI (`BRAINSTORE_CODE_BUNDLE_URI`)       | Configured                           |
    | HTTP/2                                               | Data plane is using HTTP/2 or higher |

    **Brainstore direct writes** will show "Upgrade to configure Brainstore direct writes." This is enabled in the next step.

    ### Validate the base upgrade

    Before enabling no-PostgreSQL mode, validate the workloads your team relies on. For example, trace one production-shaped request, run an eval suite you use regularly, and invoke or iterate on a prompt. If you use online scorers or automations, trigger one through its normal online path. For trace-level scorers, choose one that uses full trace context. If these workflows round-trip cleanly through the data plane and look right in the UI, continue to no-PostgreSQL mode.

    <h3 id="enable-no-postgresql-mode-aws">
      Enable no-PostgreSQL mode
    </h3>

    No-PostgreSQL mode removes PostgreSQL from the Brainstore write path, delivering higher ingestion throughput. This step is a prerequisite for [Topics](/observe/topics) but does not enable them.

    <Warning>
      The switch to no-PostgreSQL mode is one-way: Once Brainstore is writing data directly, rolling back requires downtime to drain and re-ingest. Enable it only when you are ready to commit.
    </Warning>

    Keep your module on v5.2.1 and set `skip_pg_for_brainstore_objects = "all"`:

    ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    module "braintrust-data-plane" {
      source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v5.2.1"

      brainstore_wal_footer_version = "v3"
      skip_pg_for_brainstore_objects = "all"

      # ... other configuration
    }
    ```

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    terraform apply
    ```

    Repeat the same workload validation after enabling no-PostgreSQL mode. If the same representative workflows round-trip cleanly through the data plane and look right in the UI, proceed to the next environment.

    ### Enable Topics

    Topics for self-hosted deployments is available as early access with limited eligibility. Completing the full v2.x upgrade and no-PostgreSQL mode migration is a prerequisite, but additional conditions must all be met before Topics can be enabled:

    * **Standard deployment required.** Topics is supported on standard Terraform/Helm deployments only. Custom Kubernetes clusters using the Helm chart on non-standard infrastructure are not supported.
    * **Braintrust-hosted inference required.** Topics runs LLM calls on models hosted by Braintrust with Zero Data Retention (ZDR). Bring-your-own-model is not supported. Currently US-only.
    * **Built-in models must be enabled.** Self-hosted organizations have [built-in models](/admin/ai-providers#manage-built-in-models) disabled by default, so no trace data leaves your network boundary unless you opt in. Because Topics depends on built-in models, an admin must explicitly enable them before Topics can run.
    * **Pricing is not included by default.** Topics usage is not covered by standard contracts. Discuss pricing with your account team before proceeding.
    * **Ongoing maintenance required.** Self-hosted Topics deployments run on a frequent-release build track separate from the tagged data plane versions and will require regular upgrades to receive the latest fixes and improvements.

    If you meet all of these requirements and want to proceed, contact your account team or [Braintrust support](mailto:support@braintrust.dev). Until Braintrust enables Topics access for your organization, the Topics page and Topics automations remain blocked, even after the upgrade and no-PostgreSQL migration are complete.

    ## Configuration reference

    <Accordion title="Core configuration (auto-set by v4.4.0)">
      | Variable                         | Source                                                   | Since  |
      | -------------------------------- | -------------------------------------------------------- | ------ |
      | `SERVICE_TOKEN_SECRET_KEY`       | Auto-generated 32-character key in Secrets Manager       | v3.0.0 |
      | `BRAINSTORE_REDIS_URI`           | ElastiCache endpoint and port                            | v3.1.0 |
      | `BRAINSTORE_DEFAULT`             | Hardcoded `"force"`                                      | v3.0.0 |
      | `INSERT_LOGS2`                   | Hardcoded `"true"`                                       | v3.0.0 |
      | `BRAINSTORE_INSERT_ROW_REFS`     | Hardcoded `"true"`                                       | v3.0.0 |
      | `BRAINSTORE_REALTIME_WAL_BUCKET` | Auto-created S3 bucket                                   | v3.0.0 |
      | `BRAINSTORE_AI_PROXY_URL`        | Fetched from SSM at boot                                 | v4.0.3 |
      | `BRAINSTORE_XACT_MANAGER_URI`    | Same ElastiCache endpoint as Redis                       | v4.4.0 |
      | `BRAINSTORE_RESPONSE_CACHE_URI`  | Module-created S3 bucket (at `/brainstore-cache` prefix) | v4.4.0 |
      | `BRAINSTORE_CODE_BUNDLE_URI`     | Module-created S3 bucket                                 | v4.4.0 |
    </Accordion>

    <Accordion title="WAL footer version (requires explicit configuration)">
      | Variable                        | How to set                                           | Since  |
      | ------------------------------- | ---------------------------------------------------- | ------ |
      | `BRAINSTORE_WAL_FOOTER_VERSION` | Set `brainstore_wal_footer_version = "v1"` in module | v4.5.0 |

      Allowed values: `""` (disabled, default), `"v1"`, `"v2"`, `"v3"`. Set to `"v1"` as part of the pre-upgrade steps. Only set to `"v3"` after successfully deploying v2.x.
    </Accordion>

    <Accordion title="No-PostgreSQL mode (opt-in, post-upgrade)">
      | Variable                              | How to set                                                                                          | Since  |
      | ------------------------------------- | --------------------------------------------------------------------------------------------------- | ------ |
      | `SKIP_PG_FOR_BRAINSTORE_OBJECTS`      | Set `skip_pg_for_brainstore_objects` in module                                                      | v4.5.0 |
      | `BRAINSTORE_ASYNC_SCORING_OBJECTS`    | Auto-derived from `skip_pg_for_brainstore_objects`                                                  | v4.5.0 |
      | `BRAINSTORE_LOG_AUTOMATIONS_OBJECTS`  | Auto-derived from `skip_pg_for_brainstore_objects`                                                  | v4.5.0 |
      | `BRAINSTORE_WAL_USE_EFFICIENT_FORMAT` | Auto-enabled when either `brainstore_wal_footer_version` or `skip_pg_for_brainstore_objects` is set | v4.5.0 |

      Setting `skip_pg_for_brainstore_objects = "all"` is a prerequisite for enabling Topics. The module automatically fans this value out to `BRAINSTORE_ASYNC_SCORING_OBJECTS` and `BRAINSTORE_LOG_AUTOMATIONS_OBJECTS`.
    </Accordion>
  </Tab>

  <Tab title="GCP" icon="https://img.logo.dev/cloud.google.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    This guide shows the process for upgrading the Braintrust data plane to v2.x in your GCP account.

    ## 1. Prepare for v2.x

    Before upgrading to data plane v2.x, you need to reach Helm chart v5.0.1 (data plane v1.1.32) and enable the efficient WAL format. v1.1.32 is the required foundation for v2.x. It ensures all Brainstore configuration is in place and verified before the upgrade.

    ### Upgrade Helm chart

    Check your current Helm chart version:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    helm list -n braintrust
    ```

    Then follow the path for your starting point:

    | Starting version                     | Sub-steps to follow                                                     |
    | ------------------------------------ | ----------------------------------------------------------------------- |
    | Helm chart \< v3.1.1                 | 1 → 2 → 3                                                               |
    | Helm chart v3.x                      | 2 → 3                                                                   |
    | Helm chart v4.x                      | 3 only                                                                  |
    | Helm chart v5.0.1                    | Skip to [Enable efficient WAL format](#enable-efficient-wal-format-gcp) |
    | Helm chart v6.0.0, v6.1.0, or v6.2.0 | Skip to [Upgrade to v2.x](#upgrade-to-v2-x-gcp)                         |
    | Helm chart v6.2.1+                   | Skip to [Enable no-PostgreSQL mode](#enable-no-postgresql-mode-gcp)     |

    <Steps>
      <Step title="Upgrade to Helm chart v3.1.1">
        This upgrades the data plane from v1.1.27 to v1.1.31. There are no breaking changes.

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        helm upgrade braintrust \
          oci://public.ecr.aws/braintrust/helm/braintrust \
          --namespace braintrust \
          --version 3.1.1 \
          --values helm-values.yaml
        ```

        After applying, restart pods:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        kubectl rollout restart deployment -n braintrust
        ```
      </Step>

      <Step title="Upgrade to Helm chart v4.0.0">
        This step upgrades the data plane to v1.1.32 and introduces bidirectional communication between Brainstore and API pods. Brainstore now needs to reach the API pods. The chart auto-sets `BRAINSTORE_AI_PROXY_URL` to `http://braintrust-api:8000`.

        <Warning>
          If your cluster has network policies or security rules restricting traffic between pods, allow Brainstore pods to reach the API service on port 8000 before upgrading.
        </Warning>

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        helm upgrade braintrust \
          oci://public.ecr.aws/braintrust/helm/braintrust \
          --namespace braintrust \
          --version 4.0.0 \
          --values helm-values.yaml
        ```

        After applying, restart pods:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        kubectl rollout restart deployment -n braintrust
        ```
      </Step>

      <Step title="Upgrade to Helm chart v5.0.1">
        This step enables fast readers, isolated Brainstore nodes that handle common UI queries. Fast readers are enabled by default with 2 replicas and use the same node spec as standard readers, **increasing your cluster node count by 2**. You can upgrade directly to v5.0.1 from any v4.x version.

        <Warning>
          Before upgrading, account for 2 additional fast reader nodes in your cluster capacity. If you have customized `brainstore.reader` settings in `values.yaml`, mirror those customizations to the new `brainstore.fastreader` block. See [Configure Brainstore fast readers](/admin/self-hosting/advanced#configure-brainstore-fast-readers) for details.
        </Warning>

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        helm upgrade braintrust \
          oci://public.ecr.aws/braintrust/helm/braintrust \
          --namespace braintrust \
          --version 5.0.1 \
          --values helm-values.yaml
        ```

        After applying, restart pods:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        kubectl rollout restart deployment -n braintrust
        ```
      </Step>
    </Steps>

    <h3 id="enable-efficient-wal-format-gcp">
      Enable efficient WAL format
    </h3>

    <Warning>
      This must be a separate `helm upgrade` after confirming all pods are running v1.1.32. Setting this during the same upgrade as the version bump risks Brainstore nodes still rolling out being unable to read the new WAL format.
    </Warning>

    Set `brainstoreWalFooterVersion` in your `helm-values.yaml`:

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    brainstoreWalFooterVersion: "v1"
    ```

    Then apply:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    helm upgrade braintrust \
      oci://public.ecr.aws/braintrust/helm/braintrust \
      --namespace braintrust \
      --version 5.1.0 \
      --values helm-values.yaml
    ```

    On chart v5.1.0+, pods will automatically restart after applying the upgrade.

    Once the pods have cycled, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) and check the WAL footer version (`BRAINSTORE_WAL_FOOTER_VERSION`) row. On v1.1.32, it will show "Unable to verify setting. Please upgrade to configure." The setting is active; Brainstore v1.1.32 does not report it back to the control plane. It will show correctly after upgrading to v2.x.

    <Note>
      This step is strongly recommended but not mechanically enforced. Deployments running mixed WAL formats become increasingly difficult to tune at scale.
    </Note>

    ### Run the preflight check

    Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url). Verify the following expected statuses before proceeding:

    | Setting                                              | Expected status                                 |
    | ---------------------------------------------------- | ----------------------------------------------- |
    | License                                              | Configured                                      |
    | Telemetry                                            | Configured                                      |
    | Data plane service token                             | Configured                                      |
    | Brainstore default mode (`BRAINSTORE_DEFAULT`)       | Configured                                      |
    | Insert logs (`INSERT_LOGS2`)                         | Configured                                      |
    | Insert row references (`BRAINSTORE_INSERT_ROW_REFS`) | Configured                                      |
    | Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)      | Configured                                      |
    | Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)        | Configured                                      |
    | Proxy URL (`BRAINSTORE_AI_PROXY_URL`)                | Configured                                      |
    | Redis (`BRAINSTORE_REDIS_URI`)                       | Configured                                      |
    | Brainstore direct writes                             | "Upgrade to configure Brainstore direct writes" |

    <Note>
      On v1.1.32, items like WAL footer version, response cache URI, and code bundle URI are not displayed. They appear only after upgrading to v2.x. The HTTP/2 check may show a warning on v1.1.32. This resolves after upgrading.
    </Note>

    If any of the first ten rows are not green, resolve them before proceeding. Contact [Braintrust support](mailto:support@braintrust.dev) if you need help.

    ### Update Workload Identity bindings

    Data plane v2.0 introduces API pod endpoints that access GCS directly. Prior versions only accessed GCS from Brainstore pods. The GCP IAM binding must be updated to grant the `braintrust-api` Kubernetes service account Workload Identity access before upgrading.

    * **If using the Braintrust GCP Terraform module**, update to [v1.5.2](https://github.com/braintrustdata/terraform-google-braintrust-data-plane/releases/tag/v1.5.2) and run `terraform apply` before upgrading Helm to v6.2.1. The updated module includes the binding for both the `brainstore` and `braintrust-api` service accounts.

      ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      module "braintrust-data-plane" {
        source = "github.com/braintrustdata/terraform-google-braintrust-data-plane?ref=v1.5.2"

        # ... other configuration
      }
      ```

      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      terraform apply
      ```
    * **If managing IAM manually**, add the binding:

      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      gcloud iam service-accounts add-iam-policy-binding \
        <brainstore-gcp-service-account>@<project>.iam.gserviceaccount.com \
        --role roles/iam.workloadIdentityUser \
        --member "serviceAccount:<project>.svc.id.goog[<namespace>/braintrust-api]"
      ```

    <Warning>
      **Apply these IAM changes before upgrading to v2.x.** Without this binding, the API pod will return errors on endpoints that access GCS directly.
    </Warning>

    <h2 id="upgrade-to-v2-x-gcp">
      2\. Upgrade to v2.x
    </h2>

    With preflight complete, upgrade to Helm chart v6.2.1, which ships the recommended data plane v2.1.1 images. The WAL footer also bumps to v3 in the same apply.

    <Note>
      If you are already on Helm chart v6.2.1 with WAL footer version set to v3, skip to [Enable no-PostgreSQL mode](#enable-no-postgresql-mode-gcp).
    </Note>

    ### Apply the upgrade

    Update your `helm-values.yaml` to bump the WAL footer to v3. Because the latest chart defaults no-PostgreSQL mode on, explicitly disable it for the base upgrade. Enable it only in the next step.

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    brainstoreWalFooterVersion: "v3"
    skipPgForBrainstoreObjects: ""
    ```

    **Breaking change:** Chart v6.2.1 disables code function execution by default. To preserve code-backed scorers, tools, or functions on a single-org deployment, add:

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    api:
      allowCodeFunctionExecution: true
    ```

    <Warning>
      If your deployment uses `ORG_NAME=*` or hosts multiple Braintrust organizations, [contact Braintrust](mailto:support@braintrust.dev) before enabling code function execution.
    </Warning>

    Apply Helm chart v6.2.1:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    helm upgrade braintrust \
      oci://public.ecr.aws/braintrust/helm/braintrust \
      --namespace braintrust \
      --version 6.2.1 \
      --values helm-values.yaml
    ```

    Pods will automatically restart after applying the upgrade.

    ### Verify settings

    After the pods have cycled, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) and verify the following are all green:

    | Setting                                              | Expected status                      |
    | ---------------------------------------------------- | ------------------------------------ |
    | License                                              | Configured                           |
    | Telemetry                                            | Configured                           |
    | Data plane service token                             | Configured                           |
    | Brainstore default mode (`BRAINSTORE_DEFAULT`)       | Configured                           |
    | Insert logs (`INSERT_LOGS2`)                         | Configured                           |
    | Insert row references (`BRAINSTORE_INSERT_ROW_REFS`) | Configured                           |
    | Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)      | Configured                           |
    | Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)        | Configured                           |
    | Proxy URL (`BRAINSTORE_AI_PROXY_URL`)                | Configured                           |
    | Redis (`BRAINSTORE_REDIS_URI`)                       | Configured                           |
    | Response cache URI (`BRAINSTORE_RESPONSE_CACHE_URI`) | Configured                           |
    | Code bundle URI (`BRAINSTORE_CODE_BUNDLE_URI`)       | Configured                           |
    | HTTP/2                                               | Data plane is using HTTP/2 or higher |

    **Brainstore direct writes** will show "Upgrade to configure Brainstore direct writes." This is enabled in the next step.

    ### Validate the base upgrade

    Before enabling no-PostgreSQL mode, validate the workloads your team relies on. For example, trace one production-shaped request, run an eval suite you use regularly, and invoke or iterate on a prompt. If you use online scorers or automations, trigger one through its normal online path. For trace-level scorers, choose one that uses full trace context. If these workflows round-trip cleanly through the data plane and look right in the UI, continue to no-PostgreSQL mode.

    <h3 id="enable-no-postgresql-mode-gcp">
      Enable no-PostgreSQL mode
    </h3>

    No-PostgreSQL mode removes PostgreSQL from the Brainstore write path, delivering higher ingestion throughput. This step is a prerequisite for [Topics](/observe/topics) but does not enable them.

    <Warning>
      The switch to no-PostgreSQL mode is one-way: Once Brainstore is writing data directly, rolling back requires downtime to drain and re-ingest. Enable it only when you are ready to commit.
    </Warning>

    Set `skipPgForBrainstoreObjects` in your `helm-values.yaml`:

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    skipPgForBrainstoreObjects: "all"
    ```

    Keep Helm chart v6.2.1 and apply the updated values:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    helm upgrade braintrust \
      oci://public.ecr.aws/braintrust/helm/braintrust \
      --namespace braintrust \
      --version 6.2.1 \
      --values helm-values.yaml
    ```

    Then repeat the same workload validation after enabling no-PostgreSQL mode. If the same representative workflows round-trip cleanly through the data plane and look right in the UI, proceed to the next environment.

    ### Enable Topics

    [Topics](/observe/topics) for self-hosted deployments has specific deployment, inference, billing, and maintenance requirements. Completing the full v2.x upgrade and no-PostgreSQL mode migration is a prerequisite, and the following conditions must also be met before Topics can be enabled:

    * **Standard deployment required.** Topics is supported on standard Terraform/Helm deployments only. Custom Kubernetes clusters using the Helm chart on non-standard infrastructure are not supported.
    * **Braintrust-hosted inference required.** Topics runs LLM calls on models hosted by Braintrust with Zero Data Retention (ZDR). Bring-your-own-model is not supported. Currently US-only.
    * **Built-in models must be enabled.** Self-hosted organizations have [built-in models](/admin/ai-providers#manage-built-in-models) disabled by default, so no trace data leaves your network boundary unless you opt in. Because Topics depends on built-in models, an admin must explicitly enable them before Topics can run.
    * **Pricing is not included by default.** Topics usage is not covered by standard contracts. Discuss pricing with your account team before proceeding.
    * **Ongoing maintenance required.** Self-hosted Topics deployments run on a frequent-release build track separate from the tagged data plane versions and will require regular upgrades to receive the latest fixes and improvements.

    If you meet all of these requirements and want to proceed, contact your account team or [Braintrust support](mailto:support@braintrust.dev). Until Braintrust enables Topics access for your organization, the Topics page and Topics automations remain blocked, even after the upgrade and no-PostgreSQL migration are complete.

    ## Configuration reference

    <Accordion title="Core configuration (auto-set by Helm v5.1.0)">
      | Variable                         | Source                                       | Pods                       |
      | -------------------------------- | -------------------------------------------- | -------------------------- |
      | `BRAINSTORE_REDIS_URI`           | From `REDIS_URL` secret                      | reader, writer, fastreader |
      | `BRAINSTORE_DEFAULT`             | Hardcoded `"force"`                          | API                        |
      | `INSERT_LOGS2`                   | Hardcoded `"true"`                           | API                        |
      | `BRAINSTORE_INSERT_ROW_REFS`     | Hardcoded `"true"`                           | API                        |
      | `BRAINSTORE_REALTIME_WAL_BUCKET` | From `objectStorage` values                  | API                        |
      | `BRAINSTORE_AI_PROXY_URL`        | Built from `api.name` and `api.service.port` | reader, writer, fastreader |
      | `BRAINSTORE_XACT_MANAGER_URI`    | From `REDIS_URL` secret                      | reader, writer, fastreader |
      | `BRAINSTORE_RESPONSE_CACHE_URI`  | Auto-derived from `objectStorage` config     | reader, writer, fastreader |
      | `BRAINSTORE_CODE_BUNDLE_URI`     | Auto-derived from `objectStorage` config     | reader, writer, fastreader |
    </Accordion>

    <Accordion title="WAL footer version (requires explicit configuration)">
      | Variable                              | How to set                                                                                   | Since  | Pods |
      | ------------------------------------- | -------------------------------------------------------------------------------------------- | ------ | ---- |
      | `BRAINSTORE_WAL_FOOTER_VERSION`       | Set `brainstoreWalFooterVersion` in `helm-values.yaml`                                       | v5.1.0 | API  |
      | `BRAINSTORE_WAL_USE_EFFICIENT_FORMAT` | Auto-enabled when either `brainstoreWalFooterVersion` or `skipPgForBrainstoreObjects` is set | v5.1.0 | API  |

      Set `brainstoreWalFooterVersion: "v1"` as part of the pre-upgrade steps. Only set to `"v3"` after successfully deploying v2.x.
    </Accordion>

    <Accordion title="No-PostgreSQL mode (opt-in, post-upgrade)">
      | Variable                             | How to set                                             | Since  | Pods                       |
      | ------------------------------------ | ------------------------------------------------------ | ------ | -------------------------- |
      | `SKIP_PG_FOR_BRAINSTORE_OBJECTS`     | Set `skipPgForBrainstoreObjects` in `helm-values.yaml` | v5.1.0 | API                        |
      | `BRAINSTORE_ASYNC_SCORING_OBJECTS`   | Auto-derived from `skipPgForBrainstoreObjects`         | v5.1.0 | reader, writer, fastreader |
      | `BRAINSTORE_LOG_AUTOMATIONS_OBJECTS` | Auto-derived from `skipPgForBrainstoreObjects`         | v5.1.0 | reader, writer, fastreader |

      Setting `skipPgForBrainstoreObjects: "all"` is a prerequisite for enabling Topics. The chart automatically fans this value out to `BRAINSTORE_ASYNC_SCORING_OBJECTS` and `BRAINSTORE_LOG_AUTOMATIONS_OBJECTS`.
    </Accordion>
  </Tab>

  <Tab title="Azure" icon="https://img.logo.dev/azure.microsoft.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    This guide shows the process for upgrading the Braintrust data plane to v2.x in your Azure account.

    ## 1. Prepare for v2.x

    Before upgrading to data plane v2.x, you need to reach Helm chart v5.0.1 (data plane v1.1.32) and enable the efficient WAL format. v1.1.32 is the required foundation for v2.x. It ensures all Brainstore configuration is in place and verified before the upgrade.

    ### Upgrade Helm chart

    Check your current Helm chart version:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    helm list -n braintrust
    ```

    Then follow the path for your starting point:

    | Starting version                     | Sub-steps to follow                                                       |
    | ------------------------------------ | ------------------------------------------------------------------------- |
    | Helm chart \< v3.1.1                 | 1 → 2 → 3                                                                 |
    | Helm chart v3.x                      | 2 → 3                                                                     |
    | Helm chart v4.x                      | 3 only                                                                    |
    | Helm chart v5.0.1                    | Skip to [Enable efficient WAL format](#enable-efficient-wal-format-azure) |
    | Helm chart v6.0.0, v6.1.0, or v6.2.0 | Skip to [Upgrade to v2.x](#upgrade-to-v2-x-azure)                         |
    | Helm chart v6.2.1+                   | Skip to [Enable no-PostgreSQL mode](#enable-no-postgresql-mode-azure)     |

    <Steps>
      <Step title="Upgrade to Helm chart v3.1.1">
        This upgrades the data plane from v1.1.27 to v1.1.31. There are no breaking changes.

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        helm upgrade braintrust \
          oci://public.ecr.aws/braintrust/helm/braintrust \
          --namespace braintrust \
          --version 3.1.1 \
          --values helm-values.yaml
        ```

        After applying, restart pods:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        kubectl rollout restart deployment -n braintrust
        ```
      </Step>

      <Step title="Upgrade to Helm chart v4.0.0">
        This step upgrades the data plane to v1.1.32 and introduces bidirectional communication between Brainstore and API pods. Brainstore now needs to reach the API pods. The chart auto-sets `BRAINSTORE_AI_PROXY_URL` to `http://braintrust-api:8000`.

        <Warning>
          If your cluster has network policies or security rules restricting traffic between pods, allow Brainstore pods to reach the API service on port 8000 before upgrading.
        </Warning>

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        helm upgrade braintrust \
          oci://public.ecr.aws/braintrust/helm/braintrust \
          --namespace braintrust \
          --version 4.0.0 \
          --values helm-values.yaml
        ```

        After applying, restart pods:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        kubectl rollout restart deployment -n braintrust
        ```
      </Step>

      <Step title="Upgrade to Helm chart v5.0.1">
        This step enables fast readers, isolated Brainstore nodes that handle common UI queries. Fast readers are enabled by default with 2 replicas and use the same node spec as standard readers, **increasing your cluster node count by 2**. You can upgrade directly to v5.0.1 from any v4.x version.

        <Warning>
          Before upgrading, account for 2 additional fast reader nodes in your cluster capacity. If you have customized `brainstore.reader` settings in `values.yaml`, mirror those customizations to the new `brainstore.fastreader` block. See [Configure Brainstore fast readers](/admin/self-hosting/advanced#configure-brainstore-fast-readers) for details.
        </Warning>

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        helm upgrade braintrust \
          oci://public.ecr.aws/braintrust/helm/braintrust \
          --namespace braintrust \
          --version 5.0.1 \
          --values helm-values.yaml
        ```

        After applying, restart pods:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        kubectl rollout restart deployment -n braintrust
        ```
      </Step>
    </Steps>

    <h3 id="enable-efficient-wal-format-azure">
      Enable efficient WAL format
    </h3>

    <Warning>
      This must be a separate `helm upgrade` after confirming all pods are running v1.1.32. Setting this during the same upgrade as the version bump risks Brainstore nodes still rolling out being unable to read the new WAL format.
    </Warning>

    Set `brainstoreWalFooterVersion` in your `helm-values.yaml`:

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    brainstoreWalFooterVersion: "v1"
    ```

    Then apply:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    helm upgrade braintrust \
      oci://public.ecr.aws/braintrust/helm/braintrust \
      --namespace braintrust \
      --version 5.1.0 \
      --values helm-values.yaml
    ```

    On chart v5.1.0+, pods will automatically restart after applying the upgrade.

    Once the pods have cycled, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) and check the WAL footer version (`BRAINSTORE_WAL_FOOTER_VERSION`) row. On v1.1.32, it will show "Unable to verify setting. Please upgrade to configure." The setting is active; Brainstore v1.1.32 does not report it back to the control plane. It will show correctly after upgrading to v2.x.

    <Note>
      This step is strongly recommended but not mechanically enforced. Deployments running mixed WAL formats become increasingly difficult to tune at scale.
    </Note>

    ### Run the preflight check

    Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url). Verify the following expected statuses before proceeding:

    | Setting                                              | Expected status                                 |
    | ---------------------------------------------------- | ----------------------------------------------- |
    | License                                              | Configured                                      |
    | Telemetry                                            | Configured                                      |
    | Data plane service token                             | Configured                                      |
    | Brainstore default mode (`BRAINSTORE_DEFAULT`)       | Configured                                      |
    | Insert logs (`INSERT_LOGS2`)                         | Configured                                      |
    | Insert row references (`BRAINSTORE_INSERT_ROW_REFS`) | Configured                                      |
    | Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)      | Configured                                      |
    | Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)        | Configured                                      |
    | Proxy URL (`BRAINSTORE_AI_PROXY_URL`)                | Configured                                      |
    | Redis (`BRAINSTORE_REDIS_URI`)                       | Configured                                      |
    | Brainstore direct writes                             | "Upgrade to configure Brainstore direct writes" |

    <Note>
      On v1.1.32, items like WAL footer version, response cache URI, and code bundle URI are not displayed. They appear only after upgrading to v2.x. The HTTP/2 check may show a warning on v1.1.32. This resolves after upgrading.
    </Note>

    If any of the first ten rows are not green, resolve them before proceeding. Contact [Braintrust support](mailto:support@braintrust.dev) if you need help.

    ### Update Terraform module

    Update the Braintrust Azure Terraform module to [v1.1.0](https://github.com/braintrustdata/terraform-azure-braintrust-data-plane/releases/tag/v1.1.0) and apply before upgrading Helm to v6.2.1:

    ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    module "braintrust-data-plane" {
      source = "github.com/braintrustdata/terraform-azure-braintrust-data-plane?ref=v1.1.0"

      # ... other configuration
    }
    ```

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    terraform apply
    ```

    <h2 id="upgrade-to-v2-x-azure">
      2\. Upgrade to v2.x
    </h2>

    With preflight complete, upgrade to Helm chart v6.2.1, which ships the recommended data plane v2.1.1 images. The WAL footer also bumps to v3 in the same apply.

    <Note>
      If you are already on Helm chart v6.2.1 with WAL footer version set to v3, skip to [Enable no-PostgreSQL mode](#enable-no-postgresql-mode-azure).
    </Note>

    ### Apply the upgrade

    Update your `helm-values.yaml` to bump the WAL footer to v3. Because the latest chart defaults no-PostgreSQL mode on, explicitly disable it for the base upgrade. Enable it only in the next step.

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    brainstoreWalFooterVersion: "v3"
    skipPgForBrainstoreObjects: ""
    ```

    **Breaking change:** Chart v6.2.1 disables code function execution by default. To preserve code-backed scorers, tools, or functions on a single-org deployment, add:

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    api:
      allowCodeFunctionExecution: true
    ```

    <Warning>
      If your deployment uses `ORG_NAME=*` or hosts multiple Braintrust organizations, [contact Braintrust](mailto:support@braintrust.dev) before enabling code function execution.
    </Warning>

    Then apply Helm chart v6.2.1:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    helm upgrade braintrust \
      oci://public.ecr.aws/braintrust/helm/braintrust \
      --namespace braintrust \
      --version 6.2.1 \
      --values helm-values.yaml
    ```

    Pods will automatically restart after applying the upgrade.

    ### Verify settings

    After the pods have cycled, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) and verify the following are all green:

    | Setting                                              | Expected status                      |
    | ---------------------------------------------------- | ------------------------------------ |
    | License                                              | Configured                           |
    | Telemetry                                            | Configured                           |
    | Data plane service token                             | Configured                           |
    | Brainstore default mode (`BRAINSTORE_DEFAULT`)       | Configured                           |
    | Insert logs (`INSERT_LOGS2`)                         | Configured                           |
    | Insert row references (`BRAINSTORE_INSERT_ROW_REFS`) | Configured                           |
    | Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)      | Configured                           |
    | Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)        | Configured                           |
    | Proxy URL (`BRAINSTORE_AI_PROXY_URL`)                | Configured                           |
    | Redis (`BRAINSTORE_REDIS_URI`)                       | Configured                           |
    | Response cache URI (`BRAINSTORE_RESPONSE_CACHE_URI`) | Configured                           |
    | Code bundle URI (`BRAINSTORE_CODE_BUNDLE_URI`)       | Configured                           |
    | HTTP/2                                               | Data plane is using HTTP/2 or higher |

    **Brainstore direct writes** will show "Upgrade to configure Brainstore direct writes." This is enabled in the next step.

    ### Validate the base upgrade

    Before enabling no-PostgreSQL mode, validate the workloads your team relies on. For example, trace one production-shaped request, run an eval suite you use regularly, and invoke or iterate on a prompt. If you use online scorers or automations, trigger one through its normal online path. For trace-level scorers, choose one that uses full trace context. If these workflows round-trip cleanly through the data plane and look right in the UI, continue to no-PostgreSQL mode.

    <h3 id="enable-no-postgresql-mode-azure">
      Enable no-PostgreSQL mode
    </h3>

    No-PostgreSQL mode removes PostgreSQL from the Brainstore write path, delivering higher ingestion throughput. This step is a prerequisite for [Topics](/observe/topics) but does not enable them.

    <Warning>
      The switch to no-PostgreSQL mode is one-way: Once Brainstore is writing data directly, rolling back requires downtime to drain and re-ingest. Enable it only when you are ready to commit.
    </Warning>

    Set `skipPgForBrainstoreObjects` in your `helm-values.yaml`:

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    skipPgForBrainstoreObjects: "all"
    ```

    Keep Helm chart v6.2.1 and apply the updated values:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    helm upgrade braintrust \
      oci://public.ecr.aws/braintrust/helm/braintrust \
      --namespace braintrust \
      --version 6.2.1 \
      --values helm-values.yaml
    ```

    Then repeat the same workload validation after enabling no-PostgreSQL mode. If the same representative workflows round-trip cleanly through the data plane and look right in the UI, proceed to the next environment.

    ### Enable Topics

    Topics for self-hosted deployments is available as early access with limited eligibility. Completing the full v2.x upgrade and no-PostgreSQL mode migration is a prerequisite, but additional conditions must all be met before Topics can be enabled:

    * **Standard deployment required.** Topics is supported on standard Terraform/Helm deployments only. Custom Kubernetes clusters using the Helm chart on non-standard infrastructure are not supported.
    * **Braintrust-hosted inference required.** Topics runs LLM calls on models hosted by Braintrust with Zero Data Retention (ZDR). Bring-your-own-model is not supported. Currently US-only.
    * **Built-in models must be enabled.** Self-hosted organizations have [built-in models](/admin/ai-providers#manage-built-in-models) disabled by default, so no trace data leaves your network boundary unless you opt in. Because Topics depends on built-in models, an admin must explicitly enable them before Topics can run.
    * **Pricing is not included by default.** Topics usage is not covered by standard contracts. Discuss pricing with your account team before proceeding.
    * **Ongoing maintenance required.** Self-hosted Topics deployments run on a frequent-release build track separate from the tagged data plane versions and will require regular upgrades to receive the latest fixes and improvements.

    If you meet all of these requirements and want to proceed, contact your account team or [Braintrust support](mailto:support@braintrust.dev). Until Braintrust enables Topics access for your organization, the Topics page and Topics automations remain blocked, even after the upgrade and no-PostgreSQL migration are complete.

    ## Configuration reference

    <Accordion title="Core configuration (auto-set by Helm v5.1.0)">
      | Variable                         | Source                                       | Pods                       |
      | -------------------------------- | -------------------------------------------- | -------------------------- |
      | `BRAINSTORE_REDIS_URI`           | From `REDIS_URL` secret                      | reader, writer, fastreader |
      | `BRAINSTORE_DEFAULT`             | Hardcoded `"force"`                          | API                        |
      | `INSERT_LOGS2`                   | Hardcoded `"true"`                           | API                        |
      | `BRAINSTORE_INSERT_ROW_REFS`     | Hardcoded `"true"`                           | API                        |
      | `BRAINSTORE_REALTIME_WAL_BUCKET` | From `objectStorage` values                  | API                        |
      | `BRAINSTORE_AI_PROXY_URL`        | Built from `api.name` and `api.service.port` | reader, writer, fastreader |
      | `BRAINSTORE_XACT_MANAGER_URI`    | From `REDIS_URL` secret                      | reader, writer, fastreader |
      | `BRAINSTORE_RESPONSE_CACHE_URI`  | Auto-derived from `objectStorage` config     | reader, writer, fastreader |
      | `BRAINSTORE_CODE_BUNDLE_URI`     | Auto-derived from `objectStorage` config     | reader, writer, fastreader |
    </Accordion>

    <Accordion title="WAL footer version (requires explicit configuration)">
      | Variable                              | How to set                                                                                   | Since  | Pods |
      | ------------------------------------- | -------------------------------------------------------------------------------------------- | ------ | ---- |
      | `BRAINSTORE_WAL_FOOTER_VERSION`       | Set `brainstoreWalFooterVersion` in `helm-values.yaml`                                       | v5.1.0 | API  |
      | `BRAINSTORE_WAL_USE_EFFICIENT_FORMAT` | Auto-enabled when either `brainstoreWalFooterVersion` or `skipPgForBrainstoreObjects` is set | v5.1.0 | API  |

      Set `brainstoreWalFooterVersion: "v1"` as part of the pre-upgrade steps. Only set to `"v3"` after successfully deploying v2.x.
    </Accordion>

    <Accordion title="No-PostgreSQL mode (opt-in, post-upgrade)">
      | Variable                             | How to set                                             | Since  | Pods                       |
      | ------------------------------------ | ------------------------------------------------------ | ------ | -------------------------- |
      | `SKIP_PG_FOR_BRAINSTORE_OBJECTS`     | Set `skipPgForBrainstoreObjects` in `helm-values.yaml` | v5.1.0 | API                        |
      | `BRAINSTORE_ASYNC_SCORING_OBJECTS`   | Auto-derived from `skipPgForBrainstoreObjects`         | v5.1.0 | reader, writer, fastreader |
      | `BRAINSTORE_LOG_AUTOMATIONS_OBJECTS` | Auto-derived from `skipPgForBrainstoreObjects`         | v5.1.0 | reader, writer, fastreader |

      Setting `skipPgForBrainstoreObjects: "all"` is a prerequisite for enabling Topics. The chart automatically fans this value out to `BRAINSTORE_ASYNC_SCORING_OBJECTS` and `BRAINSTORE_LOG_AUTOMATIONS_OBJECTS`.
    </Accordion>
  </Tab>
</Tabs>

## Next steps

* [Self-hosting releases](/data-plane-changelog): release notes and infrastructure requirements for each data plane version
* [Advanced configuration](/admin/self-hosting/advanced): telemetry, network access, rate limiting, and other options