timescale/pg-aiguide / skills/schema-exploration
schema-exploration
VerifiedExplore 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.3 KB |
| references/data-values.md | markdown | 5.7 KB |
| references/extensions.md | markdown | 1.8 KB |
| references/foreign-tables.md | markdown | 3.9 KB |
| references/overview.md | markdown | 5.9 KB |
| references/partitioning-and-inheritance.md | markdown | 6.7 KB |
| references/psql.md | markdown | 2.1 KB |
| references/query-authoring.md | markdown | 2.1 KB |
| references/routines.md | markdown | 2.9 KB |
| references/security.md | markdown | 2.5 KB |
| references/tables.md | markdown | 7.7 KB |
| references/triggers.md | markdown | 1.6 KB |
| references/views.md | markdown | 2.4 KB |
references/psql.md
View on GitHub# Running parameterized queries with `psql` (optional)
The reference queries are plain SQL with `$1`, `$2` placeholders. When using PostgreSQL **16+ `psql`**, enter the SQL without its final semicolon, then use `\bind` followed by `\g` to execute it with parameters. `\bind` applies only to the next execution. This is a `psql` convenience, not a requirement for other clients.
When the agent already knows the values, set them with `\set` in a `psql` session or pass them on the command line with `-v` (also spelled `--set`):
```text
\set schema_name postgres_air
\set relation_name flight
```
```sh
psql -X -v schema_name=postgres_air -v relation_name=flight -f query.sql
```
Quote shell arguments appropriately if values contain spaces or shell-special characters. Both methods define the same `psql` variables. Use `\prompt 'Schema: ' schema_name` **only** in an interactive script when a person should supply the value at run time.
Example for the [overview](overview.md) relation-list query (shortened here to illustrate the execution pattern), assuming `schema_name` was set by either method:
```text
select c.relname
from pg_catalog.pg_class c
join pg_catalog.pg_namespace n on n.oid = c.relnamespace
where n.nspname = $1
\bind :schema_name
\g
```
For a query with `$1` and `$2`, use `\bind :schema_name :relation_name`. In `\bind`, use `:variable` (the parameter value), **not** `:'variable'` (which includes SQL literal quotes in the bound value). `psql` 14–15 do **not** support `\bind`: use another client that binds parameters, or adapt the SQL for `psql` variable interpolation by replacing `$1` with `:'schema_name'` and `$2` with `:'relation_name'` (quoted as SQL **values**, not identifiers). For example, with `schema_name` already set:
```text
select n.nspname
from pg_catalog.pg_namespace n
where n.nspname = :'schema_name'
\g
```
Avoid raw `:schema_name` substitution. To construct a separate query against application table *data*, identifier substitution is a different problem: use `psql`'s `:"variable"` identifier quoting or your client's safe identifier-quoting facility. Never insert untrusted names into SQL unquoted.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |