Table: tfe_run - Query Terraform Cloud Runs using SQL

A Run in Terraform Cloud represents a single run of Terraform in a workspace. It includes details about the run's status, timestamps, and associated resources such as workspace, configuration version, and plan. Runs are a key component of Terraform Cloud's collaboration features, as they allow users to propose, review, and approve infrastructure changes.

Table Usage Guide

The tfe_run table provides insights into Runs within Terraform Cloud. As a DevOps engineer, explore run-specific details through this table, including status, timestamps, and associated resources. Utilize it to understand the state of infrastructure changes, the progress of runs, and the details of associated resources.

Important Notes

You must specify the workspace_id in the where clause to query this table.

Examples

List runs

Uncover the details of all the runs associated with a specific workspace. This can be useful when you need to monitor or review the progress and status of all tasks within that workspace.

select
  *
from
  tfe_run
where
  workspace_id = 'ws-ocKJU1ouZNZWZoUx';

select
  *
from
  tfe_run
where
  workspace_id = 'ws-ocKJU1ouZNZWZoUx';

Runs that errored in the last 24 hrs

Identify instances where workflow runs have encountered errors in the past day. This is useful for troubleshooting recent issues and understanding the frequency of errors in your workflows.

select
  id,
  created_at,
  status
from
  tfe_run
where
  workspace_id = 'ws-ocKJU1ouZNZWZoUx'
  and status = 'errored'
  and created_at > current_timestamp - interval '24 hrs';

select
  id,
  created_at,
  status
from
  tfe_run
where
  workspace_id = 'ws-ocKJU1ouZNZWZoUx'
  and status = 'errored'
  and created_at > datetime('now', '-24 hours');

Which users created the most runs?

Discover the users who have initiated the most operations within a specific workspace. This can help identify the most active users and understand usage patterns.

select
  created_by ->> 'Username' as username,
  count(*)
from
  tfe_run
where
  workspace_id = 'ws-ocKJU1ouZNZWZoUx'
group by
  username
order by
  count desc;

select
  json_extract(created_by, '$.Username') as username,
  count(*)
from
  tfe_run
where
  workspace_id = 'ws-ocKJU1ouZNZWZoUx'
group by
  username
order by
  count(*) desc;

Schema for tfe_run

Name	Type	Operators	Description
_ctx	jsonb		Steampipe context in JSON form, e.g. connection_name.
actions	jsonb		Actions for the run.
apply	jsonb		Apply phase information from the run.
configuration_version	jsonb		Configuration record used in the run.
cost_estimate	jsonb		Cost estimate for the resources in this run.
created_at	timestamp with time zone		Time when the run was created.
created_by	jsonb		Basic information about the user.
force_cancel_available_at	timestamp with time zone		Time when force cancel will be available for the run.
has_changes	boolean		True if the run has changes.
id	text	=	ID of the run.
is_destroy	boolean		Specifies if this plan is a destroy plan, which will destroy all provisioned resources.
message	text		Message associated with the run.
permissions	jsonb		Permissions for the run.
plan	jsonb		Plan phase information from the run.
policy_checks	jsonb		Policy check information from the run.
position_in_queue	bigint		Position in the queue for this run.
refresh	boolean		Whether or not to refresh the state before a plan.
refresh_only	boolean		Whether this run should use the refresh-only plan mode, which will refresh the state without modifying any resources.
replace_addrs	jsonb		Optional list of resource addresses to be passed to the -replace flag.
source	text		Source of the run request, e.g. tfe-api.
status	text		Status of the run, e.g. pending, planning, applying, applied, errored, etc.
status_timestamps	jsonb		Timestamps for status changes in the run.
target_addrs	jsonb		Optional list of resource addresses to be passed to the -target flag.
workspace_id	text	=	Workspace ID that contains the run.

Export

This table is available as a standalone Exporter CLI. Steampipe exporters are stand-alone binaries that allow you to extract data using Steampipe plugins without a database.

You can download the tarball for your platform from the Releases page, but it is simplest to install them with the steampipe_export_installer.sh script:

/bin/sh -c "$(curl -fsSL https://steampipe.io/install/export.sh)" -- tfe

You can pass the configuration to the command with the --config argument:

steampipe_export_tfe --config '<your_config>' tfe_run