Skip to main content
Groundhog 0.2.0 removes the embedded DuckDB warehouse and its product surfaces. Groundhog now stores and serves the durable event log. Applications build their own derived views from replay or follow. This release changes the binary and Python SDK to version 0.2.0. The durable log schema remains version 1.

​
Removed CLI commands

The binary no longer accepts:
  • groundhog project
  • groundhog rebuild
Use replay or follow to build and rebuild derived state in an application-owned system.

​
Removed HTTP routes

The service no longer provides:
  • POST /v1/query
  • GET /v1/catalog
Both paths now return HTTP 404. Use GET /v1/events for finite replay. Use GET /v1/events?follow=true for continuous delivery. Use GET /v1/streams for authoritative stream enumeration. The HTTP API remains under /v1 because Groundhog has not reached version 1.0.

​
Removed configuration

Groundhog no longer accepts the [query] section. Remove the complete section before you start Groundhog 0.2. The binary returns this migration error:
No replacement warehouse configuration exists.

​
Python SDK 0.2.0

The Python SDK removes these interfaces:
  • Ground.query()
  • Ground.catalog()
  • QueryResult
  • CatalogResult
  • SnapshotReceipt
  • QueryError
The SDK adds Ground.streams() with typed Stream and StreamPage values. Unix-socket and HTTPS transports provide ingest, finite replay, and stream enumeration. The SDK does not provide a follow iterator in version 0.2.0. Use the HTTP API directly when a Python application needs continuous follow.

​
Storage behavior

Groundhog no longer creates, opens, or requires a DuckDB warehouse. It removes the DuckDB runtime and build dependencies. Parquet remains the immutable log-segment format. The durable event log format does not change. Groundhog 0.2 ignores these old files:
The runtime never deletes them automatically. Operators can delete them after the 0.2 upgrade passes verification, backup, and application checks.

​
Retained product surface

Groundhog retains:
  • atomic, idempotent JSON batch ingest
  • durable append-only storage
  • finite replay
  • continuous follow
  • authoritative stream enumeration
  • stream preconditions
  • source retirement and successor lineage
  • immutable Parquet log segments
  • integrity verification and recovery
  • a Unix-socket HTTP service

​
Upgrade procedure

  1. Keep the Groundhog 0.1 binary and a coherent backup.
  2. Run groundhog verify --chain with Groundhog 0.1.
  3. Stop the Groundhog 0.1 writer cleanly.
  4. Remove the [query] section from groundhog.toml.
  5. Install the Groundhog 0.2 binary.
  6. Start the deployment with the same version 1 log.
  7. Probe GET /v1/streams and a known finite replay request.
  8. Run groundhog verify --chain with Groundhog 0.2.
  9. Upgrade groundhog-sdk clients to 0.2.0.
  10. Replace SDK query and catalog calls with application-owned derived views.
  11. Confirm that each consumer can continue or rebuild from replay.
  12. Delete old warehouse files only after all upgrade checks pass.
Do not edit log files or storage metadata during the upgrade.

​
See also

Getting started, HTTP API, Python SDK, Deployment operations