Technical Deep Dive

How Stategraph
really works

Terraform state as a directed acyclic graph (DAG) stored in PostgreSQL, enabling row-level locking, MVCC, and SQL queryability through a REST API.

PostgreSQL Backend DAG Architecture

System Overview

Stategraph fundamentally reimagines how Terraform state is managed by representing it as a directed acyclic graph in a PostgreSQL database with intelligent resource management.

Terraform HCL
Your existing code
→
Stategraph REST API
Resource Management
→
PostgreSQL
DAG Storage

Stategraph transforms how Terraform manages infrastructure state by representing it as a graph database structure. This enables parallel operations, granular locking, and intelligent dependency management - all while maintaining full compatibility with your existing Terraform code.

The Stategraph CLI

The Stategraph CLI seamlessly integrates with your existing Terraform workflow.

CLI Commands Mirror Terraform

stategraph cli
$ stategraph init # Wraps terraform init
$ stategraph plan # Wraps terraform plan, captures output
$ stategraph apply # Wraps terraform apply with subgraph isolation
$ stategraph destroy # Wraps terraform destroy
$ stategraph refresh # Partial refresh of affected resources only
# All Terraform commands work as expected
# Stategraph intercepts and enhances state operations

Drop-in replacement for the Terraform CLI with enhanced state management capabilities.

Core Components

Interface

CLI / Web UI

→
API Layer

REST API

→
Processing

Plan Analyzer

→
Storage

PostgreSQL

API Layer

Modern API for infrastructure operations and management.

  • Resource management
  • State operations
  • Query interface
  • Real-time updates

Plan Analyzer

Advanced analysis of infrastructure changes and dependencies.

  • Change detection
  • Dependency mapping
  • Impact analysis
  • Optimization logic

Graph Engine

Sophisticated graph operations for state management.

  • Dependency resolution
  • Parallel execution planning
  • Conflict detection
  • Resource isolation

Data Layer

Enterprise-grade database storage for infrastructure state.

  • ACID compliance
  • High availability
  • Instant queries
  • Audit trail

State Optimizer

Intelligent state reconstruction for efficient operations.

  • Minimal state building
  • Query result caching
  • Performance optimization
  • Resource efficiency

Concurrency Control

Advanced parallel execution for independent operations.

  • Granular locking
  • Parallel execution
  • Conflict resolution
  • Transaction management

How It Works

Stategraph transforms traditional state management into a modern, scalable architecture.

main.tf
Your HCL Code
→
Stategraph CLI
stategraph plan
Planning
Generate Changes
→
Analysis
Process State
→
Storage
Save State
Database
Graph Storage
Infrastructure Graph
State History
Locks & Transactions
stategraph apply
User initiates
→
Optimization
Prepare execution
→
Terraform Apply
Execute changes

Concurrency Model

Stategraph enables multiple teams to work on independent infrastructure changes simultaneously.

Parallel Execution

  1. Analyze: Identify resource dependencies
  2. Isolate: Determine independent changes
  3. Lock: Secure only required resources
  4. Execute: Run changes in parallel
  5. Commit: Apply updates atomically
  6. Release: Free resources for others

Parallel Operations Example

Transaction A
Updating RDS Instance
LOCK: aws_db_instance.primary
UPDATE: size → db.t3.large
COMMIT: Success
Subgraph: 23 resources
Transaction B
Updating S3 Bucket
LOCK: aws_s3_bucket.assets
UPDATE: versioning → true
COMMIT: Success
Subgraph: 8 resources
Transaction C
Updating IAM Role
LOCK: aws_iam_role.lambda
UPDATE: policies → [new]
COMMIT: Success
Subgraph: 15 resources

All three transactions execute in parallel because they operate on non-overlapping subgraphs

Performance Characteristics

Capability Traditional Backend Stategraph
Concurrent Operations Sequential only Full parallelization
State Queries Download entire state Instant targeted queries
Lock Granularity Entire state file Individual resources
Performance at Scale Degrades with size Consistently fast
Audit Trail External solutions Built-in history
Recovery Manual restoration Point-in-time recovery

Technology Stack

Application

Stategraph CLI
REST API
OCaml Runtime

Data

Plan Analyzer
DAG Operations
PostgreSQL 14+

Operations

OpenTelemetry
Prometheus
Docker

Application Layer

Type-safe OCaml core with REST API for CLI and web dashboard integration

Data Layer

PostgreSQL with MVCC for concurrent operations and graph traversal via CTEs

Operations Layer

Full observability with distributed tracing, metrics, and containerized deployment

Learn More

Why Stategraph Product Roadmap Become a Design Partner

Stop coordinating. Start shipping.

Resource-level locking. Graph-based state. SQL queries on your infra.
Teams work in parallel. No more lock contention.

Get Updates Become a Design Partner

// Zero spam. Just progress updates as we build Stategraph.