Integration

The integration command runs integration tests on Trilogy scripts with real database connections. It validates that all datasources are configured properly, but does not execute the actual queries.

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.

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 that all datasources exist and are accessible
• Does NOT execute any data-modifying statements

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

• 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