Integration

The integration command runs integration tests on Trilogy scripts with real database connections. It validates that all datasources are configured properly, including data-level validation queries. It does not run ordinary script queries as a workload.

Usage

trilogy integration <input> [dialect] [options] [conn_args...]

Arguments

Argument	Description
input	Path to a Trilogy script or directory.
dialect	Database dialect. Optional - falls back to engine.dialect in trilogy.toml.
conn_args	Connection arguments, as key value pairs or key=value tokens.

Options

Option	Description
--param key=value	Environment parameters. Repeatable.
-p, --parallelism INTEGER	Maximum parallel workers for directory execution.
--config PATH	Path to a trilogy.toml configuration file.
-e, --env TEXT	Set env vars as KEY=VALUE, or pass an env file path.
--refresh-derived [failed]	Attempt a targeted derived datasource refresh when integration fails, then retry.
--skip-type [datasources/concepts/agent]	Skip a test type. Repeatable.
--include-type [datasources/concepts/agent]	Include a test type beyond the defaults. Agent checks are opt-in. Repeatable.
--report, --no-report	Enable/disable agent validation reports under .trilogy/validate_runs/; enabled by default.

Full Examples

# Integration test against Postgres
trilogy integration tests/ postgres host=localhost database=testdb username=app password=secret

# Integration test single file
trilogy integration query.preql duckdb

# Integration test with parallelism
trilogy integration . snowflake -p 4 account=myaccount username=app password=secret

# Integration test with config
trilogy integration scripts/ --config trilogy.toml

# Self-heal stale derived assets and retry once
trilogy integration . duckdb --refresh-derived failed

What It Does

• Parses the script(s)
• Connects to the specified database
• Validates datasource bindings, grain, declared value domains, and completeness claims
• Evaluates absolute datasource assertions on published data; prior-dependent assertions are reported as not run
• Does not rebuild assets unless --refresh-derived failed is requested

With --refresh-derived failed, a failing run is followed by a targeted refresh of the derived datasources behind the failures, then retried. This turns "the derived table is stale" from a failure into a self-correcting step.

Notes

Datasource and concept checks run by default. --include-type agent adds validate ... matches questions against the live data, using the configured agent provider and its tokens.

• Use this after trilogy run to set up new tables, then validate the setup
• Validates schema compatibility between your models and the actual database
• Useful for CI/CD pipelines to verify deployments