All skills
planetscale avatar

/postgres

@2b8cda6 official

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

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

This session only. Nothing lands on disk.

referencesmvcc-transactions.md

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

MVCC Transactions and Concurrency

Transaction Isolation Levels

  • READ UNCOMMITTED — treated as READ COMMITTED in PostgreSQL; no dirty reads ever.
  • READ COMMITTED (default): new snapshot per statement; can see different data within same tx.
  • REPEATABLE READ: snapshot at first query; can cause serialization errors on write conflicts.
  • SERIALIZABLE: strongest; transactions appear serial; requires retry logic in app code.

Readers never block writers; writers never block readers (only writer-writer conflicts on same row). No lock escalation — row locks never degrade to table locks.

XID Wraparound

32-bit transaction IDs wrap at ~2 billion (2^31). VACUUM FREEZE replaces old XIDs with FrozenXID (value 2, always visible). Without freeze: after wraparound, old rows appear "in the future" and become invisible. Data physically exists but is invisible to all queries — looks like total data loss. PostgreSQL emergency shutdown at 2B XIDs to prevent this. XID wraparound should be avoided at all cost.

Warning messages start at ~1.4B XIDs; shutdown at 2B. Recovery requires single-user mode VACUUM — can take hours to days on large DBs. Never disable autovacuum — it's your protection against wraparound.

XID Age Monitoring

SELECT datname, age(datfrozenxid),
  ROUND(100.0 * age(datfrozenxid) / 2147483648, 2) AS pct
FROM pg_database ORDER BY age(datfrozenxid) DESC;

Long Transaction Impact

A single long-running transaction blocks VACUUM from removing dead tuples across the entire database. Causes table bloat, increased disk, slower queries, cache pollution. idle_in_transaction connections are the #1 operational MVCC issue. Set idle_in_transaction_session_timeout (30s–5min). Dead tuples waste I/O on seq scans and cause useless heap lookups from indexes.

Serialization Errors

Apps must handle "could not serialize access" with retry logic. More common in REPEATABLE READ and SERIALIZABLE. Smaller, faster transactions reduce conflict frequency.

Source: SKILL.md on GitHub

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

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
metadata
{
  "author": "planetscale",
  "version": "1.0.0"
}
  • Database
  • postgres
  • schema-design
  • indexing
  • query-optimization
  • replication
  • monitoring
  • backup-recovery
  • planetscale

README badge

README badge for planetscale/database-skills/postgres

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.

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.