Agent skill

Postgres Performance Tuning

by fmflurry in fmflurry/settings-opencode

PostgreSQL performance tuning for the docker instance: memory sizing vs the 1g memlimit (sharedbuffers, effectivecachesize, workmem math), checkpoint tuning (maxwalsize, checkpointcompletiontarget…

MITAuto-check passedDatabases

Install Postgres Performance Tuning

skills CLI
$ npx skills add fmflurry/settings-opencode --skill postgres-performance-tuning -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install fmflurry/settings-opencode postgres-performance-tuning --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/fmflurry/settings-opencode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/postgres-performance-tuning .claude/skills/postgres-performance-tuning && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
postgres-performance-tuning
GitHub stars
171
Token cost
~2.6k tokens
SKILL.md length
872 words
Files
1
Skills in repo
37
Repo updated
First seen
Licence
MIT

At a glance

PostgreSQL performance tuning for the docker instance: memory sizing vs the 1g memlimit (sharedbuffers, effectivecachesize, workmem math), checkpoint tuning (maxwalsize, checkpointcompletiontarget…

  • Works in 6 steps: Memory sizing vs the 1g mem_limit → Checkpoint tuning → Enabling pg_stat_statements → …
  • Asked about postgres tuning
  • SKILL.md covers 1. Memory sizing vs the 1g…, 2. Checkpoint tuning, 3. Enabling pg_stat_statements and 4. Slow-query triage workflow, plus 2 more sections
  • Calls docker

What it does

Postgres Performance Tuning is an agent skill from fmflurry/settings-opencode. PostgreSQL performance tuning for the docker instance: memory sizing vs the 1g memlimit (sharedbuffers, effectivecachesize, workmem math), checkpoint tuning (maxwalsize, checkpointcompletiontarget, pgstatcheckpointer), pgstatstatements enablement via compose, slow-query triage, EXPLAIN (ANALYZE, BUFFERS) interpretation, and pgbouncer transaction-pooling constraints (SET/LISTEN-NOTIFY/PREPARE/advisory locks/WITH HOLD). Use when asked about postgres tuning, slow queries, sharedbuffers, workmem, pgstatstatements…

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Databases, covering Query optimization. It works with PostgreSQL and Docker. The repository describes itself as: Custom OpenCode settings. The licence is MIT.

When your agent uses it

  • Asked about postgres tuning
  • Pgstatstatements
  • Checkpoint tuning

Example prompts

  • “/postgres-performance-tuning”

Requirements

  • Docker

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Memory sizing vs the 1g mem_limit
  2. Checkpoint tuning
  3. Enabling pg_stat_statements
  4. Slow-query triage workflow
  5. EXPLAIN (ANALYZE, BUFFERS) — SELECTs only
  6. pgbouncer / connection pooling

What it can do on your machine

Read from SKILL.md and the folder at commit f0dcb5a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • docker

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • postgresql.org
    • pgbouncer.org
    • wolverinefx.net

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Postgres Performance Tuning loads about 2.6k tokens when it runs. Until then it costs about 173 tokens; SKILL.md has 872 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~173
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from fmflurry/settings-opencode at commit f0dcb5a, republished under its MIT licence (© fmflurry). 872 words, ~2,611 tokens.

Download SKILL.mdSave it as .claude/skills/postgres-performance-tuning/SKILL.md (or your agent's skills folder).
name
postgres-performance-tuning
description
PostgreSQL performance tuning for the docker instance: memory sizing vs the 1g mem_limit (shared_buffers, effective_cache_size, work_mem math), checkpoint tuning (max_wal_size, checkpoint_completion_target, pg_stat_checkpointer), pg_stat_statements enablement via compose, slow-query triage, EXPLAIN (ANALYZE, BUFFERS) interpretation, and pgbouncer transaction-pooling constraints (SET/LISTEN-NOTIFY/PREPARE/advisory locks/WITH HOLD). Use when asked about postgres tuning, slow queries, shared_buffers, work_mem, pg_stat_statements, pgbouncer, or checkpoint tuning. Target: postgres:16-alpine (container gc-platform-postgres). Read alongside the postgres-dba agent.

PostgreSQL Performance Tuning

Target version: postgres:16-alpine — this repository's gc-platform-postgres container: mem_limit: 1g, mem_reservation: 512m, no command: override (stock settings: shared_buffers=128MB, max_connections=100), no shared_preload_libraries.

Contract: diagnostics are read-only (pg_settings, pg_stat_*, EXPLAIN on SELECTs only). Every config change below is emitted ONLY as a ⚠️ HUMAN CONFIRMATION REQUIRED block — the postgres-dba agent never applies settings. Values marked ⚠️ are established heuristics, not guarantees: measure before and after every change, one parameter at a time.

Connection:

bash
docker exec gc-platform-postgres psql -U gcplatform -d gcplatform -c "<query>"

1. Memory sizing vs the 1g mem_limit

Current settings (verify live):

sql
SELECT name, setting, unit FROM pg_settings
WHERE name IN ('shared_buffers','effective_cache_size','work_mem','maintenance_work_mem',
               'max_connections','huge_pages');

⚠️ Heuristic sizing for a dedicated 1g container:

ParameterStockSuggestedRationale
shared_buffers128MB≈ 256MBClassic ⚠️ 25%-of-RAM heuristic; the container also needs room for per-backend memory, WAL buffers, and the OS page cache
effective_cache_size4GB (!)≈ 512–768MBPlanner hint for "how much caching exists total" (shared_buffers + OS cache). Stock 4GB is a lie on a 1g container and biases the planner toward index scans it shouldn't trust
work_mem4MBkeep 4–8MBAllocated PER sort/hash node PER connection. Worst case ≈ max_connections × nodes-per-query × work_mem: 100 × 4 nodes × 8MB = 3.2GB ≫ 1g. Raising it globally is how containers OOM; raise per-session for known big sorts instead
maintenance_work_mem64MB128–256MBUsed by VACUUM/CREATE INDEX; few concurrent users, safe to raise

⚠️ HUMAN CONFIRMATION REQUIRED

yaml
# docker-compose.yml, postgres service (restart required):
command: ["postgres",
  "-c", "shared_buffers=256MB",
  "-c", "effective_cache_size=768MB",
  "-c", "maintenance_work_mem=128MB"]

Verify after restart: SELECT name, setting FROM pg_settings WHERE name = 'shared_buffers'; and watch docker stats under load.


2. Checkpoint tuning

Source: https://www.postgresql.org/docs/16/wal-configuration.html

Diagnose first (see postgres-health-check §7):

sql
SELECT checkpoints_timed, checkpoints_req,
       ROUND(checkpoints_req::numeric / NULLIF(checkpoints_timed + checkpoints_req, 0) * 100, 2) AS req_pct
FROM pg_stat_checkpointer;
SHOW max_wal_size; SHOW checkpoint_completion_target; SHOW checkpoint_warning;

⚠️ Heuristics:

  • max_wal_size (default 1GB): raise to 2–4GB if req_pct > 10–20% — more WAL between checkpoints = fewer forced checkpoints = smoother I/O (cost: longer crash recovery, more pg_wal disk).
  • checkpoint_completion_target = 0.9 — already the default since PG14; spreads checkpoint writes across 90% of the interval. Verify it, don't blindly set it.
  • checkpoint_warning = 30s (default): logs when checkpoints are too close together; keep it as the canary.

⚠️ HUMAN CONFIRMATION REQUIRED

yaml
command: ["postgres", "-c", "max_wal_size=2GB", "-c", "checkpoint_completion_target=0.9"]

3. Enabling pg_stat_statements

The stock compose loads no extensions (shared_preload_libraries empty), so pg_stat_statements — the single highest-value slow-query tool — is unavailable until enabled.

Source: https://www.postgresql.org/docs/16/pgstatstatements.html ⚠️ (must be loaded via shared_preload_libraries → requires server restart, not a reload; the extension object then still needs CREATE EXTENSION per database).

⚠️ HUMAN CONFIRMATION REQUIRED

yaml
# docker-compose.yml, postgres service (restart required):
command: ["postgres", "-c", "shared_preload_libraries=pg_stat_statements",
          "-c", "pg_stat_statements.max=10000",
          "-c", "pg_stat_statements.track=all"]

Then the extension itself is a migration (repo change → dispatch coder):

⚠️ HUMAN CONFIRMATION REQUIRED

sql
-- Applied as an EF Core migration under the superuser/migrator connection, never ad hoc:
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Combine with §1/§2 if changing both: a single command: array holds all -c flags.


4. Slow-query triage workflow

Requires §3 enabled. Order of operations:

sql
-- 1. Worst by TOTAL time (the queries costing the most aggregate):
SELECT LEFT(query, 100) AS query, calls,
       round(total_exec_time::numeric, 1) AS total_ms,
       round(mean_exec_time::numeric, 1) AS mean_ms,
       rows,
       round((shared_blks_hit * 100.0 / NULLIF(shared_blks_hit + shared_blks_read, 0))::numeric, 2) AS hit_pct
FROM pg_stat_statements
ORDER BY total_exec_time DESC LIMIT 15;

-- 2. Worst by MEAN time (individual slow queries):
SELECT LEFT(query, 100), calls, round(mean_exec_time::numeric, 1) AS mean_ms, rows
FROM pg_stat_statements
WHERE calls > 20
ORDER BY mean_exec_time DESC LIMIT 15;

Interpretation: high calls × mean = hot path (index or N+1 — the latter is code → database-reviewer); low hit_pct = cache/index problem; huge rows vs returned rows = missing predicate index. pg_stat_statements normalizes parameters ($1) — it shows query shapes, not literals.

Remediation: index/query fixes are code/migration changes → database-reviewer + coder. Instance-side only: pg_stat_statements_reset() to re-measure after a change:

⚠️ HUMAN CONFIRMATION REQUIRED

sql
SELECT pg_stat_statements_reset();

5. EXPLAIN (ANALYZE, BUFFERS) — SELECTs only

sql
EXPLAIN (ANALYZE, BUFFERS)
SELECT …;   -- ⚠️ SELECTs only: ANALYZE EXECUTES the statement, so never run it on DML

Read the plan in this order:

  1. Actual vs planned rows (rows=X … actual … rows=Y): a 100×+ mismatch = stale statistics → ANALYZE <table> (⚠️ human) or the planner lacks a predicate.
  2. Node time hotspots: the top-cost node isn't always the culprit; look for nodes where actual time jumps vs their children.
  3. Buffers: shared hit = cache, shared read = disk. High reads on a hot query = index opportunity. BUFFERS output is only meaningful with ANALYZE.
  4. Seq Scan on large tables: fine for analytics, a bug for point lookups. Never add an index yourself — recommend it via database-reviewer.
  5. Nested Loop with high loops=: classic N+1 shape at the plan level.

Show full SKILL.md (327 more words)Show less

6. pgbouncer / connection pooling

Why: max_connections=100 and each backend costs ≈ 5–10MB; pooling lets hundreds of app connections share a few dozen backends.

Source: https://www.pgbouncer.org/features.html — transaction pooling (the mode you want) supports only what fits inside a single transaction. It BREAKS:

FeatureWhy it breaks under transaction pooling
SET (session-level)Session state is not pinned to a backend; the next query may run on another backend
LISTEN / NOTIFYNotifications are session-bound; pooled clients never (reliably) receive them
PREPARE (client-side prepared statements)The prepared plan lives on one backend; pgbouncer ≥ 1.21 can proxy them only if max_prepared_statements > 0
Session-level advisory locks (pg_advisory_lock)Lock held by a backend that the client is detached from after the transaction (transaction-level pg_advisory_xact_lock IS safe)
Cursors WITH HOLDSurvive transaction end → meaningless when the backend changes
Repo-specific verdict
  • ✓ SET LOCAL app.tenant_id = … is transaction-pooling-safe. It scopes to the current transaction, which is exactly what transaction pooling preserves — the RLS tenant GUC pattern (ADR-0038, canonical GUC app.tenant_id) works behind pgbouncer. (Session-level SET app.tenant_id without LOCAL would NOT be safe.)
  • ✓ WolverineFx (ADR-0015) is transaction-pooling-safe. Its PostgreSQL transport does not use LISTEN/NOTIFY — it polls queue tables with ORDER BY … LIMIT n FOR UPDATE SKIP LOCKED (verified: https://wolverinefx.net/guide/durability/postgresql — "PostgreSQL Messaging Transport", Polling, "Dequeue Performance"). The repo's current stack (WolverineFx.Marten outbox, DurabilityAgent store-and-forward, bus not yet booted per ADR-0020) is plain SQL + polling — exactly what transaction pooling preserves.
  • ⚠️ Residual: re-verify this verdict if any future component explicitly uses LISTEN/NOTIFY (custom NOTIFY triggers, cache-invalidation libraries, trigger-based NOTIFY) — those connections must bypass pgbouncer (direct connection string).
  • ⚠️ Npgsql prepared statements: Npgsql 8+ prepares statements by default. Behind pgbouncer this requires pgbouncer ≥ 1.21 with max_prepared_statements > 0, or set Max Auto Prepare=0 / No Reset On Close=true per Npgsql's pgbouncer guidance. Verify against the Npgsql version in backend/ before rollout.

⚠️ HUMAN CONFIRMATION REQUIRED — pooling is an infra rollout (new compose service), emitted for humans only:

yaml
# Sketch — not applied by this agent:
pgbouncer:
  image: edoburu/pgbouncer:latest   # ⚠️ pick a pinned, actively-maintained image
  environment:
    DB_HOST: postgres
    POOL_MODE: transaction
    MAX_PREPARED_STATEMENTS: "100"   # pgbouncer ≥ 1.21, for Npgsql prepared statements
  depends_on:
    postgres:
      condition: service_healthy

Rollout order: verify Wolverine transport → verify Npgsql version → pool the backend's DefaultConnection (gc_kourou_app_login) only → keep MigrationConnection and any LISTEN/NOTIFY consumer direct.

© fmflurry, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/postgres-performance-tuning of fmflurry/settings-opencode.

Open the folder on GitHubat commit f0dcb5a

Compare with similar skills

Postgres Performance Tuning next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Postgres Performance Tuning compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Postgres Performance Tuning this skillfmflurry/settings-opencode171—~2.6kAutomated safety check: PassMIT
Supabase Postgres Best Practicessupabase/agent-skills2.7k24 repos~808Automated safety check: PassMIT
How To Communicatedatabasus/databasus8.8k—~3.9kAutomated safety check: PassMIT
SQL Database Support for pRESTprest/prest4.6k—~1.6kAutomated safety check: PassMIT
PlanetScale Postgres Playbookplanetscale/database-skills6983 repos~1.8kAutomated safety check: PassMIT
PostgreSQL Documentation Reference2025Emma/vibe-coding-cn23k1 repos~19kAutomated safety check: PassMIT

Similar skills

  • Official

    Gives the agent Postgres rules to consult before writing or changing tables, queries, indexes, RLS policies or migrations, and when diagnosing slow queries.

    2.7k GitHub starsUsed in 24 repos~808 tokens
    DatabasesAuto-check passed
  • How To Communicate

    databasus/databasus

    Communicate clearly in every response, progress update and agent-authored document.

    8.8k GitHub stars~3.9k tokensUpdated 15 days ago
    DatabasesAuto-check passed
  • Guides classifying, gap-analyzing and scaffolding support for a new SQL database in pREST, from Postgres-compatible variants to entirely new dialects.

    4.6k GitHub stars~1.6k tokensUpdated yesterday
    DatabasesAuto-check passed
  • PlanetScale Postgres Playbook

    planetscale/database-skills

    Official

    Indexes reference files on Postgres schema design, indexing, partitioning, query patterns, MVCC and VACUUM, and PlanetScale-specific operations.

    698 GitHub starsUsed in 3 repos~1.8k tokens
    DatabasesAuto-check passed
  • PostgreSQL Documentation Reference

    2025Emma/vibe-coding-cn

    PostgreSQL database documentation - SQL queries, database design, administration, performance tuning, and advanced features. Use when working with PostgreSQL…

    23k GitHub starsUsed in 1 repo~19k tokens
    DatabasesAuto-check passed
  • DB Ops Sop

    OpenDCAI/DataMind

    Database operations runbook — backup, recovery, performance tuning, troubleshooting.

    406 GitHub stars~388 tokensUpdated 17 days ago
    DatabasesAuto-check passed

More from fmflurry/settings-opencode

All 37 skills in this repo
  • Show Your Work

    fmflurry/settings-opencode

    Keep a reviewable decision trail for long-running or unattended work: a TSV log with one row per decision (what, why, evidence, result).

    171 GitHub stars~1.8k tokensUpdated 2 days ago
    Auto-check passed
  • Playwright E2E Authoring

    fmflurry/settings-opencode

    Scaffold and extend Playwright E2E tests for the gc.platform suite (tests/playwright), wiring every artifact to the real frontend (localhost:4200) + real .NET backend — never mocks.

    171 GitHub stars~2.4k tokensUpdated 2 days ago
    Auto-check passed
  • Why

    fmflurry/settings-opencode

    A skill your agent uses for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds.

    171 GitHub stars~2k tokensUpdated 2 days ago
    Auto-check passed
  • Angular Accessibility

    fmflurry/settings-opencode

    Audit and fix common accessibility issues in Angular templates and Angular Material components.

    171 GitHub stars~2.7k tokensUpdated 2 days ago
    Auto-check passed
  • Angular Clean Architecture

    fmflurry/settings-opencode

    Scaffolds and extends Angular standalone feature MODULES under src/app/modules/{name} using Clean Architecture layering (presentation/application/core/infrastructure), a self-registering module…

    171 GitHub stars~3.6k tokensUpdated 2 days ago
    Auto-check passed
  • Angular Cop

    fmflurry/settings-opencode

    Pre-merge code review for Angular + TypeScript pull requests.

    171 GitHub stars~1.4k tokensUpdated 2 days ago
    Auto-check passed

Categories

Questions about Postgres Performance Tuning

What does Postgres Performance Tuning do?

PostgreSQL performance tuning for the docker instance: memory sizing vs the 1g memlimit (sharedbuffers, effectivecachesize, workmem math), checkpoint tuning (maxwalsize, checkpointcompletiontarget…. Postgres Performance Tuning is an agent skill from fmflurry/settings-opencode. PostgreSQL performance tuning for the docker instance: memory sizing vs the 1g memlimit (sharedbuffers, effectivecachesize, workmem math), checkpoint tuning (maxwalsize, checkpointcompletiontarget, pgstatcheckpointer), pgstatstatements enablement via compose, slow-query triage, EXPLAIN (ANALYZE, BUFFERS) interpretation, and pgbouncer transaction-pooling constraints (SET/LISTEN-NOTIFY/PREPARE/advisory locks/WITH HOLD).

When should I use Postgres Performance Tuning?

Postgres Performance Tuning fits situations like: asked about postgres tuning; pgstatstatements; checkpoint tuning.

How do I install Postgres Performance Tuning in Claude Code?

Run `npx skills add fmflurry/settings-opencode --skill postgres-performance-tuning -a claude-code`. Or copy the skill folder (skills/postgres-performance-tuning in fmflurry/settings-opencode) into .claude/skills/postgres-performance-tuning in your project. Claude Code loads it when a task matches its description.

How do I install Postgres Performance Tuning in Codex?

Run `npx skills add fmflurry/settings-opencode --skill postgres-performance-tuning -a codex`. Or copy the skill folder (skills/postgres-performance-tuning in fmflurry/settings-opencode) into .agents/skills/postgres-performance-tuning in your project. Codex loads it when a task matches its description.

Can I use Postgres Performance Tuning in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add fmflurry/settings-opencode --skill postgres-performance-tuning -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/postgres-performance-tuning, .gemini/skills/postgres-performance-tuning, .github/skills/postgres-performance-tuning and .opencode/skills/postgres-performance-tuning in your project.

What does Postgres Performance Tuning need to run?

Going by SKILL.md and its folder, Postgres Performance Tuning needs the command-line tools its instructions call (docker). Our summary lists: Docker.

Does Postgres Performance Tuning access the network?

SKILL.md names 3 domains. As links in the text: postgresql.org, pgbouncer.org and wolverinefx.net. This is read from the text; nothing was executed.

Is Postgres Performance Tuning safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Postgres Performance Tuning use?

Postgres Performance Tuning is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Postgres Performance Tuning use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Postgres Performance Tuning?

Skills that share tags, products or a category with Postgres Performance Tuning: Supabase Postgres Best Practices (supabase/agent-skills, 2.7k stars), How To Communicate (databasus/databasus, 8.8k stars), SQL Database Support for pREST (prest/prest, 4.6k stars) and PlanetScale Postgres Playbook (planetscale/database-skills, 698 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Postgres Performance Tuning?

fmflurry (a GitHub user) maintains it in fmflurry/settings-opencode, which has 171 GitHub stars. The repository holds 37 skills in this directory. The repository was last updated on October 5, 2026.

Source: fmflurry/settings-opencode on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.