Skippr Docs

Appearance

Common MotherDuck Warehouse Setup Mistakes ​

May 2026

MotherDuck warehouse setup tends to fail when teams treat the token as a blanket grant instead of checking the exact database and schema boundary.

Short Answer ​

The most common MotherDuck warehouse mistakes are using a token that can authenticate but not write to the chosen database and schema, assuming main is always the right schema, and glossing over how CDC upserts and deletes are actually reconciled. Skippr expects a motherduck_token, a database, and a schema, then applies CDC with order-token guards and tombstone tables for final-state correctness.

That means the easy-looking setup can still fail late. A token may open the connection but lack permission to create or modify objects in the database your project targets. Another common issue is copying a shared example that uses schema main even though the team intended a dedicated raw schema for landed tables and wants cleaner separation for downstream models.

Why Teams Struggle with This ​

MotherDuck setup is simpler than some cloud warehouses, but the simplicity can hide the real contract. The token still needs write access, the runner still needs outbound network access, and CDC still depends on explicit _skippr_order_token and tombstone rules rather than ad hoc overwrite logic.

  • A valid MotherDuck token is not sufficient if it cannot create or write objects in the selected database and schema.
  • Teams often reuse the default schema without deciding where raw landing tables should actually live.
  • CDC expectations get muddled when people assume deletes and replays are handled by replacement alone instead of by tombstone-aware final-state logic.
  • Network access is still part of setup because the runner must reach MotherDuck reliably during loads.

How Skippr Handles It ​

Skippr keeps the MotherDuck destination surface compact and readable: token, database, and schema. That is useful because warehouse reviews can focus on one concrete question: does this token have the exact access we expect in the exact target location?

For CDC, Skippr also preserves the semantics in the open. The destination gets _skippr_order_token plus tombstone tables, and upserts are guarded by token ordering so replayed older rows do not replace newer state.

  • Direct MotherDuck destination configuration through token, database, and schema.
  • Environment-variable token interpolation rather than committed secrets.
  • CDC reconciliation with token-guarded replacement behavior and tombstone tracking.
  • A warehouse setup that stays inspectable without extra orchestration layers.

What the First Useful Version Looks Like ​

The first useful version is one dedicated database, one clearly chosen raw schema, and one token whose write scope has been tested there.

If CDC is part of the plan, pick a target table and review how an older replayed row would lose to a newer token before expanding the pipeline surface.