Skip to content

Commit 8d101f7

Browse files
author
github-actions
committed
Sync docs from infrahub-sync repo
1 parent 6bf4ebb commit 8d101f7

4 files changed

Lines changed: 248 additions & 0 deletions

File tree

‎docs/docs-sync/release-notes/infrahub-sync/release-1_5_6.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Release 1.5.6
3+
---
4+
<table>
5+
<tbody>
6+
<tr>
7+
<th>Release Number</th>
8+
<td>1.5.6</td>
9+
</tr>
10+
<tr>
11+
<th>Release Date</th>
12+
<td>February 18th, 2026</td>
13+
</tr>
14+
<tr>
15+
<th>Tag</th>
16+
<td>[1.5.6](https://github.com/opsmill/infrahub-sync/releases/tag/1.5.6)</td>
17+
</tr>
18+
</tbody>
19+
</table>
20+
21+
## Fixed
22+
23+
- Fixed a race in the Slurp’it adapter by processing interface records sequentially instead of concurrently. Slurp’it sync runs now produce deterministic interface output. ([#115](https://github.com/opsmill/infrahub-sync/pull/115))

‎docs/docs-sync/release-notes/infrahub-sync/release-1_6_0.mdx‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Release 1.6.0
3+
---
4+
<table>
5+
<tbody>
6+
<tr>
7+
<th>Release Number</th>
8+
<td>1.6.0</td>
9+
</tr>
10+
<tr>
11+
<th>Release Date</th>
12+
<td>March 26th, 2026</td>
13+
</tr>
14+
<tr>
15+
<th>Tag</th>
16+
<td>[1.6.0](https://github.com/opsmill/infrahub-sync/releases/tag/1.6.0)</td>
17+
</tr>
18+
</tbody>
19+
</table>
20+
21+
Infrahub Sync 1.6.0 is available.
22+
23+
This release updates CLI, engine, and adapter messages to use Python logging instead of direct terminal printing. It also adds verbosity and progress controls for scheduled runs and interactive troubleshooting.
24+
25+
## Main changes
26+
27+
### Automation-friendly logging
28+
29+
The package CLI, sync engine, and built-in adapters now emit operational messages through Python logging instead of writing directly to the terminal. A run produces one consistent log stream rather than a mix of printed lines and application logs.
30+
31+
The default CLI format remains human-readable. When you embed Infrahub Sync in Python automation, CI, cron, or workflow schedulers, attach your own handlers and formatters to route logs alongside the rest of your pipeline.
32+
33+
### Verbosity and progress controls
34+
35+
The CLI now includes global verbosity controls:
36+
37+
```bash
38+
infrahub-sync --verbosity quiet ...
39+
infrahub-sync --verbosity verbose ...
40+
infrahub-sync -q ...
41+
infrahub-sync -v ...
42+
```
43+
44+
Commands that show progress now support `--show-progress / --no-show-progress`. Progress bars are auto-detected for interactive terminals by default. Use `--no-show-progress` in automation that needs stable, machine-readable output.
45+
46+
## Upgrade notes
47+
48+
- No configuration changes are required.
49+
- Review any scripts that parse human-readable output from `list`, `diff`, `sync`, or `generate`. Operational messages now flow through Python logging.
50+
- Use `--quiet`, `--verbose`, or `--verbosity` to tune log volume for automation and troubleshooting.
51+
- Use `--no-show-progress` in non-interactive environments that require stable log output.
52+
53+
## Full changelog
54+
55+
### Added
56+
57+
- Added global `--verbosity`, `--verbose`/`-v`, and `--quiet`/`-q` controls. ([#117](https://github.com/opsmill/infrahub-sync/pull/117))
58+
- Added `--show-progress / --no-show-progress` to `diff` and `sync`, with terminal auto-detection by default. ([#117](https://github.com/opsmill/infrahub-sync/pull/117))
59+
60+
### Changed
61+
62+
- Replaced direct `print()` and Rich console output with Python logging in the package CLI, sync engine, and built-in adapters. ([#117](https://github.com/opsmill/infrahub-sync/pull/117))
63+
- Updated adapter documentation command examples from Poetry to uv. ([#117](https://github.com/opsmill/infrahub-sync/pull/117))
64+
- Updated development guidance for the uv-based workflow and Python 3.13 support. ([#117](https://github.com/opsmill/infrahub-sync/pull/117))

‎docs/docs-sync/release-notes/infrahub-sync/release-2_0_0.mdx‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: Release 2.0.0
3+
---
4+
<table>
5+
<tbody>
6+
<tr>
7+
<th>Release Number</th>
8+
<td>2.0.0</td>
9+
</tr>
10+
<tr>
11+
<th>Release Date</th>
12+
<td>June 8th, 2026</td>
13+
</tr>
14+
<tr>
15+
<th>Tag</th>
16+
<td>[2.0.0](https://github.com/opsmill/infrahub-sync/releases/tag/2.0.0)</td>
17+
</tr>
18+
</tbody>
19+
</table>
20+
21+
Infrahub Sync 2.0.0 is available.
22+
23+
This release focuses on recurring synchronization at scale. Run large syncs on a schedule, automate them safely, and inspect exactly what changed on every run.
24+
25+
The focus of 2.0 is operational reliability: faster incremental syncs, automatic dependency ordering, built-in safety guardrails, and on-disk run artifacts. Together these make it practical to run synchronization as a recurring part of infrastructure operations.
26+
27+
## Release highlights
28+
29+
- **Schedule recurring syncs without re-reading entire datasets.** Recurring syncs used to re-read the full source and destination on every run. After the first run, `--no-full-extract` lets supported adapters extract only changed records, so large sync jobs stay fast enough to run on a schedule. See [Incremental syncs for large datasets](#incremental-syncs-for-large-datasets).
30+
- **Add and evolve models without maintaining a write order.** Sync ordering used to be maintained manually in `config.yml` and updated on every schema change. It is now derived from your schema mapping automatically. Evolve data models, onboard new systems, and extend integrations without updating sync configuration on every change. See [Write ordering derived from schema mapping](#write-ordering-derived-from-schema-mapping).
31+
- **Run synchronization safely in unattended environments.** Source system outages, permission issues, or incomplete datasets no longer risk deleting valid destination data. Built-in guardrails detect unexpected source drops and stop the run, or skip the affected records, before writing to the destination. Run scheduled syncs in CI/CD pipelines and cron jobs without risking accidental data loss from source anomalies. See [Row count guardrails for unattended runs](#row-count-guardrails-for-unattended-runs).
32+
- **Inspect, audit, and troubleshoot every sync run.** Every `diff` and `sync` used to be discarded after execution. Both are now saved to disk. Review exactly what changed, investigate unexpected results, and build repeatable operational workflows around sync. See [Per-run artifacts for diff and sync](#per-run-artifacts-for-diff-and-sync).
33+
34+
:::note What to expect after upgrading
35+
36+
Your existing sync projects keep working without changes, and most run faster, because loading and writing now happen in parallel by default. Three situations need action:
37+
38+
- If you use a custom adapter that is not thread-safe, pass `--no-concurrent-load`.
39+
- If a sync depends on a specific write order, set an explicit `order` list in `config.yml`.
40+
- `diff` and `sync` now write a cache under `.infrahub-sync-cache/`. In scheduled environments, plan to clean it up so per-run artifacts do not accumulate.
41+
42+
The [upgrade notes](#upgrade-notes) list every default that changed.
43+
44+
:::
45+
46+
## Main changes
47+
48+
### Incremental syncs for large datasets
49+
50+
Large synchronization jobs previously required reading both source and destination systems in full on every run, so execution time grew with the dataset. Infrahub Sync now loads both systems concurrently and, after the first run, can extract only changed records on supported adapters. Run large syncs on a schedule and keep systems in sync as datasets change.
51+
52+
The approved benchmark for [#127](https://github.com/opsmill/infrahub-sync/pull/127) used the `nautobot-v2` demo dataset with interfaces omitted and about 14 object kinds:
53+
54+
| Scenario | Cold | Warm |
55+
| --- | ---: | ---: |
56+
| Baseline, serial, no concurrent load | 463.8s | 154.3s |
57+
| `--parallel` with `--concurrent-load` | 437.5s | 132.3s |
58+
| `--no-full-extract`, cursor-driven warm run | 434.5s | 6.3s |
59+
60+
- Pass `--no-concurrent-load` for custom adapters that are not thread-safe. Concurrent loading is on by default and does not change the sync result.
61+
- Enable incremental extraction with `--no-full-extract` to read only changed records after the first run. The default `--full-extract` re-reads every resource on each run. On supported adapters it uses timestamp cursors: NetBox and Nautobot use `last_updated__gte`, and Infrahub uses `node_metadata__updated_at__after`.
62+
- Infrahub Sync falls back to a full extract when the schema mapping changes, when no prior successful run exists, when an adapter has no cursor for a resource, or when the full-resync cadence is reached.
63+
- Timestamp cursors do not detect deletes. Infrahub Sync forces a full extract every 10 runs by default to reconcile them.
64+
65+
See the [incremental extraction reference](../../reference/incremental-extraction.mdx) for details.
66+
67+
### Write ordering derived from schema mapping
68+
69+
Add and evolve models without updating sync configuration. Synchronization writes objects in dependency order, and that order used to be maintained manually in `config.yml` and updated on every schema change. Infrahub Sync now derives it from the `reference` relationships in your schema mapping.
70+
71+
- Infrahub Sync builds the dependency graph from the `reference` relationships in your `schema_mapping`. It groups object kinds into tiers; objects within a tier have no cross-dependencies.
72+
- When `order` is omitted, Infrahub Sync writes each tier in full before starting the next, so no object is created before what it references. `--parallel` is on by default and writes objects within a tier concurrently.
73+
- Set an explicit `order` list when you need a specific sequence; Infrahub Sync logs a warning and uses it.
74+
75+
### Row count guardrails for unattended runs
76+
77+
Schedule syncs in CI jobs or cron without manually reviewing each run for source anomalies. An outage, a partial restore, or a permissions change can make a source return far fewer records than it holds. Previously, a sync would apply that drop as a deletion. Infrahub Sync now checks record counts against a baseline before writing and stops the run, or skips the affected records, when the drop exceeds the configured threshold.
78+
79+
- Pass `--allow-rowcount-drop` only when the source intentionally shrank. By default, the rowcount check stops a run when a resource drops by more than 50 percent from its last successful baseline.
80+
- Pass `--continue-on-error` to log and skip a record that links to an object it cannot find, such as a peer relationship with a missing identifier, instead of aborting the run. Use it for partial source data, then review the warnings before relying on the result.
81+
82+
### Per-run artifacts for diff and sync
83+
84+
Review, audit, and troubleshoot any run after it completes. `diff` used to print to the terminal and keep nothing. Every `diff` and `sync` now saves its snapshots and change plan to disk, so you can inspect what changed and investigate an unexpected result.
85+
86+
- Find each run's source snapshot, destination snapshot, `plan.parquet`, run metadata, cursors, and schema sub-hash under `.infrahub-sync-cache/<sync-name>/<run-id>/`. The sync-level rowcount baseline is stored at `.infrahub-sync-cache/<sync-name>/last-successful-rowcounts.json`. See the [cache layout reference](../../reference/cache-layout.mdx) for the file structure and plan columns.
87+
- Query the plan with tools such as DuckDB before the next run, or to investigate an unexpected diff:
88+
89+
```bash
90+
uv run infrahub-sync diff --name from-netbox --directory examples/
91+
duckdb -c "SELECT action, resource, source_id FROM read_parquet('.infrahub-sync-cache/from-netbox/<run-id>/plan.parquet') LIMIT 20"
92+
```
93+
94+
- Use `apply` (preview) to replay a cached plan without re-extracting the source. In 2.0.0 it requires destination adapter support for cached-row application, so use `sync` for built-in adapter workflows until that support is available. `apply` refuses to run when the current schema mapping and destination schema shape no longer match the cached schema sub-hash.
95+
96+
### Type checking uses ty in invoke lint
97+
98+
Run `invoke lint` with stricter type checking and no override blocks. The project used mypy with overrides that hid known type errors. Migrating to ty removed those overrides and fixed several latent runtime bugs in the process.
99+
100+
- [ty](https://github.com/astral-sh/ty) runs alongside ruff, pylint, and yamllint in `invoke lint`.
101+
- The migration also fixed latent runtime failures in CLI narrowing, adapter peer resolution, resource-name handling, and Slurp'it conversion return types.
102+
103+
## Upgrade notes
104+
105+
- `order` is now optional when `schema_mapping` contains enough `reference` information to derive the dependency graph. Keep `order` when you need a configured sequence.
106+
- `--parallel`, `--concurrent-load`, and `--full-extract` are enabled by default. Use `--no-concurrent-load` for custom adapters that are not thread-safe.
107+
- Incremental extraction is opt-in with `--no-full-extract`.
108+
- `.infrahub-sync-cache/` is now part of normal operation and is ignored by Git.
109+
- Review automation that parses command output. The new cache workflow adds run identifiers and cache paths to successful `diff` and `sync` runs.
110+
- Review retention and cleanup for `.infrahub-sync-cache/` in scheduled environments, because recurring runs now persist snapshots and plans.
111+
112+
## Full changelog
113+
114+
### Added
115+
116+
- Added automatic sync ordering from `schema_mapping` reference relationships, making `order` optional for configurations with enough dependency information. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
117+
- Added tier-by-tier sync execution with `--parallel` enabled by default when `order` is omitted. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
118+
- Added per-run cache artifacts under `.infrahub-sync-cache/<sync-name>/<run-id>/`, including source and destination snapshots, run metadata, cursors, and schema-sub-hash data. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
119+
- Added sync-level rowcount baselines under `.infrahub-sync-cache/<sync-name>/last-successful-rowcounts.json`. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
120+
- Added Parquet diff plans for `diff` and `sync`, so run output can be inspected with external tools. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
121+
- Added the `infrahub-sync apply` command (preview) as the foundation for replaying cached plans with destination adapters that support cached-row application. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
122+
- Added cursor-based incremental extraction for NetBox, Nautobot, and Infrahub, enabled with `--no-full-extract`. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
123+
- Added rowcount guardrails that stop `sync` when a resource count drops by more than 50 percent from the previous successful baseline. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
124+
- Added `--continue-on-error` to skip peer relationships with missing identifier values while logging warnings. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
125+
126+
### Changed
127+
128+
- Enabled concurrent source and destination loading by default for `diff` and `sync`, with `--no-concurrent-load` available for custom adapters that are not thread-safe. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
129+
- Enabled `--parallel` and `--full-extract` by default for `sync`. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
130+
- Updated example configurations to omit `order` by default and show how to opt back into a manual sequence. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
131+
- Replaced mypy with ty in the development and CI linting workflow. ([#126](https://github.com/opsmill/infrahub-sync/pull/126))
132+
133+
### Fixed
134+
135+
- Improved peer identifier handling so missing peer identifier values produce clearer errors, or warnings when `--continue-on-error` is used. ([#127](https://github.com/opsmill/infrahub-sync/pull/127))
136+
- Fixed several type-checker-discovered runtime failure paths in CLI narrowing, resource-name handling, Infrahub peer resolution, and Slurp'it conversion return values. ([#126](https://github.com/opsmill/infrahub-sync/pull/126))

‎docs/sidebars-sync.ts‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,31 @@ const sidebars: SidebarsConfig = {
5353
'reference/incremental-extraction',
5454
],
5555
},
56+
{
57+
type: 'category',
58+
label: 'Release Notes',
59+
collapsible: true,
60+
collapsed: true,
61+
link: {
62+
type: 'generated-index',
63+
slug: 'release-notes',
64+
},
65+
items: [
66+
{
67+
type: 'category',
68+
label: 'Infrahub Sync',
69+
link: {
70+
type: 'generated-index',
71+
slug: 'release-notes/infrahub-sync',
72+
},
73+
items: [
74+
'release-notes/infrahub-sync/release-2_0_0',
75+
'release-notes/infrahub-sync/release-1_6_0',
76+
'release-notes/infrahub-sync/release-1_5_6',
77+
],
78+
},
79+
],
80+
},
5681
'contributing',
5782
]
5883
};

0 commit comments

Comments
 (0)