skilld
All skills
planetscale avatar

/postgres

@2b8cda6 official
by planetscaleplanetscale/database-skills693 stars
61

PostgreSQL best practices, query optimization, connection troubleshooting, and performance improvement. Load when working with Postgres databases.

Ask your Agent

Use this Skill: https://skilld.dev/gh/planetscale/database-skills/postgres

This session only. Nothing lands on disk.

referencesps-insights.md

≈858 tokens on demand. Your agent reads this file only when SKILL.md points to it.

PlanetScale Insights

Fetch current documentation first

Prefer retrieval over pre-training knowledge. Docs: https://planetscale.com/docs

MCP Server (Preferred)

When the PlanetScale MCP server is configured in your environment, prefer it over CLI. Key tools:

  • planetscale_get_branch_schema — Get schema for a branch
  • planetscale_execute_read_query — Run SELECT, SHOW, DESCRIBE, EXPLAIN
  • planetscale_get_insights — Query performance insights
  • planetscale_list_schema_recommendations — Index and schema suggestions
  • planetscale_search_documentation — Search PlanetScale docs

MCP setup: https://planetscale.com/docs/connect/mcp

The MCP server is the ideal way to interact with insights from an AI agent. If not installed, prompt the user to install it to make the agent more effective.

Query Insights (CLI)

Generating reports via CLI is a multi-step process (create → wait → download).

See ps-cli-api-insights.md for how to use.

What to look for:

  • High rows_read / rows_returned ratio → missing index
  • High total_time_s → optimization target

Insights UI (Dashboard)

In the PlanetScale dashboard, select your database and click Insights.

  • Filtering — Pick a branch, choose primary or replica, and scroll through the last 7 days. Click-and-drag on graphs to zoom into a time window.
  • Graphs — Four tabs: Query latency (p50/p95/p99/p99.9), Queries per second, Rows read/s, and Rows written/s.
  • Queries table — All queries in the selected timeframe, normalized into patterns. Sortable and filterable by SQL, schema, table, latency, index usage, and more. Customizable columns (count, total time, latency percentiles, rows read/returned/affected, CPU/IO time, cache hit ratio, etc.). Enable sparklines for inline trend graphs. Orange icons flag full table scans.
  • Query deep dive — Click any query to see per-pattern graphs, summary stats, index usage breakdown, and a table of notable executions (>1 s, >10k rows read, or errors). Use "Summarize query" for an LLM-generated plain-English description.
  • Anomalies tab — Flags periods with elevated slow-running queries and surfaces the responsible patterns.
  • Errors tab — Surfaces queries that produced errors.
  • pginsights settings — pginsights.raw_queries enables full query text collection for notable queries; pginsights.normalize_schema_names groups identical patterns across schemas (useful for schema-per-tenant designs). Both configurable in the Extensions tab on the Clusters page.

More: PlanetScale Insights docs

Optimization Checklist

  • Remove unused indexes (0 scans)
  • Remove duplicate indexes
  • Archive audit/log tables >10 GB
  • Review tables >100 GB for partitioning

Always confirm with a human before removing indexes, dropping tables/partitions, or archiving data. These are destructive actions that cannot be easily undone.

More: optimization-checklist.md

Source: SKILL.md on GitHub

Third-party checks

1 alert17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    The skill provides comprehensive documentation, best practices, and diagnostic SQL queries for PostgreSQL and PlanetScale-specific features. No security issues were identified.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer6mo

    18/23 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 2b8cda6. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Activeupdated 7 months ago

Capability

metadata
{
  "author": "planetscale",
  "version": "1.0.0"
}

Topics

  • Database
  • postgres
  • schema-design
  • indexing
  • query-optimization
  • replication
  • monitoring
  • backup-recovery
  • planetscale

README badge

README badge for planetscale/database-skills/postgres

What it does

Provides Postgres best practices, query optimization guidance, indexing strategies, and schema design patterns. Includes PlanetScale-specific connection pooling, monitoring, and CLI reference for hosted Postgres deployments.

Generated from the current SKILL.md.

Frequently asked

Does this skill cover PlanetScale-specific features like connection pooling?
Yes. The skill includes references for PlanetScale connection pooling, PgBouncer configuration, the pscale CLI, and PlanetScale Insights for slow query analysis.
What topics does this skill cover?
Schema design, indexing, query optimization, partitioning, MVCC and transactions, replication, WAL operations, monitoring, backup/recovery, and PlanetScale-specific connection and deployment workflows.
Does this skill help with query performance troubleshooting?
Yes. It includes guidance on query patterns, index optimization, MVCC transaction isolation, and monitoring via pg_stat views and pg_stat_statements.
Can I use this skill if I self-host Postgres instead of PlanetScale?
Yes. The skill covers generic Postgres best practices and operations. PlanetScale-specific references are optional and only used if you choose PlanetScale for hosting.

Generated from the current SKILL.md. These answers refresh after source changes.