Skippr Docs

Appearance

How PostgreSQL Shapes the Warehouse Contract ​

July 2026

PostgreSQL is a clear warehouse contract when the team wants ordinary SQL tables for current state and is comfortable with a staging-then-apply CDC pattern behind them.

Short Answer ​

PostgreSQL shapes the warehouse contract around one destination database, one schema, and tables that behave like current-state row-store tables. The destination docs and CDC docs explain the mechanics plainly: Skippr stages incoming data, then applies it with INSERT ... ON CONFLICT guarded by _skippr_order_token TEXT, while tombstone tables protect deletes from stale replays.

That means the main table remains the public contract. If analytics.raw.orders is the target, analysts and models read analytics.raw.orders, not the staging table. The staging layer exists to load efficiently and then apply newer-wins semantics by business key. It is part of the implementation, but the warehouse contract lives on the final table and its tombstone companion.

Why Teams Struggle with This ​

PostgreSQL destinations are easy to underestimate because they look familiar. Teams often stop at connectivity and forget to explain the apply rule that keeps the final table correct under retries, out-of-order events, and deletes.

  • A table that looks like ordinary PostgreSQL still has a CDC freshness rule defined by _skippr_order_token.
  • Environment-variable overrides such as POSTGRES_DATABASE and POSTGRES_SCHEMA can change the landing area if the team does not review them carefully.
  • Treating the staging table as part of the analyst interface blurs the cleaner final-table contract.
  • Missing CREATE, USAGE, or write privileges on the target schema breaks the contract even when the login itself works.

How Skippr Handles It ​

Skippr keeps the PostgreSQL contract readable because the visible config is just database and schema, while credentials stay in POSTGRES_* environment variables. That separation makes it easy to review where data lands without exposing secrets.

The CDC contract is equally concrete. Rows only update when the incoming order token is newer than the one already stored, and tombstones stop older inserts from reviving keys that were deleted later. Downstream SQL can therefore treat the main table as the current-state interface.

  • Targets explicit PostgreSQL database and schema values.
  • Uses a staging-table plus INSERT ... ON CONFLICT apply pattern for CDC.
  • Adds _skippr_order_token and tombstone tables automatically.
  • Keeps the main destination table, not the staging table, as the published warehouse interface.

What the First Useful Version Looks Like ​

The first useful version is one schema such as raw and one CDC-managed table whose business key the team already understands. That makes the newer-wins contract easy to verify with a few deliberate updates and deletes.

If reviewers still describe the destination as "just loading rows into Postgres," bring the apply rule forward. The point of this destination is not only storage. It is correct current state inside ordinary PostgreSQL tables.