Agent Skills › timescale/pg-aiguide › schema-exploration

schema-exploration

GitHub

用于在回答SQL或数据问题前探索PostgreSQL数据库模式。通过只读查询分析表、视图及权限等元数据，协助理解数据结构与业务含义，支持生成只读查询，不涉及架构设计或迁移。

skills/schema-exploration/SKILL.md timescale/pg-aiguide

Trigger Scenarios

用户询问不熟悉模式的SQL查询需要基于数据事实回答业务概念位置需要了解表、视图、触发器等对象结构

Install

npx skills add timescale/pg-aiguide --skill schema-exploration -g -y

More Options

Use without installing

npx skills use timescale/pg-aiguide@schema-exploration

指定 Agent (Claude Code)

npx skills add timescale/pg-aiguide --skill schema-exploration -a claude-code -g -y

安装 repo 全部 skill

npx skills add timescale/pg-aiguide --all -g -y

预览 repo 内 skill

npx skills add timescale/pg-aiguide --list

SKILL.md

Frontmatter

{
    "name": "schema-exploration",
    "license": "Apache-2.0",
    "metadata": {
        "author": "tigerdata"
    },
    "description": "Explore an existing PostgreSQL database before answering questions about its data or writing SQL. Use this skill whenever a user asks for a query or a data-backed answer against an unfamiliar schema (counts, missing or failed records, recent changes), asks where a business concept lives, or asks how tables, joins, views, routines, triggers, RLS, or extensions work. Find the relevant objects with read-only pg_catalog queries, then request approval before inspecting data-derived statistics or rows. Not a schema-design or migration guide.\n"
}

Explore a PostgreSQL database

Start with the user's question, not a full-database audit unless that is the explicit ask. Use the database connection already available to you; if none is available, ask for access or work from provided schema files. Stay within the database and schemas the user has authorized. Catalog metadata can reveal sensitive names or source code: do not export it unnecessarily.

Workflow

Establish the current database, server version, role, and scope. Use overview for a small inventory. Choose relevant schemas; do not assume public contains the application.
Pick the most promising object(s) and read only the matching drill-down reference: tables, partitioning/inheritance, foreign tables, views, routines, triggers, security/RLS, or extensions. Follow cross-references only when the question requires them.
Corroborate meaning with comments, definitions, keys, and known dependencies. Names are clues, not proof of business meaning. If data-derived values would help, use data-derived values only after obtaining approval for the specific columns and access method. Ask the user when semantics remain ambiguous.
If the user wants SQL, follow query authoring: establish join keys and grain, then validate a vetted read-only query with plain EXPLAIN where authorized. Do not mistake a valid plan for proof of business semantics.
Stop once you can answer. Report the specific schema-qualified objects and evidence, distinguish observations from inferences, and state limitations (permissions, stale statistics, missing dependencies, unknown application logic).

Example finding

Illustrative only; report facts verified in the target database:

Observed: sales.orders has a primary key on order_id and a foreign key from account_id to sales.accounts.account_id.
Inferred: sales.orders likely records one row per order; the keys support this, but do not establish what the business calls an “order.”
Unresolved: The catalog does not show whether canceled orders remain in this table. Confirm with the application owner before assuming they do.

Safety and execution

Prefer structural catalog queries; pg_stats is data-derived and requires approval too. Do not change schema, data, roles, or session-wide settings without authorization. Never call discovered functions or procedures, refresh materialized views, or run EXPLAIN ANALYZE on unknown queries. A function marked STABLE or IMMUTABLE is not a safety guarantee.
If your client supports transactions, use a read-only transaction and a reasonable statement timeout for exploration. Metadata queries are not a license to run full-table counts or unrestricted scans. Ask before sampling data; sample only when necessary, with explicit limits and a clear understanding of table size and access controls.
All reference queries are plain PostgreSQL SQL. Bind $1, $2, etc. as values using your client's API. psql users can follow the optional psql adapter. Never interpolate an untrusted object name as raw SQL; placeholders cannot replace SQL identifiers in data queries.
Queries target PostgreSQL 18. Each version-sensitive section notes alternatives for older majors where applicable. Check server_version_num first. If a query fails due to permissions or version differences, report the limitation instead of guessing.