Transactions

Stategraph records every state change as a transaction, providing complete audit history and the ability to understand what changed over time.

Overview

Each time Terraform updates state, Stategraph creates a transaction record containing:

Timestamp - When the change occurred
User - Who made the change (from session token)
State - Transaction state (open, completed, aborted)
Changes - What resources were added, modified, or removed
Tags - Custom metadata attached to the transaction

Viewing Transactions

In the UI

Navigate to a state in the Stategraph UI
Click the Timeline or History tab
View the list of transactions with timestamps and summaries

Each transaction shows: - Date and time - User who made the change - Number of resources affected - Transaction state

Via CLI

List transactions for a tenant:

# Get your tenant ID
stategraph user tenants list

Output:

550e8400-e29b-41d4-a716-446655440000    my-org

Then list transactions:

stategraph tx list --tenant 550e8400-e29b-41d4-a716-446655440000

Response:

{
  "results": [
    {
      "id": "455fe705-f27f-4335-9355-dbe8f14098df",
      "created_at": "2024-01-15T10:30:00Z",
      "created_by": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
      "completed_at": "2024-01-15T10:30:05Z",
      "completed_by": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
      "state": "completed",
      "tags": {
        "desc": "Backend update"
      }
    }
  ]
}

Transaction Logs

View detailed logs for a specific transaction:

stategraph tx logs list --tx 455fe705-f27f-4335-9355-dbe8f14098df

Response:

{
  "results": [
    {
      "id": "3f207fb5-f65f-44d8-9e00-52c2d7ee9712",
      "action": "state_set",
      "object_type": "instance",
      "created_at": "2024-01-15T10:30:00Z",
      "state_id": "04c6c195-16d4-43e5-8927-8e97d48a1743",
      "user_id": "f30ed1f9-be44-46a3-9050-03e9561e94f0",
      "data": {
        "address": "null_resource.test",
        "attributes": {"id": "7533051593509317038"},
        "schema_version": 0,
        "resource_address": "null_resource.test"
      }
    }
  ]
}

Transaction States

State	Description
`open`	Transaction in progress
`completed`	Transaction finished successfully
`aborted`	Transaction was rolled back or cancelled

Transaction Tags

Add custom metadata to transactions when creating sessions:

stategraph tx create-with-session \
  --tenant 550e8400-e29b-41d4-a716-446655440000 \
  --tag pipeline=github-actions \
  --tag run_id=12345 \
  --tag branch=main \
  --tag commit=abc123

These tags appear in the transaction record and can be used for: - Linking to CI/CD pipelines - Tracking deployments - Compliance auditing - Debugging issues

Log Entry Types

Object Types

Type	Description
`instance`	Resource instance (e.g., `aws_instance.web`)
`resource`	Resource definition
`provider`	Provider configuration
`output`	Output values
`state_metadata`	State-level metadata
`check_result`	Check block results
`check_result_entry`	Individual check entries

Actions

Action	Description
`state_set`	Resource was added or updated
`state_delete`	Resource was removed

Querying Transaction History

Use MQL to query transaction data:

-- Recent transactions
SELECT * FROM transactions
ORDER BY created_at DESC
LIMIT 10

-- Transactions by user
SELECT * FROM transactions
WHERE created_by = 'user@example.com'

-- Failed transactions
SELECT * FROM transactions
WHERE state = 'aborted'

Use Cases

Audit Compliance

Track who made changes and when:

All state changes are recorded with timestamps
User identity from session token
Complete before/after state available
Export to compliance systems via API

Debugging

When something goes wrong:

Find the transaction that introduced the issue
View the exact changes made
Identify the user and CI/CD pipeline
Compare with previous working state

Rollback Planning

While Stategraph doesn't directly roll back state, transaction history helps plan recovery:

Identify the last known good transaction
View the state at that point
Plan Terraform operations to restore
Apply changes through normal Terraform workflow

Change Tracking

Monitor infrastructure changes:

View transactions over time
Identify patterns (frequent changes, high-risk operations)
Set up alerting on specific change types
Generate reports for stakeholders

CI/CD Integration

Tagging from GitHub Actions

- name: Create Session
  run: |
    TOKEN=$(stategraph tx create-with-session \
      --tenant ${{ secrets.TENANT_ID }} \
      --tag pipeline=github-actions \
      --tag run_id=${{ github.run_id }} \
      --tag repository=${{ github.repository }} \
      --tag branch=${{ github.ref_name }} \
      --tag commit=${{ github.sha }} \
      --tag actor=${{ github.actor }})
    echo "TF_HTTP_PASSWORD=$TOKEN" >> $GITHUB_ENV

Tagging from GitLab CI

create_session:
  script:
    - |
      TOKEN=$(stategraph tx create-with-session \
        --tenant $TENANT_ID \
        --tag pipeline=gitlab-ci \
        --tag job_id=$CI_JOB_ID \
        --tag project=$CI_PROJECT_PATH \
        --tag branch=$CI_COMMIT_REF_NAME \
        --tag commit=$CI_COMMIT_SHA)
      echo "TF_HTTP_PASSWORD=$TOKEN" >> variables.env
  artifacts:
    reports:
      dotenv: variables.env