# Motherduck Duckdb SQL

> DuckDB SQL reference for MotherDuck. Use when you need exact DuckDB syntax, function behavior, supported MotherDuck SQL features, or to resolve whether PostgreSQL-oriented SQL will fail on MotherDuck.

- Skill: `majiayu000/motherduck-duckdb-sql-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/motherduck-duckdb-sql-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/motherduck-duckdb-sql-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- License: MIT
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/majiayu000/motherduck-duckdb-sql-2

---


# DuckDB SQL Reference for MotherDuck

Use this skill when you need exact DuckDB syntax, function behavior, or a quick sanity check that a statement will actually work on MotherDuck.

## Source Of Truth

- Prefer current DuckDB SQL docs for language features and function semantics.
- Use current MotherDuck SQL docs for MotherDuck-only commands such as shares, secrets, snapshots, and Dive operations.
- Check MotherDuck version-lifecycle docs for newly released DuckDB features before promising they are available in MotherDuck.
- Treat upstream DuckDB 1.5.x docs as ahead of MotherDuck unless the current MotherDuck lifecycle docs confirm the same DuckDB version and feature surface.
- Distinguish upstream DuckDB current-version docs from MotherDuck-supported DuckDB versions; MotherDuck can lag upstream current for client compatibility and SQL feature support.
- If the connection path matters, verify behavior against the current Postgres-endpoint docs before promising server-mode support.

## Default Posture

- Write DuckDB SQL, not PostgreSQL SQL, even when the client connects through the Postgres endpoint.
- Use fully qualified `"database"."schema"."table"` names once more than one database or share is in scope.
- Prefer DuckDB-native constructs when they simplify the query: `GROUP BY ALL`, `QUALIFY`, `UNION BY NAME`, `arg_max`, `EXCLUDE`, and `REPLACE`.
- When porting SQL from another engine, translate functions, date arithmetic, identifier quoting, and type casts explicitly instead of assuming compatibility.
- For upstream DuckDB 1.5 features such as `VARIANT`, native `GEOMETRY`, `date_trunc` return-type changes, ODBC scanner behavior, or lakehouse-format changes, verify current MotherDuck support before adding them to production guidance.
- Check whether the statement depends on local files, extension install/load, temporary-table behavior, or other client-only features before claiming it will work in MotherDuck.
- Treat snapshot, restore, and `UNDROP DATABASE` statements as operational SQL with plan-specific retention behavior, not ordinary analytical syntax.
- Treat MotherDuck SQL as an additional surface on top of DuckDB SQL, not a replacement for it.

## Workflow

1. Confirm the connection path and whether the question is about syntax, feature support, or a specific error.
2. Write or repair the statement in DuckDB SQL first.
3. Verify any MotherDuck-only command or server-mode limitation against the current docs.
4. If the user needs exact syntax or function details, open `references/SYNTAX_REFERENCE.md`.

## Open Next

- `references/SYNTAX_REFERENCE.md` for DuckDB data types, friendly SQL features, functions, complex types, and common MotherDuck-specific gotchas

## Related Skills

- `motherduck-query` for writing and validating analytical SQL against live MotherDuck data
- `motherduck-connect` when syntax support depends on PG endpoint versus native DuckDB behavior
- `motherduck-explore` when the problem is really missing schema context rather than missing syntax knowledge