docs(dump): document --qualify-schema flag (#321)

[tianzhou]

Documents the dump --qualify-schema flag shipped in #492 (issue #321).

Changes (docs-only, docs/cli/dump.mdx)

• Output Options: new --qualify-schema ParamField (default false), linking to the detail section.
• Schema Qualification → new "Forced Qualification" subsection:
  • Example showing fully qualified schema.object output.
  • The two motivations from Support dumping schema without qualifiers shortening #321: reserved-word / ambiguous identifiers (→ Respect quoted identifiers in plpgsql functions when dumping schema #320) and simpler static analysis.
  • Coverage scope, accurately worded: object names and structural references where PostgreSQL syntax permits — table/view/sequence/type/function/procedure/policy names; index targets and comments; and ON/REFERENCES/OWNED BY/COMMENT targets. A note clarifies that CREATE INDEX names stay unqualified (the index lives in its table's schema).
  • A <Note> documenting the same-schema type-reference limitation, tracked in Inspector/IR should preserve schema identity for type references (enable --qualify-schema for types) #493.
• Overview: mention forced qualification alongside smart qualification.

Notes

• Examples follow the page's existing stylized form (inline REFERENCES, no IF NOT EXISTS) to parallel the smart-qualification example directly above.
• Reviewed locally by @PG-Codex (wording-accuracy pass on the index-name coverage).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Documents the existing pgschema dump --qualify-schema flag (introduced in #492) in the dump CLI docs, explaining when and why to use forced schema qualification and clarifying current limitations.

Changes:

• Adds --qualify-schema to the Output Options parameter list with default/behavior and links to details.
• Expands Schema Qualification docs with a new Forced Qualification subsection, including examples, motivations, and a limitation note linking to #493.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Greptile Summary

This PR is a documentation-only change that adds a reference entry and a usage section for the --qualify-schema flag introduced in #492. The new content is accurate, well-structured, and consistent with the rest of the page.

• A new --qualify-schema ParamField is added to the Output Options section, explaining the flag's purpose and linking to the detail section.
• A new Forced Qualification subsection under Schema Qualification provides a working SQL example, two motivating use-cases (reserved-word identifiers and static analysis), an explicit coverage scope, and a <Note> documenting the current type-reference limitation tracked in Inspector/IR should preserve schema identity for type references (enable --qualify-schema for types) #493.

Confidence Score: 4/5

Documentation-only change with no code modifications; safe to merge after addressing the minor wording nit.

The added content is accurate and well-organized. The only issues are a slightly imprecise phrase in the ParamField description ("wherever PostgreSQL syntax permits" doesn't match the real reason type references stay unqualified) and a missing trailing newline — both cosmetic. There is no risk of behavioral regression from a docs change.

docs/cli/dump.mdx — the ParamField description wording and missing trailing newline are worth fixing before merge.

Important Files Changed

Filename	Overview
docs/cli/dump.mdx	Adds documentation for --qualify-schema flag: new ParamField in Output Options, a Forced Qualification subsection with SQL example and usage bullets, and a Note about the type-reference limitation. One minor wording nuance in the ParamField description and a missing trailing newline.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[pgschema dump] --> B{--qualify-schema flag?}
    B -- No --> C[Smart Qualification]
    B -- Yes --> D[Forced Qualification]

    C --> C1[Objects in dumped schema: no qualifier]
    C --> C2[Objects in other schemas: fully qualified]

    D --> D1[Table / view / sequence / type names: schema.object]
    D --> D2[REFERENCES targets: schema.object]
    D --> D3[OWNED BY / COMMENT / ON targets: schema.object]
    D --> D4[Index target table: schema.object]
    D --> D5[Index name: unqualified - index lives in table's schema]
    D --> D6[Comment headers: show schema instead of '-']
    D --> D7[Type references in columns/params: NOT qualified - limitation tracked in #493]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[pgschema dump] --> B{--qualify-schema flag?}
    B -- No --> C[Smart Qualification]
    B -- Yes --> D[Forced Qualification]

    C --> C1[Objects in dumped schema: no qualifier]
    C --> C2[Objects in other schemas: fully qualified]

    D --> D1[Table / view / sequence / type names: schema.object]
    D --> D2[REFERENCES targets: schema.object]
    D --> D3[OWNED BY / COMMENT / ON targets: schema.object]
    D --> D4[Index target table: schema.object]
    D --> D5[Index name: unqualified - index lives in table's schema]
    D --> D6[Comment headers: show schema instead of '-']
    D --> D7[Type references in columns/params: NOT qualified - limitation tracked in #493]

Loading

_{Reviews (1): Last reviewed commit: "docs(dump): correct --qualify-schema cov..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.