Upgrade to data plane v2.0

Data plane v2.0 provides many new features, including trace-level scorers, topics for automated log insights, and sandboxes for agent evals.

AWS
GCP
Azure

This guide shows the process for upgrading the Braintrust data plane to v2.0 in your AWS account.

1. Prepare for v2.0

Before upgrading to data plane v2.0, 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.0. 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:

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

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.

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v3.1.3"

  # ... other configuration
}

terraform apply

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.

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v4.0.0"

  # ... other configuration
}

terraform apply

The data plane version does not change in this step.

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.

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.

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v4.5.0"

  # ... other configuration
}

terraform apply

Enable efficient WAL format

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.

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

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v4.5.0"

  brainstore_wal_footer_version = "v1"

  # ... other configuration
}

terraform apply

After applying, go to Settings > Data plane 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.” — this is expected. 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.0.

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

Run the preflight check

Go to Settings > Data plane. 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”

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.0. The HTTP/2 check may show a warning on v1.1.32. This resolves after upgrading.

If any of the first ten rows are not green, resolve them before proceeding. Contact Braintrust support if you need help.

2. Upgrade to v2.0

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

Apply the upgrade

Update your module to v5.0.0 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.0 nodes will understand the v3 format on startup.

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v5.0.0"

  brainstore_wal_footer_version = "v3"

  # ... other configuration
}

terraform apply

Verify settings

Go to Settings > Data plane 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
WAL footer version (`BRAINSTORE_WAL_FOOTER_VERSION`)	v3
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.

Enable no-PostgreSQL mode

No-PostgreSQL mode removes PostgreSQL from the Brainstore write path, delivering higher ingestion throughput and unlocking Topics. This step is a prerequisite for Topics but does not enable them.

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.

Update your module to v5.1.0 and set skip_pg_for_brainstore_objects = "all":

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v5.1.0"

  brainstore_wal_footer_version  = "v3"
  skip_pg_for_brainstore_objects = "all"

  # ... other configuration
}

terraform apply

Validate that reads, writes, scoring, and automations all function normally.

Enable Topics

Go to the Braintrust UI to enable Topics per-project.

Configuration reference

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

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.0.

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.

This guide shows the process for upgrading the Braintrust data plane to v2.0 in your GCP account.

1. Prepare for v2.0

Before upgrading to data plane v2.0, 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.0. It ensures all Brainstore configuration is in place and verified before the upgrade.

Upgrade Helm chart

Check your current Helm chart version:

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

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.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 3.1.1 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

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.

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.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 4.0.0 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

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.

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 for details.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 5.0.1 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

Enable efficient WAL format

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.

Set brainstoreWalFooterVersion in your helm-values.yaml:

brainstoreWalFooterVersion: "v1"

Then apply:

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 Settings > Data plane 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.” — this is expected. 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.0.

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

Run the preflight check

Go to Settings > Data plane. 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”

If any of the first ten rows are not green, resolve them before proceeding. Contact Braintrust support 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.1 and run terraform apply before upgrading Helm to v6.0.0. The updated module includes the binding for both the brainstore and braintrust-api service accounts.
```
module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-google-braintrust-data-plane?ref=v1.5.1"

  # ... other configuration
}
```
```
terraform apply
```

If managing IAM manually, add the binding:

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]"

Apply these IAM changes before upgrading to v2.0. Without this binding, the API pod will return errors on endpoints that access GCS directly.

2. Upgrade to v2.0

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

Apply the upgrade

Update your helm-values.yaml to bump the WAL footer to v3:

brainstoreWalFooterVersion: "v3"

Apply Helm chart v6.0.0:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 6.0.0 \
  --values helm-values.yaml

Pods will automatically restart after applying the upgrade.

Verify settings

After the pods have cycled, go to Settings > Data plane 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
WAL footer version (`BRAINSTORE_WAL_FOOTER_VERSION`)	v3
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.

Enable no-PostgreSQL mode

No-PostgreSQL mode removes PostgreSQL from the Brainstore write path, delivering higher ingestion throughput and unlocking Topics. This step is a prerequisite for Topics but does not enable them.

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.

Set skipPgForBrainstoreObjects in your helm-values.yaml:

skipPgForBrainstoreObjects: "all"

Apply Helm chart v6.1.0:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 6.1.0 \
  --values helm-values.yaml

Then validate that reads, writes, scoring, and automations all function normally.

Enable Topics

Go to the Braintrust UI to enable Topics per-project.

Configuration reference

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

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.0.

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.

This guide shows the process for upgrading the Braintrust data plane to v2.0 in your Azure account.

1. Prepare for v2.0

Upgrade Helm chart

Check your current Helm chart version:

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

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.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 3.1.1 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

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.

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.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 4.0.0 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

Upgrade to Helm chart v5.0.1

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 5.0.1 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

Enable efficient WAL format

Set brainstoreWalFooterVersion in your helm-values.yaml:

brainstoreWalFooterVersion: "v1"

Then apply:

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 Settings > Data plane 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.” This is expected. 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.0.

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

Run the preflight check

Go to Settings > Data plane. 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”

If any of the first ten rows are not green, resolve them before proceeding. Contact Braintrust support if you need help.

Update Terraform module

Update the Braintrust Azure Terraform module to v1.1.0 and apply before upgrading Helm to v6.0.0:

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-azure-braintrust-data-plane?ref=v1.1.0"

  # ... other configuration
}

terraform apply

2. Upgrade to v2.0

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

Apply the upgrade

Update your helm-values.yaml to bump the WAL footer to v3:

brainstoreWalFooterVersion: "v3"

Then apply Helm chart v6.0.0:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 6.0.0 \
  --values helm-values.yaml

Pods will automatically restart after applying the upgrade.

Verify settings

After the pods have cycled, go to Settings > Data plane 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
WAL footer version (`BRAINSTORE_WAL_FOOTER_VERSION`)	v3
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.

Enable no-PostgreSQL mode

No-PostgreSQL mode removes PostgreSQL from the Brainstore write path, delivering higher ingestion throughput and unlocking Topics. This step is a prerequisite for Topics but does not enable them.

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.

Set skipPgForBrainstoreObjects in your helm-values.yaml:

skipPgForBrainstoreObjects: "all"

Apply Helm chart v6.1.0:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 6.1.0 \
  --values helm-values.yaml

Then validate that reads, writes, scoring, and automations all function normally.

Enable Topics

Go to the Braintrust UI to enable Topics per-project.

Configuration reference

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

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.0.

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

Next steps

Self-hosting releases — release notes and infrastructure requirements for each data plane version
Advanced configuration — telemetry, network access, rate limiting, and other options

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

​1. Prepare for v2.0

​Upgrade Terraform module

​Enable efficient WAL format

​Run the preflight check

​2. Upgrade to v2.0

​Apply the upgrade

​Verify settings

​Enable no-PostgreSQL mode

​Enable Topics

​Configuration reference

​1. Prepare for v2.0

​Upgrade Helm chart

​Enable efficient WAL format

​Run the preflight check

​Update Workload Identity bindings

​2. Upgrade to v2.0

​Apply the upgrade

​Verify settings

​Enable no-PostgreSQL mode

​Enable Topics

​Configuration reference

​1. Prepare for v2.0

​Upgrade Helm chart

​Enable efficient WAL format

​Run the preflight check

​Update Terraform module

​2. Upgrade to v2.0

​Apply the upgrade

​Verify settings

​Enable no-PostgreSQL mode

​Enable Topics

​Configuration reference

​Next steps

1. Prepare for v2.0

Upgrade Terraform module

Enable efficient WAL format

Run the preflight check

2. Upgrade to v2.0

Apply the upgrade

Verify settings

Enable no-PostgreSQL mode

Enable Topics

Configuration reference

1. Prepare for v2.0

Upgrade Helm chart

Enable efficient WAL format

Run the preflight check

Update Workload Identity bindings

2. Upgrade to v2.0

Apply the upgrade

Verify settings

Enable no-PostgreSQL mode

Enable Topics

Configuration reference

1. Prepare for v2.0

Upgrade Helm chart

Enable efficient WAL format

Run the preflight check

Update Terraform module

2. Upgrade to v2.0

Apply the upgrade

Verify settings

Enable no-PostgreSQL mode

Enable Topics

Configuration reference

Next steps