Skippr Docs

Appearance

How to Explain PostgreSQL Tables to Analysts ​

July 2026

Analysts should read Skippr Postgres tables as regular SQL tables in the target schema that represent current state after each load completes.

Short Answer ​

Explain PostgreSQL destination tables as regular SQL tables in the target schema that represent current state after the latest successful load. Skippr uses a staging-table plus merge pattern for CDC, so a table such as raw.orders should be treated as the latest raw order row per business key, not as an append-only queue of upstream mutations.

That is the useful mental model for analysts. They can join and filter these tables with normal PostgreSQL SQL. If an order was updated twice today, the ordinary raw table should show the newest version once the staging merge finishes. The _skippr_order_token column is there so Skippr can reject stale updates, not so analysts can measure business time.

Why Teams Struggle with This ​

Postgres feels familiar enough that teams often skip explaining table semantics. Familiar SQL does not remove the need to say whether a raw table is current state, history, or something in between.

  • The target schema such as raw or public tells analysts where landing tables live, but not whether those tables are historical unless engineering explains it.
  • A CDC-managed Postgres table is usually current state per key, not a mutation ledger.
  • The _skippr_order_token column and tombstone tables are correctness machinery, not the core reporting surface.
  • Environment variables like POSTGRES_HOST and POSTGRES_USER affect access, but they do not change the meaning of one row in the table.

How Skippr Handles It ​

Skippr makes this easy to communicate because the destination surface is compact: database and schema in config, credentials in environment variables, and straightforward relational tables on the warehouse side. Analysts do not have to learn a special query model to start using the landing layer.

The CDC semantics also map well to analyst expectations. Staging-table merge behavior plus order-token guards means the raw table can stay a dependable current-state input into downstream dbt models or hand-written SQL.

  • Targets a named PostgreSQL database and schema.
  • Uses staging-table merge semantics for exactly-once final-state CDC.
  • Automatically adds _skippr_order_token columns for stale-write protection.
  • Creates tombstone tables so deleted keys are not mistakenly restored by replayed events.

What the First Useful Version Looks Like ​

The first useful explanation is one table and one key: this table shows the current row for that key, and the extra Skippr column is for ingestion safety. Most analyst confusion disappears once that sentence is explicit.

If someone needs history, keep the answer simple: this raw Postgres table is for current state, and historical analysis belongs in a separate model built on purpose.