Documentation - Stategraph Docs

Documentation

Stategraph is infrastructure as code with a database underneath, and works with the Terraform and OpenTofu code that you have. Stategraph Orchestration runs plans and applies in your pull requests, with policy checks and approvals. Infrastructure as a Database replaces the state file, so plans read only what your change reaches, changes that do not overlap apply at the same time, and you can query every state with SQL.

Start here

Stategraph Cloud

Sign up, connect GitHub or GitLab, and run your first plan and apply from a pull request.

Self-hosted

Run Open Source with Docker Compose, or the Enterprise build with a license key.

Stategraph Orchestration

Orchestration works with GitHub and GitLab, as Open Source or Enterprise.

  • Each pull request gets a plan comment, policy checks, and the required approvals.
  • An apply runs on a stategraph apply comment or on merge.
  • Drift detection runs on a schedule.
  • Plans and applies run on your own GitHub Actions or GitLab CI runners, with Terraform, OpenTofu, the stategraph CLI, Terragrunt, Pulumi, CDKTF, or any command-line tool.
  • Your state stays where it is, or you can keep it in Infrastructure as a Database.

Infrastructure as a Database

Infrastructure as a Database keeps your state in PostgreSQL as a graph of resources and dependencies, not as a state file:

  • A plan reads only the resources that the change reaches.
  • Locks hold single resources, not the full state.
  • Each plan and apply is a recorded transaction.
  • You can query all of your infrastructure with SQL.

Infrastructure as a Database also works without Orchestration, with your current CI system: see CI and orchestrators.

Why Stategraph

What is Stategraph, in 2 minutes. Watch on YouTube.

A Terraform state file is one JSON file per workspace, and each run locks all of it. Teams split the state so that they can work at the same time, and then connect the states by hand or with Terragrunt. Stategraph removes these limits.

State file

vpc + subnetplan and apply
bucket + policywaitingplan and apply

One run at a time.

Stategraph

vpc + subnetplan and apply
bucket + policyplan and apply

Both at the same time.

Two changes to one state.
With a state file, the second change waits for the lock.
With Stategraph, changes that do not overlap run at the same time.

State file

aws_sgaws_dbaws_db_replicaaws_bucketbucket_policy

The full state locks.

Stategraph

aws_sgaws_dbaws_db_replicaaws_bucketbucket_policy

Only the changed resources lock.

A change to aws_db and aws_db_replica. With Stategraph, the rest of the state stays free for other changes.

State files

networking→compute→application

One apply per state. A failure leaves a partial change.

Stategraph

networkingcomputeapplication

One transaction. All states apply, or none do.

A change that reaches three states.
Problem With Stategraph
Runs wait for the lock on the full state. Stategraph detects conflicts per resource. Changes that do not overlap plan and apply at the same time, in the same state. See Resource-level locking.
A large state makes each plan slow. A plan reads only the resources that the change reaches. See Infrastructure as a Database.
Split states need dependencies that you connect by hand. A plan follows the dependencies between states. The states that a change reaches plan and apply as one transaction: all of them apply, or none do. See Multi-state transactions.
A rename or a move can lose state. A refactor session follows your HCL changes and writes the moved blocks for you. See Refactoring.
Changes reach the cloud without review. Each change goes through a pull request: a plan, policy checks, approvals, and an apply on a comment or on merge. An apply locks the directories and workspaces that it changes, so no other pull request applies over them. Layered runs and stacks put dependent changes in order. See Pull request workflow.
Anyone with access can apply to production. With Enterprise, RBAC, CODEOWNERS enforcement, approval gates, and centralized configuration control who can plan and apply. Runs can get cloud credentials through OIDC. See Security best practices.
Changes made outside Terraform stay hidden. Scheduled drift detection compares your infrastructure with your code, and can open an issue. See Drift detection.
You cannot see what you run or how it changed. Query every state with SQL, and keep your queries in dashboards. See the blast radius, the dependency graph, the history of each change, and the cloud resources that no state manages. See Query.
You see what a change costs only on the bill. Stategraph estimates the cost of each plan and shows it in the pull request. It totals the cost per state and per tenant, and attributes it by tag. See Cost.
AI agents need wide access to your infrastructure. Skills for Claude Code and other agents, tokens with limited capabilities, and a timeline of each action. See AI agents.

Adopt Stategraph in two steps:

  1. Start with Orchestration and the tool that you use now: Terraform, OpenTofu, Terragrunt, Pulumi, or CDKTF. Your state stays where it is.
  2. Change to the stategraph engine, and import your state into Infrastructure as a Database. You can export it back to a Terraform state file.

Browse the docs

Get started

Orchestration

Infrastructure as a Database

Administration

CLI

Reference

For help, see Support.

Get engineering updates
Short updates on what we're building. No filler.
© Stategraph • Visitor 0