Upgrade the ClickHouse behind your self-hosted SigNoz to 25.12.5 before a newer SigNoz release starts requiring it. This is a transitive upgrade: a future signoz-otel-collector release will not run on ClickHouse older than 25.12.5, and a routine SigNoz update will eventually pull it. Doing this ClickHouse upgrade on its own, ahead of that release, keeps the move controlled. It is a significant version jump, so review this guide and back up before upgrading to avoid issues with your existing data. This guide covers both Foundry and the Helm chart.
A future signoz-otel-collector release stores trace attributes as a ClickHouse JSON column (otel-collector#833), and its schema migration uses settings that exist only in 25.12.5. With Foundry, forge and cast block the mismatch.
Upgrade
Step 1: Back up your data
ClickHouse upgrades its on-disk format in place on first start, and downgrades are not guaranteed. Snapshot your data before upgrading: the Kubernetes PersistentVolumes, the Docker volume, or /var/lib/clickhouse (binary). If the upgrade goes wrong, restore that snapshot and roll back to your previous version.
Step 2: Upgrade ClickHouse and SigNoz
Upgrade foundryctl first. It brings the v0.131.0 defaults (ClickHouse 25.12.5) and the compatibility check that blocks an incompatible pairing once the new collector lands:
curl -fsSL https://signoz.io/foundry.sh | bash
Then re-forge and re-apply your existing casting.yaml:
foundryctl cast -f casting.yaml
Or run foundryctl forge -f casting.yaml to render the deployment files into pours/, then apply them with your platform's own command. That apply step varies by mode and flavor (docker compose up -d, kubectl apply, helm upgrade, and so on).
If your casting.yaml pins image versions, the new defaults will not override them (your config wins), so bump the pins yourself, at minimum ClickHouse to 25.12.5. Otherwise the old version sticks and forge flags the mismatch:
spec:
telemetrystore:
spec:
image: clickhouse/clickhouse-server:25.12.5
telemetrykeeper: # only if you run ClickHouse Keeper
spec:
image: clickhouse/clickhouse-keeper:25.12.5
Update the chart and upgrade. The v0.131.0 chart sets ClickHouse 25.12.5:
helm repo update
helm -n signoz upgrade signoz signoz/signoz
helm upgrade takes the newest chart; add --version 0.131.0 to pin the v0.131.0 chart.
To pin ClickHouse explicitly, override the tag:
helm -n signoz upgrade signoz signoz/signoz --set clickhouse.image.tag=25.12.5
Step 3: Verify the upgrade
- Pods and containers are healthy (
kubectl get pods -n signoz,docker compose ps, orsystemctl status 'signoz-*'). - ClickHouse is on the new version:
SELECT version(); - The
signoz-telemetrystore-migratorjob finished (no failed or restarting migrator pods). - Telemetry is flowing: open the Meter Explorer and confirm ingestion is recording for logs, traces, and metrics.
- SigNoz reports v0.131.0 under Settings.
Troubleshooting
Migrator fails with "Unknown setting 'object_serialization_version'"
If the new collector runs before ClickHouse is on 25.12.5, the signoz-otel-collector pod keeps running, but the signoz-telemetrystore-migrator job fails (Init:Error / CrashLoopBackOff on its sync step):
Code: 115. DB::Exception: Unknown setting 'object_serialization_version'. (UNKNOWN_SETTING)
The migration sets ClickHouse settings (object_serialization_version, object_shared_data_serialization_version) that exist only in 25.12.5. Upgrade ClickHouse to 25.12.5; the migrator completes on its next run.
