Przejdź do treści
Biblioteka skilli
Programowanie · Testowanie

postgresai

/postgresai

Uruchamia EXPLAIN i EXPLAIN ANALYZE, testuje indeksy i mierzy koszt zapytań na klonach Database Lab PostgresAI przez CLI, w skali produkcyjnej, także przed przeglądem bazy GitLab.

Repozytorium
gitlabhq ↗
Licencja
MIT
Ostatnia zmiana repozytorium
23.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
7
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 23.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/joe.sh, tests/test_joe.sh

Co robi i kiedy

Uruchamia EXPLAIN i EXPLAIN ANALYZE, testuje indeksy i mierzy koszt zapytań na klonach Database Lab PostgresAI przez CLI, w skali produkcyjnej, także przed przeglądem bazy GitLab.

Oryginalny opis (EN)

Run EXPLAIN / EXPLAIN ANALYZE, test indexes, and measure query cost on PostgresAI Database Lab thin clones with the PostgresAI CLI (postgresai, pgai, Joe). Use when asked to explain or optimize a query, check a plan at production scale, try an index on realistic data, or prepare a GitLab database review.

Jak działa

  1. When to Use
  2. Install
  3. Authenticate
  4. Pick the target
  5. Core loop
  6. Gotchas
  7. Safety rules
  8. GitLab-specific
  9. CLI reference (live)
  10. Contributing Improvements
Sekcje z nagłówków SKILL.md, w oryginale · 94 linii, 600 słów
Podgląd SKILL.md
---
name: postgresai
description: "Run EXPLAIN / EXPLAIN ANALYZE, test indexes, and measure query cost on PostgresAI Database Lab thin clones with the PostgresAI CLI (postgresai, pgai, Joe). Use when asked to explain or optimize a query, check a plan at production scale, try an index on realistic data, or prepare a GitLab database review."
version: 1.0.3
license: MIT
category: Database
---

# PostgresAI CLI (Database Lab / Joe)

Run `EXPLAIN` and DDL experiments on ephemeral thin clones of production-sized data
from the terminal, not the Joe chat bot.

## When to Use

- Checking query plans at production scale, or testing an index or migration on a thin clone.
- Collecting queries and plans as evidence for a database review.

Not for local development databases (GitLab: use `gitlab-psql`).

## Install

Prefer npm: `npm i -g postgresai` (or `npx postgresai ...`); binaries `postgresai`, `pgai`.
Don't rely on a Homebrew tap; it may no longer exist.

## Authenticate

`postgresai auth show-key` shows whether a key is stored; if not, run `postgresai login` (browser
OAuth, callback on `127.0.0.1`, `--port` selectable). Headless: `login --set-key <key>` or
`PGAI_API_KEY`. Never commit or print the key.

## Pick the target

```shell
postgresai projects        # JOE column shows which projects are ready
```

Pass `--project <id|alias>` (or `--instance-id <id>`) to `joe`, or store a default with
`postgresai set-default-project <alias>`; `joe --help` wrongly says `--project` is always required.
Prefer JOE `ready` entries (skips stale `-deprecated`/`-new` duplicates); ask the user if ambiguous.

## Core loop

Run `joe` through [scripts/joe.sh](scripts/joe.sh) (path relative to this skill): same arguments as
`postgresai joe`, but it waits out the CLI's poll budget and prints only the result.

```shell
J=scripts/joe.sh; P="--project <alias>"
$J plan     $P "SELECT ..."            # estimates only, never executes: default
$J explain  $P "SELECT ..."            # EXPLAIN + ANALYZE + buffers, executes on clone
$J describe $P <table>                 # \d-style metadata
$J exec     $P "CREATE INDEX ..."      # real DDL on the clone; prints only the duration
$J exec     $P "ANALYZE <table>"       # refresh stats, then `explain` again to re-measure
$J reset    $P                         # discard experiments
```

Plans and iterating: [references/plan-analysis.md](references/plan-analysis.md).

## Gotchas

- **Budget:** plain `postgresai joe` returns exit 0 after `--budget` (default 25 s) with
  `started <id> · pending … resume: pgai joe result <id>`; the command keeps running (`result`
  exits 1 while pending). `joe.sh` polls (`JOE_WAIT_SECONDS`, default 600; raise it for big tables).
- **Don't `reset` to stop a slow command** (kills pending work, `conn closed`): use
  `joe activity` and `joe terminate <pid>`.
- **`hypo` (HypoPG) didn't persist between CLI calls**: test indexes with `exec CREATE INDEX` +
  `exec ANALYZE` + `explain` (see plan-analysis).
- `explain` and `exec` really execute: bound queries (`LIMIT`, tenant/project id). `exec` returns no rows.
- **Clone creation can fail** (`failed to create a Database Lab clone`). Stop using that target
  for the session (`explain`/`reset` fail the same way), report it, don't retry in a loop. Switch
  target only if another database can answer the question.
- JSON output and explicit clones: [references/advanced.md](references/advanced.md).

## Safety rules

- Experiment only through the clone commands; never run writes or DDL against production or
  replicas by any other route. Always `joe reset` when finished.
- Clone data is real production data. **Never paste row values, emails, tokens or
  result sets** into public MRs, issues, or repos. Share SQL, plans with literals
  replaced by placeholders, and timings/buffer counts only.
- Clones may enforce statement timeouts; don't retry them in a loop.

## GitLab-specific

GitLab monolith: target aliases in [references/gitlab.md](references/gitlab.md); review flow in
[references/db-review-flow.md](references/db-review-flow.md).

## CLI reference (live)

Flags change between releases; check the installed CLI:

!`postgresai joe --help 2>&1 | head -30`

## Contributing Improvements

This skill is maintained in [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) at
`.claude/skills/postgresai/`.
If you discover that any guidance here is **inaccurate or outdated** (e.g. a command that no
longer works, a wrong flag, CLI output drift that breaks `scripts/joe.sh`), confirm with the
user and open an MR against `gitlab-org/gitlab` with the fix. Keep changes focused — one fix per MR.
Pliki w paczce (7)
  • SKILL.md 5 KB
  • references/advanced.md 1 KB
  • references/db-review-flow.md 1 KB
  • references/gitlab.md 1 KB
  • references/plan-analysis.md 2 KB
  • scripts/joe.sh 3 KB
  • tests/test_joe.sh 6 KB

Wersje

W bazie nie ma innych skilli o nazwie postgresai.

Migawka bazy z 13.11.2026 · wersja paczki ddc79fd3a51c (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100db-query-plan-analyzer
    Czyta wyniki EXPLAIN i EXPLAIN ANALYZE z PostgreSQL, MySQL i SQLite, wskazuje dominujący koszt i proponuje konkretny indeks lub przepisanie zapytania wraz z instrukcją CREATE INDEX.
  • 100analyzing-database-indexes
    Projektuje i optymalizuje indeksy baz danych, żeby przyspieszyć zapytania.
  • 90database-query-performance
    Diagnozuje opóźnienia bazy danych przez plany wykonania, własność indeksów i przegląd kształtu zapytań, gdy zapytanie jest wolne, brakuje indeksu albo pojawiają się skany i wzorce N+1.
  • 100mariadb-explain
    Opisuje zachowanie EXPLAIN i ANALYZE w MariaDB: samodzielne ANALYZE faktycznie wykonuje zapytanie, EXPLAIN niczego nie uruchamia, formaty JSON i tradycyjny oraz SHOW EXPLAIN dla trwających zapytań.
  • 100database-index-design
    Projektuje indeksy relacyjnych baz z rzeczywistego obciążenia zapytaniami: kolejność kolumn, indeksy pokrywające, częściowe i wyrażeniowe oraz koszt zapisu.
  • 100db-index-advisor
    Doradza w optymalizacji indeksów PostgreSQL, MySQL i SQLite: analizuje wolne zapytania, brakujące, nieużywane i nadmiarowe indeksy oraz generuje instrukcje CREATE INDEX z szacunkami EXPLAIN ANALYZE.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.