Docs

amfelt sync

Execute a pipeline job defined in amfelt.yaml.
Usage Examples Flags Global flags

Executes the pipeline job identified by --job. The job definition in amfelt.yaml names the source and target, sets the default layer and write mode, and selects which objects to move using glob include/exclude patterns resolved against the source’s data contract. Selected objects can override the history mode, write mode, table type, cursor, and column handling individually.

Use --dry-run to validate the job configuration and print the resolved job summary without executing any data movement.

Use --run-report to save the engine’s run metadata and structured report as JSON, including run and task IDs, bytes, row counts, and history counters. The file uses schema version 1 and permissions 0600. Completed failed runs also save their available evidence; setup failures leave an existing file unchanged. A write failure fails the command. This flag cannot be combined with --dry-run. It can be used alongside --target-contract with separate destinations.

Use --target-contract to write a data contract (ODCS) of what the warehouse holds once the run succeeds: every table and view in the job’s layer schemas, read back from the warehouse itself, with the layer each one belongs to, and for each table and view this job creates, the source object it came from. The staging tables and current-record views this job creates can also carry primary keys and foreign keys from the source’s data contract. An object gets a key only if it holds every column of the key. A foreign key links these objects only within one layer, and only if the object it points to has the key it references; the object it starts from needs no key of its own. In the history and bridge layers, a foreign key links two objects only if the job gives both the same history mode. In the bridge layer, a key or foreign key is included only when the views pass every column it involves through unchanged, with no transform or rename. A layer built from a SQL template you have customized gets no keys or foreign keys, and neither does any layer built on top of it. The file is replaced only when the run succeeds and the warehouse could be read back; otherwise the command fails and the file is left as it was.

Usage  

amfelt sync [flags]

Examples  

amfelt sync --job sync-dwh
Validates and executes the 'sync-dwh' job defined in amfelt.yaml.

amfelt sync --job sync-dwh --dry-run
Prints the resolved job configuration without executing anything.

Flags  

FlagTypeDefaultDescription
--dry-runboolfalsegenerate DDL without executing against the database
--forceboolfalseignore warnings and errors
--jobstring—name of the job to execute (required)
--pathstringamfelt.yamlpath of the Amfelt project file
--run-reportstring—write the engine run metadata and report as JSON to this file, including failed runs
--source-urlstring—connection URL for the source database plugin (e.g. postgres://user:pass@host:5432/db)
--strictbooltrueuse strict validation
--target-contractstring—after a successful run, write a data contract (ODCS) of what the warehouse holds to this file: every table and view in the job’s layer schemas with its layer, and for each one this job creates, the source object it came from and, where they apply, keys and foreign keys from the source’s data contract

Global flags  

FlagTypeDefaultDescription
--amfelt-dirstring.amfeltdirectory for workspace files (such as plugins); does not move agent identity (controlled by AMFELT_DIR)
--configstring—directory or filename of the application configuration
-f, --formatstringdefaultlog format to use; either default, pretty, or json
-l, --levelstringinfominimum log level to display; either error, warn, info, or debug
-v, --verboseboolfalsetrigger to use verbose logging

Generated from amfelt v5.6.3.

Last updated on November 1, 2026

On this page