DDX for PostgreSQL — How To Use Each Endpoint
Complete setup and usage guides for accessing PostgreSQL mailing lists and repositories.
For LLM clients: see /llms.txt for a structured index of all programmatic interfaces, suitable for autonomous agents that need to bootstrap context about pg.ddx.io quickly.
OVERVIEW
DDX for PostgreSQL offers multiple protocols to access the same data. Choose the one that fits your workflow:
- IMAP / POP3: Use your email client (Thunderbird, Apple Mail, Outlook, etc.)
- NNTP: Use a newsreader (classic protocol for discussion forums)
- Git: Clone a mailing list as a git repository
- HTTP/REST: Programmatic access with full-text search, semantic search (experimental, currently slow), and structured queries
- GraphQL: Pick exactly the fields you want at
POST /api/graphql— one round trip, multi-inbox queries via aliasing - MCP: Integrate with AI agents via Model Context Protocol
What do you want to do?
Each answer lists the ways to do it, best first. All of them are free and need no account.
Keep your own copy of a mailing list
- Clone it with git. One transfer gets the whole list; later,
git fetchbrings only what is new.git clone https://pg.ddx.io/m/pgsql-hackers.git git -C pgsql-hackers fetch # later
Each commit is one message (public-inbox v2 format). Over SSH:git clone ssh://git@git.pg.ddx.io:22/pgsql-hackers.gitGit clone setup → - Mirror it into a mailbox with
imapsync, if you want the mail in your own IMAP server rather than as git. Point it atimap.pg.ddx.io:993with any username and password. Each list is split into numbered folders (pgsql-hackers.0….86), so select a numbered folder, not the bare list name. IMAP details → - Download a range as mbox for a one-off:
https://pg.ddx.io/m/pgsql-hackers/<from>-<to>.mbox.gz. The numbers come from/m/pgsql-hackers/info.json. mbox ranges →
Please do not build a copy by fetching messages one at a time over HTTP. It is far slower for you, and at scale it is what takes this one-server site down. See agents.txt.
Be told when new mail arrives on a list
- Subscribe to the list's feed in any feed reader:
https://pg.ddx.io/m/pgsql-hackers/new.atom(orrss.xml). For new threads only:topics_new.atom; for threads with fresh replies:topics_active.atom. Feeds → - Leave a mail client connected to
imap.pg.ddx.io:993on the newest numbered folder; the server pushes new mail with IMAP IDLE. IMAP IDLE → - From code or an agent, poll with a cursor so you only ever see
what is new: the
get_new_messagesMCP tool takes the last article number you saw and returns what came after it.get_new_messages→
Read a list without subscribing to it
- In your browser: browse the archive, threaded, with every message linked to the commits it led to.
- In your mail client, as a read-only account:
IMAP serverimap.pg.ddx.io, port993, SSL/TLS, any username and password. Every list appears as folders. Nothing you do there can send mail or change anything. IMAP setup → - In a newsreader:
nntp.pg.ddx.io, port563with TLS, or119plain. Each list is a newsgroup (pgsql-hackers); read-only. NNTP setup →
Be told when new commits land in a repository
- Subscribe to the commit feed:
https://pg.ddx.io/gitweb/?p=postgresql.git;a=atom. Each entry is one commit with its full message, including theDiscussion:link back to the thread. Swap the project name forpgbouncer,pgjdbc, and the rest listed on /gitweb/. Commit feed → - Follow the committers list if you would rather have it by mail:
https://pg.ddx.io/m/pgsql-committers/new.atom, or the same list over IMAP. Read pgsql-committers →
Search commits the way you used to on git.postgresql.org
Use the same gitweb URLs with the host changed; the st= modes and a
commit search box are in 4b. Or use the
/api/v2/repos/postgres/commits?q= JSON API, or the
git_search MCP tool.
Open postgresql.org links here automatically
The pg.ddx.io redirector sends
postgr.es/m/… and postgresql.org/message-id/… links to
the threaded view here, and gitweb links to the gitweb here. Available as a
userscript for any browser and as a Chrome extension.
1. IMAP — Email Client Access
IMAP treats each PostgreSQL mailing list as an IMAP folder. Once connected, you can browse, search, and read messages directly in Thunderbird, Apple Mail, Outlook, or any IMAP-compatible email client.
Setup
- Thunderbird: File → New → Existing Mail Account → Enter any username/password → Configure manually
- Apple Mail: Mail → Preferences → Accounts → + → Other Mail Account
- Outlook: File → Account Settings → Account Settings → New → More Options
pgsql-general (most active, general discussion).
Usage
1. Click "pgsql-hackers" folder
2. Your email client shows the newest messages first
3. Click a message to read the full thread
1. In Thunderbird: right-click a folder → Search Messages
2. Search for: "VACUUM performance" across pgsql-performance
3. Results show all matching messages with context
1. Set your client to check for new mail every 1 hour (Settings)
2. Enable notifications when new messages arrive
3. You'll get alerts for new pgsql-hackers discussions
Tips
- No authentication needed: Use any username/password. We don't verify — all lists are public read-only.
- Threading: IMAP preserves message threading, so replies are grouped under the original message.
- Large mailboxes: Start with 2-3 lists. Adding all 85 lists may slow your client. You can add more later.
- Offline access: Most email clients cache messages locally, so you can read offline and reconnect to sync.
2. POP3 — Download and Keep Locally
POP3 downloads messages and removes them from the server. Use this if you want to keep a local archive of PostgreSQL discussions.
Setup
Username format is required and strict. The server replies
-ERR no UUID@ in mailbox name if the <UUID>@
prefix is missing.
- UUID: any 32-hex-digit identifier, dashes optional. It is
an opaque per-client tracking ID, not a credential — pick one once and
reuse it. Example:
deadbeefdeadbeefdeadbeefdeadbeefordead-beef-dead-beef-dead-beef-dead-beef. - newsgroup: the inbox to read, e.g.
pgsql.hackers,pgsql.general,pgsql.bugs. - .slice (optional): integer slice number; omit for the latest slice.
- ?initial_limit=N&limit=N (optional): cap the number of messages returned.
- Password: must be the literal string
anonymous.
Example username: deadbeefdeadbeefdeadbeefdeadbeef@pgsql.hackers
Usage
Set your client to check every 24 hours. All new messages download and stay on your computer. Good for backup and offline research.
3. NNTP — Newsreader Access
If you use a newsreader (Thunderbird, Usenet clients), connect via NNTP. Each mailing list appears as a newsgroup.
Setup
In Thunderbird, tick Use secure connection (SSL) and set the port to 563. No username or password is needed.
- Thunderbird: Edit → Preferences → Network & Storage → Newsgroup Servers → Add
- Other newsreaders: Add server with the address above
Note: Newsgroup names use hyphens, not dots.
Usage
Read and search the lists as you would any newsgroup. The server is read-only: it answers POST with 440 posting not allowed. To take part in a discussion, reply to the list by email.
4. Git — Clone a Mailing List as Repository
Clone any PostgreSQL mailing list as a git repository. Each message is a commit. Use this for data analysis, historical research, or building tools.
What these repositories actually are. The git URLs under /m/<inbox>.git are public-inbox v2 archives of mailing-list traffic. They are not mirrors of the upstream PostgreSQL source tree. Each commit is one email; the working tree contains the message's metadata and body. To clone the actual PostgreSQL source code or any other upstream project repository, go to its canonical home (for PostgreSQL: https://git.postgresql.org/git/postgresql.git). pg.ddx.io does not re-publish project source repos.
Setup
Usage
(Shows how many messages per day)
Tips
- Large repositories: pgsql-hackers is ~190k commits. Clone may take 5-10 minutes.
- Shallow clone (faster):
git clone --depth 100 https://pg.ddx.io/m/pgsql-hackers.git - Script automation: Perfect for CI/CD pipelines that analyze historical discussions.
4a. Feeds & notifications — be told when something new arrives
New mail on a list
Replace pgsql-hackers with any list on the archive.
The message feeds hold the 25 newest messages; the two topic feeds hold 50 threads.
New commits in a repository
The 50 newest commits, newest first. Each entry is the full commit message,
so the Discussion:, Reviewed-by: and
Backpatch-through: trailers are there, and the link opens the commit.
a=rss returns the same feed. Swap postgresql for any project
on /gitweb/ — pgbouncer, pgjdbc,
pgpool2, psqlodbc and the rest.
Push, in a mail client (IMAP IDLE)
Connect to imap.pg.ddx.io:993 and open the highest-numbered
folder of the list (for pgsql-hackers, pgsql-hackers.86). Each list is
split into numbered folders, and new mail lands in the last one. The server supports
IDLE, so a client left open is told about new mail as it arrives.
From code or an agent
Poll with a cursor so you only ever receive what is new. The
get_new_messages MCP tool takes the last article_num you saw
and returns what came after it, with has_more when there is another page:
A range of messages as a file
The numbers are article numbers, which are global across all lists rather
than counted from 1 within each one — so 1-100 usually returns
nothing. Read a list's current range from /m/pgsql-hackers/info.json.
For a whole list, clone it instead.
4b. Git commit search (REST) — the gitweb replacement for agents
This is a fast, agent-friendly alternative to git.postgresql.org/gitweb, which still serves browsing but answers a=search with HTTP 429 (checked 2026-10-22: summary pages 200, every search 429). Unlike the /m/<inbox>.git mailing-list repos above, these endpoints index the real source repositories — the full postgres history since 1996 (65k+ commits) plus ecosystem repos (pgbouncer, pgpool2, pgjdbc, and more). Commit-message search is backed by a Postgres full-text (pg_fts) index, so it stays fast under heavy automated load.
Your gitweb URLs keep working
The full postgres git history since 1996, searchable by commit message,
author and file path. Your existing gitweb search URLs keep working: change the host and
nothing else.
st=commit searches commit messages, st=author and
st=committer search names, and st=grep searches the
source tree for a string and links each file and line.
As JSON: GET /api/v2/repos/postgres/commits?q=… ·
from an agent: the git_search MCP tool ·
or explore everything in the GraphQL explorer.
Setup
None. Any HTTP client. All responses are JSON.
Endpoints
| Endpoint | Returns |
|---|---|
GET /api/v2/repos | List of indexed repositories. |
GET /api/v2/repos/{name}/commits?q=… | Commit log / search. Params below. |
GET /api/v2/repos/{name}/commits/{sha} | One commit: full message, author, committer, parent. sha is a full or ≥7-char git SHA. |
GET /api/v2/repos/{name}/branches | Branch list. |
/commits query parameters
| Param | Meaning |
|---|---|
q | Full-text search of the commit message (pg_fts, index-backed). Words are AND-ed; the operators of the search page work here, so from:, after: and before: narrow by author and date. Quotes, | and -word are not applied to commits; use -intext:word to exclude a word. |
author | Filter by author name or email fragment (the same as from: in q). |
limit, offset | Page size (default 50, max 200) and offset. |
trailer | A commit trailer, Key=Value or Key (also trailer:Key=Value in q). |
Each result has commit (the git SHA), subject, author, email, and date.
A full or ≥7-char SHA prefix resolves to the commit with its complete message, committer, and parent id.
Commits by a file path or on one branch are in the any-version code history: GET /api/v2/code/history/commits?paths=src/backend/access/heap/vacuumlazy.c&range=REL_14_STABLE.
Code browser. We index far more than commit messages: a symbol graph (functions, structs, macros, types across C, Rust, SQL, Java, C++, Python, Go), a call graph, and the full file content of every repo we mirror. A GitHub/Forgejo-class browser is built on top of it: /c/postgres/ is the tree at the default branch's head, and /c/<repo>/<commit, branch or tag>/<path> a tree or a syntax-highlighted file at that commit (#L120-L140 selects lines), with the commit's message and links, older/newer commit links (keys [ and ]), ?blame=1, ?changes=1 (that commit's diff), identifiers linking their definition and a #define's expansion on hover. /search's Code at a commit (src=code&rev=, or GET /api/v2/code/at) finds text and symbols at one commit. The older forms /c/<repo>/blob/<commit>/<path> and /c/<repo>/tree/<commit>/<path> still work, a git-blame where every line's commit metadata is a link (/c/<repo>/blame/<commit>/<path> — to the commit, the author's people page, the CVE it fixed, the discussion thread it came from), a per-file symbol outline, code & symbol search with GitHub-style filters (lang:, path:, symbol:, kind:, repo:; also GET /api/v2/code/search and /api/v2/code/symbol), and in-browser diffs between two points in time (/c/<repo>/compare/<base>...<head>). The gitweb views remain for raw blobs and the classic surface.
4c. Search syntax & the unified search page
The /search page searches the mailing lists, the PostgreSQL documentation, the wiki and the git commit history together, and every search is a deep link (the query lives in the URL: /search?q=…&l=<list>&repo=<repo>&src=mail,docs,wiki,git, plus dv=18,17 for documentation versions and wh=1 to include wiki page history). Pick which sources, list, repo, documentation versions and wiki history to search with the checkboxes and facets; results are clickable (mail → the message; documentation → postgresql.org; wiki → the page, or the matching revision; commit → the gitweb-style commit view). The box in every page’s header goes to the same page. Settings you change there (sources, list, repository, order, match mode, documentation versions, wiki history, commitfests) are kept for your next search in a cookie; a link that names a setting wins, and Reset search settings clears it (privacy). To search this site’s own pages instead (this how-to, the API and MCP tool reference, the skills catalogue), use site search.
Archive (era=) picks whose history to search. PostgreSQL (the default) is everything above. University POSTGRES (era=ucbpg) searches the Berkeley postgres mailing list (1991–1997), the documentation version ucbpg and the symbols of the POSTGRES and Postgres95 releases. University INGRES (era=ucbingres) searches INGRES on Usenet (1985–1995), the INGRES manuals (ucbingres) and the INGRES 8.9 source. A historical era has no wiki or commitfest, and its repositories hold one synthetic import commit per release, so the git half becomes a symbol search across the era’s repositories (GET /api/v2/code/search?q=&repo=ucb-ingres-8.9,ucb-ingres-8.9-linux). The era is saved with the other settings.
Operators work in the box and in q= of every search API (mail, docs, wiki, commits, commitfest) and the MCP search verbs. Google documents six (“exact phrase”, site:, -, before:, after:, filetype:); the rest are its long-standing undocumented ones, the public-inbox prefixes this archive always took, and Gmail’s. Put - before any operator to negate it (-site:wiki, -has:patch, -/^re:/). A word: that is not an operator is an ordinary word, so pg_catalog::regclass and ERROR: deadlock search as written. A source an operator does not apply to is left out and the page says why. Recognised operators show as chips under the box; click × to drop one.
| Operator | Google (or origin) | Here | Sources | Example |
|---|---|---|---|---|
"exact phrase" | the words, adjacent and in order | docs, wiki and commitfest: same. Mail ranks a phrase as its words in any order (a positional check over the archive takes 5–30 s); commits drop the quotes | all | "visibility map" |
-word, +word | exclude / require a word | same; a sign is an operator only before a letter or a quote, so -O2 and 8-byte stay literal. Commits ignore -word (it is read as a word to match); exclude with -intext:word there | mail, docs, wiki, commitfest | vacuum -autovacuum |
OR | either word | one or two words are AND-ed; three or more are OR-ed and the messages matching the most words rank first. and/or/not carry no meaning of their own. pg_fts boolean syntax (a | b, (a | b) & c) is passed through to mail; docs, wiki and commits read the words AND-ed | (hash | btree) & vacuum | |
site: | results from one site or path | a source: site:mail, site:docs, site:wiki, site:commits, site:commitfest; a list (site:pgsql-bugs, site:pgjdbc) or a repository (site:pgbouncer: the page then searches that repository’s commits); or the real host (site:postgresql.org/docs, site:wiki.postgresql.org, site:commitfest.postgresql.org, site:git.postgresql.org). It ticks the checkboxes; -site: leaves one out | all | vacuum site:docs |
before: after: | by date | YYYY, YYYY-MM, YYYY-MM-DD or YYYY/MM/DD, UTC; after: includes the day, before: does not. Mail by its date, wiki by revision, commits by commit time, commitfest by last update; docs search the releases that were current then | all | hash index before:2010 |
d:A..B, date: | (public-inbox) | a range of the same forms, both ends included: d:2024-01..2024-02 is after:2024-01 before:2024-03; d:2024.. and d:..2019 are open | all | vacuum d:2024-01..2024-02 |
intitle: allintitle: | a word in the page title | mail subject (also s:, subject:), doc or wiki title, commitfest title, a commit’s first line | all | intitle:freeze vacuum |
intext: allintext: | a word in the body | the author’s own words in mail (quotes left out; also b:, body:), doc and wiki text, the commit message | mail, docs, wiki, git | intext:deadlock |
inurl: allinurl: | a word in the URL | the doc path, the wiki title, the Message-ID, the commit SHA | mail, docs, wiki, git | inurl:glossary |
from: author: | (Gmail; Google Groups had author:) | the sender (name or address, also f:), the commit author, the wiki editor, the commitfest authors and reviewers | mail, wiki, git, commitfest | vacuum from:lane |
to: cc: | (Gmail) | the To and Cc headers | to:pgsql-bugs | |
filetype: ext: | files of a type | messages with an attachment of that extension; patch and diff also match text/x-patch parts | filetype:patch vacuum | |
has:patch has:attachment | (Gmail has:attachment) | messages carrying a patch, or any named attachment | has:patch logical decoding | |
link: | (retired by Google in 2017) pages linking to a URL | documents whose text links to the URL: link:example.org any URL on that host or its subdomains; link:https://example.org/a/ that URL and everything under it; link:*://example.org any scheme; * elsewhere matches anything. Alone it lists the linking documents newest first; with words it filters them. Also GET /api/v2/links?url=. | mail, docs, wiki, git, commitfest | link:*://www.postgresql.org/message-id/* |
/regex/ | (GitHub code search, Sourcegraph) | a PostgreSQL regular expression, case-insensitive (case:yes for case-sensitive); ^ and $ anchor at line ends; \/ is a slash. Scope it with a field: subject:/^\[PATCH/, from:/@example\.org$/, b:/.../. Without a field it matches the title and sender (mail), title and text (docs, wiki), the message (git). A body regex needs a word to narrow it | all | vacuum /freez(e|ing) map/ after:2016 |
related: | (retired) similar sites | a card with what relates to a Message-ID, commit, docs or wiki URL, or CVE (the cross reference, GET /api/v2/related?ref=) | the page | related:https://www.postgresql.org/docs/current/brin.html |
define: | a definition | a card with the PostgreSQL glossary entry (an acronym, plural or "See" entry finds it), the SQL standard feature (by ID or name) or the SQL key word; other glossary terms, docs sections and feature IDs in its text are links | docs (/api/v2/docs/search, MCP search_docs: a definition block) | define:MVCC, define:T611, define:LATERAL |
AROUND(n) | words within n of each other | accepted, matched as AND: pg_fts has an exact-distance <N> operator, but a positional check over every message measured 5–30 s | all | vacuum AROUND(3) freeze |
* in a phrase | any word | not supported: the full-text index has no word wildcard; use a /regex/ | — | |
a..b numbers | a number range | only as a date range in d: | — | |
cache: | Google’s cached copy | not supported: every page here is the archived copy | — | |
info:, location:, inanchor:, allinanchor: | about a page; by place; in link text | not supported: there is no page summary, no location, and link text is not indexed (only the URL is, for link:) | — | |
daterange: | by Julian day number | not supported: before:/after:/d: cover it | — |
A commit SHA as the whole query (7–40 hex characters, any case, e.g. be913fabe7) finds that commit and what refers to it: the git section shows the commit, the mail section its Discussion: thread, the pgsql-committers announcement and the mail citing the hash (each labelled), the commitfest section the entries tracking that discussion (in every commitfest), and the wiki section the pages citing it. Hex that names no commit, or a prefix two commits share, is searched as an ordinary word. A list or site: narrows the references; a date or author filter turns it back into a word search.
Operators combine: vacuum freeze -autovacuum after:2022 site:pgsql-hackers, subject:/^\[PATCH/ from:freund has:patch. Field operators (from:, intitle:, intext:) match a word in that field anywhere: from:tom matches Tom Lane and Tomas Vondra (and every other sender with “tom” in the name or address), though Tom Lane fills the first page; a value with spaces is quoted: from:"Tom Lane".
Machine access: mail → GET /api/v2/mail/search?q=&list= (omit list for all lists); documentation → GET /api/v2/docs/search?q=&versions=18,17 (versions: GET /api/v2/docs/versions); wiki → GET /api/v2/wiki/search?q=&history=1&since=&until=; git → GET /api/v2/repos/{repo}/commits?q= or the short GET /c/?q= (defaults to postgres) / GET /c/{repo}/?q=. Commitfest entries → GET /api/v2/commitfest/search?q=&cf=current|all|62,61 (default: the current commitfest; the list: GET /api/v2/commitfest/commitfests). All return JSON with links (message_url/thread_url for mail, commit SHA for git).
Mail ranking (mode= on the mail API, “Match by” on the page): hybrid (default) blends the keyword score with meaning (embedding similarity) per thread, so a question in your own words finds a discussion that used different ones; keyword ranks by the words alone (best for exact identifiers such as function or setting names); semantic ranks by meaning alone. Mail results come one per thread unless all=1.
On any message or thread page there are copy buttons under the headers: copy link (the hosted short URL pg.ddx.io/id/<message-id>), copy postgr.es (the community short form postgr.es/m/<message-id>), and — when the message or thread carries a patch — copy git am, a one-liner that pipes the thread’s mbox into git am so you can apply the patch series into a local checkout.
5. HTTP/REST — Programmatic Access
Every indexed inbox has a search endpoint at https://pg.ddx.io/m/<inbox>/?q=<term>. Add &format=json to get JSON instead of the HTML view. Each inbox is also exposed as a public-inbox v2 git repository at https://pg.ddx.io/m/<inbox>.git.
Note: indexes are populated from upstream archives over time. If you query an inbox that's still importing you'll see “No messages yet.” or “Search is not available for this inbox.” That's import lag, not breakage. Inboxes confirmed populated today include pgsql-announce, pgsql-committers, pgsql-performance.
Setup
None. curl, wget, fetch, or any HTTP client.
Usage
The endpoint https://pg.ddx.io/m/<inbox>/?...&format=json accepts these query parameters. Filters are operators inside q; they combine (all must hold).
| Param | Meaning |
|---|---|
q | The query: words, and the operators of the search page (intitle:, from:, after:, before:, /regex/, …). Required. |
format=json | Return JSON instead of HTML. |
limit, o | Page size (default 50, max 1000) and offset. |
Returns the total hit count and the first match for “pgbouncer” in pgsql-announce. Each result has subject, from, date, message_id, thread_url, message_url, and a BM25 relevance score.
Search a different inbox; limit and o (offset) page through results. Drop &format=json to render the same query as a browseable HTML page.
Restrict the match to the Subject header (intitle:, also subject:). Useful when the body is noisy or you only care about announcement-style headlines.
Match a fragment of the From header (display name or address).
The message as JSON: headers, the decoded body and its attachments. If you do not know the list, https://pg.ddx.io/id/<message-id> redirects to it.
Q1 2024 only. after: includes the day, before: does not. Dates combine with any other operator.
A PostgreSQL regular expression between slashes, here on the subject (intitle:/relea[sz]e/): it matches both “release” and “releaze”. URL-encode /, [, ], + and the like.
Standard Atom feed of recent messages. Poll no more often than once every 5 minutes — the feed only changes when new mail arrives, and aggressive polling wastes bandwidth on both sides. Most feed readers default to 30–60 minutes, which is appropriate.
Returns the original message bytes, including all headers and the unmodified body. URL pattern is /m/<inbox>/<message-id>/raw. Pipe into your own MIME parser or save to disk for archival.
URL pattern is /m/<inbox>/<begin>-<end>.mbox.gz, where begin and end are public-inbox v2 article numbers. Range is capped at 10000 messages per request. Use this to seed a local mbox archive without cloning the full git repo.
Public-inbox v2 layout. Run your own indexer or mirror locally for offline analysis. (Reminder: this is the mailing-list archive, not upstream PostgreSQL source.)
Tips
- JSON or HTML: the same URL serves both — toggle with
&format=json. - Paging: add
?limit=N&offset=M. Default limit is 50, max 1000 (server-enforced). - Browse first: visit
https://pg.ddx.io/in a browser to see the full inbox list and pick one. - Structured tools: for symbol search, call graphs (get_callers and get_callees), commitfest queries, etc., use the MCP server (Section 1) — those are JSON-RPC tool calls, not REST endpoints.
6. GraphQL — Structured Queries
Try it live: the GraphQL explorer runs queries against the real endpoint and has a Docs pane generated from the schema itself.
The GraphQL endpoint exposes the same data as the REST API but lets the caller specify which fields they want. Useful when you'd otherwise be making N requests in a loop and stitching JSON together.
Endpoint: POST https://pg.ddx.io/api/graphql (Content-Type: application/json). GET with a ?query=… parameter also works for read-only queries. There is no /<inbox>/graphql URL — every Query field takes an explicit inbox: String! argument instead.
Interactive explorer: open https://pg.ddx.io/api/graphql in a browser and you get the GraphiQL UI with schema introspection, autocomplete, and query history. Programmatic clients (curl, fetch with Accept: application/json) keep getting the JSON API as before.
Schema
Top-level Query fields:
inbox(inbox: String!)— metadata: name, description, addresses, message count, last-modified.messages(inbox: String!, limit: Int = 25)— recent messages.message(inbox: String!, mid: String!)— one message by Message-ID, including body and attachments.thread(inbox: String!, mid: String!)— full thread rooted at a Message-ID.search(inbox: String!, query: String!, limit: Int = 50, offset: Int = 0)— BM25 search; results carry arelevancescore.
Usage
Returns both the inbox header and the first three search hits in one round trip. Compare with the REST API, which would require two calls.
Replace the mid value with a real Message-ID from the inbox you care about (you can copy one from a REST search response or the HTML view). Add body to the messages selection set if you also want the message text.
Tips
- Errors are inline. A query that hits a missing inbox or a bad Message-ID still returns HTTP 200 with the failure inside an
errorsarray. Check bothdataanderrorsin your client. - The
inboxargument is required on every field. The endpoint is not scoped to any inbox; the schema deliberately surfaces the inbox name in each query so a single GraphQL request can span multiple inboxes by aliasing. - 1 MiB request body cap. Plenty for normal queries; chunk large mutations (none are exposed today — this is a read-only API).
7. MCP — For AI Agents
The MCP server gives an agent the mailing lists back to the 1990s, the full
postgres history, commitfest and buildfarm as tools it can call
rather than pages it has to scrape. It does retrieval; your own model writes the
answer, citing what the tools returned.
Endpoint
MCP Streamable HTTP (JSON-RPC 2.0). No key, no account. A plain
GET of that URL returns a short JSON description of the server; clients
POST to it. /mcp-tools is not an endpoint — it is the
human-readable reference for the tools.
Setup
Claude Code
claude mcp add --transport http pg-ddx https://pg.ddx.io/mcp
Codex
codex mcp add pg-ddx --url https://pg.ddx.io/mcp
Or in ~/.codex/config.toml:
[mcp_servers.pg-ddx] url = "https://pg.ddx.io/mcp"
GitHub Copilot CLI
copilot mcp add --transport http pg-ddx https://pg.ddx.io/mcp
This writes ~/.copilot/mcp-config.json:
{"mcpServers": {"pg-ddx": {"type": "http",
"url": "https://pg.ddx.io/mcp", "tools": ["*"]}}}
VS Code
In .vscode/mcp.json (VS Code uses servers, not mcpServers):
{"servers": {"pg-ddx": {"type": "http", "url": "https://pg.ddx.io/mcp"}}}
Cursor
In ~/.cursor/mcp.json:
{"mcpServers": {"pg-ddx": {"url": "https://pg.ddx.io/mcp"}}}
Zed
In settings.json:
{"context_servers": {"pg-ddx": {"url": "https://pg.ddx.io/mcp"}}}
OpenCode
In opencode.json:
{"$schema": "https://opencode.ai/config.json",
"mcp": {"pg-ddx": {"type": "remote", "url": "https://pg.ddx.io/mcp", "enabled": true}}}
Any other client
MCP Streamable HTTP at https://pg.ddx.io/mcp; clients that only speak the
legacy SSE transport use https://pg.ddx.io/mcp/sse. No key, no account.
/mcp lists the core tools; every tool (129) is at /mcp/full.
A retrieval loop that works
retrieve_context {"query": "...", "token_budget": 4000}— start here: cited passages that fit the budget, one per thread, orfound: falsewhen the archive does not discuss the question.hybrid_search {"query": "..."}— ranked hits, each with anexcerptof the author's own words, so you can judge a hit without opening it.get_message {"message_id": "...", "body_only": true}— one message in full.get_thread {"message_id": "...", "include_bodies": false}— an outline of the whole thread; then fetch the messages that matter. Threads are paged (20 messages per call).git_searchandcommit_history— from a discussion to the commit it produced, and back.
Omit inbox on a mail search and it searches every list; on get_message/get_thread it defaults to pgsql-hackers; omit
repository and it is postgres.
All tools and their arguments →
Ready-made skills
Pre-built, CC0 (public-domain) agent skills for Claude, Kiro, Pi, and any MCP-aware agent — written once for every agent (no per-agent branches). They are grouped by how you work with Postgres (query user, DBA, design overseer, replication, triage, core/extension developer), plus tooling and generic agent skills, and include a 41-rule PostgreSQL best-practices library. Browse the full catalogue at gburd.github.io/postgres-agent-skills, or clone the repository into your agent's skills directory:
Then point the agent at AGENTS.md at the repo root. It's a shared
community resource — issues and PRs welcome at
github.com/gburd/postgres-agent-skills.
Tips
- Authentication: none. Public and read-only.
- Rate limits: light, per client. A throttled request gets
HTTP 429; back off and retry. - Bulk copies: please clone the list rather than fetching every message through tools. See agents.txt.
WHICH SHOULD I USE?
| Use Case | Best Endpoint | Why |
|---|---|---|
| Browse discussions like email | IMAP | Familiar email client, threading, search built-in |
| Download archive to computer | POP3 | Keep local copy, work offline |
| Old-school newsreader fan | NNTP | Classic protocol, powerful newsreaders available |
| Build tools / analyze history | Git | Version control, scripting, full history |
| Quick searches / dashboards | HTTP/REST | Simple API, JSON responses, easy integration |
| AI agent integration | MCP | Purpose-built for AI, structured queries, 100+ tools |
FINDING THE BERKELEY POSTGRES HISTORICAL ARCHIVE
pg.ddx.io mirrors the University of California, Berkeley POSTGRES
project (1986–1995) — the academic predecessor of
PostgreSQL — at /legacy/. The
upstream archive at dsf.berkeley.edu/postgres.html
has been effectively static since 1999; this mirror exists so the bytes
survive if the upstream ever disappears.
Mailing list (1991–1997)
The original UCB POSTGRES hackers list, including design-era discussions from Stonebraker and the original implementors:
- Browse:
/m/legacy/ - Search:
/m/legacy/?q=stonebraker - Atom feed:
/m/legacy/new.atom - Whole-archive mbox:
/legacy/mail-archive/(64 monthly tarballs plus a single aggregatedall-messages.mboxfor grep) - Programmatic via MCP:
search_messages(inbox="legacy", query="vacuum")
Project documentation, papers, FAQ
- Academic papers (Stonebraker et al., 1986–1995):
/legacy/papers/— both PostScript andps2asciitext. Includes "Design of POSTGRES", "Implementation of POSTGRES", "Rules, Procedures and Caching", and ten more. - FAQ (1997):
/legacy/postgres-v4r2/postgres.faq - Per-OS port READMEs and release notes:
/legacy/postgres-v4r2/ - contrib applications (CONCERT trouble-ticket sample, Onyx 4GL, etc.):
/legacy/postgres-v4r2/contrib/ - Manifest with per-artifact
sha256:/legacy/manifest.json - Bit-perfect snapshot of the upstream index page:
/legacy/upstream-snapshot.html
The archive contains the CONCERT Trouble Ticket System (a contrib sample application), not bug tickets — UCB never used a bug tracker for the project. Patch discussions and design exchanges are in the mailing list.
Source code
- Latest official release (POSTGRES 4.2, 1994): browse extracted tree at
/legacy/extracted/or grab the tarball/legacy/postgres-v4r2/postgres-v4r2.tar.Z. - Earlier releases (v3.1, v4.0, v4.0r1, v4.1 incl. Sequoia 2000 fork, v4.2 alpha/beta) and the Postgres95 0.01–1.02 transition releases that became modern PostgreSQL:
/legacy/oldpost/ - Unofficial community ports and the unofficial port list:
/legacy/oldpost/unofficial-ports/,UNOFFICIAL-PORT-LIST. - Code search via MCP:
search_symbols(repository="ucb-postgres-v4r2", query="parser")andgit_log(repository="ucb-postgres-v4r2"). The repositories areucb-postgres-{v3r1,v4r0,v4r0r1,v4r1,v4r2}(plus the v4r1 ports, v4r2 alpha/beta and RCS) anducb-postgres95-{0.01..1.02}; browse them at/c/ucb-postgres-v4r2/.
Before POSTGRES: University INGRES
INGRES (UC Berkeley, 1973–1988) preceded POSTGRES. Its archive at
s2k-ftp.cs.berkeley.edu/ingres/
is mirrored at /legacy/ingres/:
- INGRES on Usenet, 1985–1995:
/m/ingres/, every thread of comp.databases.ingres, comp.databases and net.database that names University or Berkeley INGRES, QUEL or EQUEL (1,878 articles), with headers as Usenet gave them. Built from the Google Groups Usenet export on the Internet Archive and the three articles in the Berkeley mirror. Also over NNTP/IMAP as groupingres, andsearch_messages(inbox="ingres", query="equel"). On /search, pick Archive: University INGRES. - INGRES 8.9 (1988), the last Berkeley release:
vax-bsd/ingres89.tar.Z, unpacked underextracted/. - Every manual page, setup guide and release note as text, including "The Design and Implementation of INGRES" (1976):
/legacy/ingres/text/. Search them as documentation versionucbingres:search_docs(query="decomposition", versions=["ucbingres"]). - The code:
search_symbols(repository="ucb-ingres-8.9", query="decomp"), browsable at/c/ucb-ingres-8.9/.ucb-ingres-8.9-linuxhas the 1993 Linux/386BSD port as a second commit, so its diff shows the port.
TROUBLESHOOTING
IMAP won't connect
- Check port: 993 (SSL) is standard, 143 (STARTTLS) also works
- Verify hostname:
imap.pg.ddx.io(no www, no .com) - Username/password: Can be anything (we don't authenticate)
- Firewall: Some firewalls block IMAP. Use 993 (SSL) instead of 143
No folders appear after connecting
- Check "Show all folders" or "List all folders" in your client
- Might need to refresh/re-subscribe
- Try subscribing to specific list:
pgsql-general
HTTP search returns no results
- Try simpler query:
?q=queryinstead of complex syntax - Check URL encoding: spaces should be
+or%20 - Use
jq .to see response structure
Git clone too slow
- Use shallow clone:
git clone --depth 10 ... - Or clone only recent commits with:
git log -p --max-count=100
OPENAPI 3.1 SPECIFICATION
Every public HTTP endpoint described on this page is also documented in a single OpenAPI 3.1 document — search, single-message JSON, raw RFC 822, threads, Atom/RSS feeds, inbox metadata, the help/color/mirror text pages, the git smart-HTTP transport, /healthz, and the MCP JSON-RPC envelope.
The spec is served by the service itself at /openapi.yaml and rendered as an interactive Swagger UI page at /api.html. Both are kept in lock-step with the service's route table.
Usage
Loads Swagger UI from a CDN and points it at the live spec. Each endpoint has a “Try it out” button that issues real requests against the production service.
Useful for embedding in your own docs site, validating with spectral lint, or generating clients with openapi-generator.
Replace python with any of the supported targets (typescript-fetch, go, rust, etc.). The generated client speaks JSON only — for the HTML, Atom, RSS, and git smart-HTTP routes you still need a regular HTTP client.
Tips
- Same URL, two formats: the search endpoint defaults to HTML; add
&format=jsonfor the JSON envelope. The OpenAPI document only describes the JSON variant. - Pagination: follow
Linkheaders (RFC 8288rel="next"/rel="prev"/rel="first") instead of recomputing offsets. The body'shas_moreis also reliable. - MCP for agents: the
POST /mcp/entry in the spec describes the JSON-RPC envelope. AI agents should use a real MCP client library; the OpenAPI is there mostly for debugging.
QUESTIONS?
Something not working as described? Get in touch. We want these endpoints to work perfectly.