Migrate from HTTP Backend

If you're currently using the Stategraph HTTP backend (backend "http" blocks in your Terraform configuration), this guide walks you through migrating to Velocity's CLI-managed state.

Why Migrate

The HTTP backend works with standard terraform commands but has limitations:

  • No workspace support — Terraform's workspace select fails against the HTTP backend
  • No parallel execution — state-level locking blocks concurrent operations
  • No multi-state transactions — each state is managed independently

Velocity replaces the HTTP backend with CLI-managed state (stategraph tf commands), enabling parallel execution, resource-level locking, and multi-state transactions.

Prerequisites

  • Stategraph CLI installed
  • Terraform or OpenTofu installed
  • Access to your current HTTP backend states
  • Your Stategraph tenant ID (run stategraph user tenants list)
export STATEGRAPH_API_BASE="https://your-stategraph-instance"
export STATEGRAPH_API_KEY="<your-api-key>"

Migration Steps

Repeat these steps for each Terraform root module that uses the HTTP backend.

1. Pull the Current State

From the module directory (where your main.tf lives), initialize against the existing HTTP backend and pull the state to a local file:

cd path/to/module
terraform init
terraform state pull > terraform.tfstate

2. Import into Velocity

Import the local state file into Stategraph for Velocity:

stategraph import tf \
  --tenant <tenant-id> \
  --name <state-name> \
  terraform.tfstate

The --name should be a descriptive identifier for this state (e.g., production/app, staging/networking).

This creates a new Velocity-managed state and writes a stategraph.json file in the current directory with the state ID.

3. Remove the Backend Block

Remove the backend "http" block from your Terraform configuration. Before:

terraform {
  required_providers {
    # ...
  }
}

terraform {
  backend "http" {
    address = "https://stategraph.example.com/api/v1/states/backend/<group-id>"
  }
}

After:

terraform {
  required_providers {
    # ...
  }
}

4. Clean Up

Remove the local state file — state is now managed by Stategraph:

rm -f terraform.tfstate

5. Commit Changes

Commit the updated stategraph.json and the modified Terraform configuration:

git add stategraph.json main.tf
git commit -m "Migrate state from HTTP backend to Velocity"

Bulk Migration Example

If you have multiple modules (e.g., production/app, production/db, production/metrics), you can script the migration:

export STATEGRAPH_TENANT_ID="<tenant-id>"

for dir in production/*/; do
  echo "Migrating $dir..."
  cd "$dir"

  # Pull state from HTTP backend
  terraform init
  terraform state pull > terraform.tfstate

  # Import into Velocity
  stategraph import tf \
    --tenant "$STATEGRAPH_TENANT_ID" \
    --name "$dir" \
    terraform.tfstate

  # Clean up local state
  rm -f terraform.tfstate

  cd -
done

After running the script, remove all backend "http" blocks and commit the changes.

Using Velocity After Migration

Once migrated, use stategraph tf commands instead of terraform plan and terraform apply:

# Single state
stategraph tf plan --out plan.json
stategraph tf apply plan.json

# Multiple states in one transaction
stategraph tf mtx --out plan.json ./production/*/

The CLI auto-discovers state IDs from stategraph.json files in each directory.

Configuration

By default, Velocity uses tofu as the execution binary. To use Terraform instead:

export TF_CMD=terraform

Verification

After migration, verify that Velocity can plan against each state:

stategraph tf plan --out plan.json

A clean plan (no changes) confirms the state was imported correctly.

Troubleshooting

"State not found" during plan

The stategraph.json file is missing or has an incorrect state_id. Re-run the import step to regenerate it.

Plan shows resources being recreated

The imported state may not match the current infrastructure. This usually means the wrong state file was imported. Pull the state again from the HTTP backend and re-import.

Permission errors

Importing and deleting states requires admin privileges. If you get ADMIN_REQUIRED, ask an admin to grant you admin access in Settings > Users.