Skip to content

ppg-proxy series - proposal doc #7996

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
pcan wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

ppg-proxy series - proposal doc #7996

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
11e79c1
ppg-proxy series - proposal doc
pcan Jul 2, 2026
da3e09b
adding fakepg point
pcan Jul 2, 2026
0b8c416
fix numbering
pcan Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions apps/blog/proposals/ppg-proxy-series.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# ppg-proxy blogposts

A proposal for a series of blogposts showing how we manage prisma postgres connectivity, discussing about the ppg-proxy, what problems it resolves, how it evolved, the challenges whe faced over time, and the revamp that we've been doing as a result.


# 1 ppg-proxy intro: what, why and how

@ankur-arch ankur-arch Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice start!


1. What is Prisma Postgres, how/where it's deployed, what are the common access pattern to postgres in multi tenant settings (very briefly, we talked about microvms/unikernels extensively already)
2. justifying the need for a "proxy" or "gateway": what responsibilities it takes:
- route postgres traffic to the target databases, preserving tenant isolation
- better auth scheme, api-key based, rotation without touching db credentials
- billing & holds based on queries, ingress/egress traffic, backup traffic, etc
- unified throttling, observability, access logging
Comment on lines +9 to +13

@ellotheth ellotheth Jul 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The gateway will also give us a mechanism to cordon of the PPg hosts entirely from public traffic, which will be a huge security/maintenance win.

3. Chanllenges and how we overcome them
- the routing data distribution: choices and tradeoffs
- The postgres binary protocol (message-oriented) and the open source libraries landscape
- buffering and the noisy neighbor problem: when horizontal scaling hides but doesn't solve the problem
- biting the bullet and implementing a full end-to-end low level streaming protocol capability, while still allowing selective messages inspection (e.g. error reporting or query counting)
Comment on lines +14 to +18

@ellotheth ellotheth Jul 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you want to put our logging-to-stdout adventure in here too or nah 😆

@pcan pcan Jul 2, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

YES YES YES!!!!

4. What's next
- the need for a more serverless-friendly entry point
- per-tenant dedicated connection pooling

# 2 ppg-proxy for serverless - part 1: Connection Pooling

1. What are serverless workloads, how they compare to traditional stateful workloads, why they are convenient from a developer perspective, what are their limitations
- introducing stateless execution environment (e.g. aws Lambda) vs a traditional VM/bare metal server solution
- dissonance between serverless environment and "legacy" technologies such as RDBMs and their long-running persistent connection & transaction model, normally adopted in _persistent_ running environments such as ec2
- lack of support for native tcp/tls client connectivity (sometimes)
- possible approaches to bridge the gap: dedicated pooler, http/ws protocol wrapper, or pooler-as-a-service (accelerate, which does both things with its limitations)
2. Tackling the throwaway-connection issue with pooling
- what's connection pooling, what's its main goal (to relieve pressure on the db for connection creation/teardown)

@ellotheth ellotheth Jul 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another fun one here could be something about its non-goals, like query performance or latency, and why adding a pooler will actually slow you down sometimes.

@pcan pcan Jul 2, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good point!!!

- what are the pooling types/levels (statement, transaction, connection)
- how each approach "reuses" connections (at a high level, query-start-query-end boundaries, transaction detection)
- how Prisma Postgres approached the problem (per-db pgbouncer), what are the current limitations when used in conjunction with ppg proxy
3. What's next
- Anticipating part 2: not all environments support direct TCP/TLS
- How a http/ws API could fill the gap (exploring 2 approaches, pg-protocol wrapper and its limitations vs a bespoke api, without anticipating too much)


# 3 ppg-proxy for serverless - part 2: HTTP/WS API & driver

1. Where we left: tackling the lack of support for tcp/tls and the need of a HTTP-friendly alternative.
- How the industry usually handles this: bare-metal pg protocol wrapper vs bespoke HTTP/WS API.
- The _"driver"_ is not the challenge, the API is: Neon serverless driver as a case study, a deep dive in its protocol mechanics
- how Neon approach represents a _blast from the past_ for us (QE anyone?) and why it's a poor/short-sighted model. Lessons learned with Data Proxy & Accelerate (noisy neighbor problem, artificially limiting query duration and req/res body size to manage scaling)
2. Prisma Postgres Serverless API
- How we overcame the limitations of a Neon-serverless-driver/Accelerate QE model: biting the bullet and implementing a full end-to-end streaming mechanism: basic idea
- The full end-to-end streaming chain: ingress layer, encoding/decoding, framing layer & flow control, database session & sub-message level streaming
3. Prisma Postgres Serverless Driver
- Unlocking the same flexibility on the client side: streaming as a _first class citizen_, although optional: CollectableIterator
- Advanced features unlocked _for free_: postgres query batching and pipelining, the difference with the traditional request/response model, how this blends seamlessly with the client driver API
- Future state: a driver for every language! Sketching an example of a JDBC driver.


# 4 ppg-proxy revamped

1. How we got here and why
- Connection Pooler as a dedicated components: current limitations and the impact on serverless connectivity (pgbouncer as a good _quick win_, but now we have to do it seriously).
- What is needed to _embed_ pooling within the ppg-proxy. Clean/busy/dirty connection state & transaction tracking, pg protocol-related challenges: we need a centralized protocol handler for these.
- The big blocker. Postgres TCP proxy (raw pg protocol) vs serverless HTTP/WS API: two sub-systems, two (almost) independent stories and timelines, EA/GA phases and architectural dissonances: the toll of a fast paced evolution: missing or duplicated building blocks, challenges/risks and opportunities with AI-accelerated re-architecting
2. Towards a unified pipelining model for TCP & Serverless
- Connection lifecycle and protocol handling are separate problems, and how this helps shaping the new architecture.
- The BIG challenge: finding the boundary contract between the two, _while_ keeping the streaming promise.
- Step 1: Unifying wire protocol handling: from a mixed pgproto3/bespoke set of utilities to a well designed, cohesive raw pg protocol library with first-class streaming support.
- Step 2: The core pg-protocol pipeline
- Step 3: Serverless API & TCP terminal adapters
- A detour on fakepg and why we need it (testing connectivity issues, or just sequences of pre-baked messages)
3. What's next
- Connection Pooling as a 2-facet system: the protocol sensing and the connection factory
- The plan to support advanced pooling features (first we do query detection, transaction boundary and then detecting unsupported statement as the last thing)

@ankur-arch ankur-arch Jul 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pcan here's some feedback from me and GPT:

High-level structural feedback

  • The series has strong raw material, but the structure is currently too implementation-led. It reads more like an internal architecture history than a public-facing blog series.

  • The reader needs a clearer “why should I care?” arc before getting deep into protocol internals.

  • Start with the developer/customer problem, not ppg-proxy.

    • “ppg-proxy intro: what, why and how” is accurate, but not very compelling as the entry point.
    • A stronger frame would be something like: “How Prisma Postgres handles secure, scalable database connectivity.”
    • Then introduce ppg-proxy as the system that makes that possible.

Narrative arc

Right now, the progression feels like:

proxy → pooling → HTTP/WS → revamp

A stronger arc would be:

developer pain → platform constraints → connectivity architecture → serverless access → protocol/streaming design → unified future architecture

That gives the series a clearer reader-facing story instead of making it feel like a chronological engineering history.

Audience clarity

The intended audience is currently unclear. Some parts speak to app developers, some to infra engineers, and some to Prisma employees.

I’d decide whether the series is primarily for:

  • Prisma users who want to understand Postgres connectivity
  • backend/platform engineers interested in architecture
  • database/protocol nerds

My recommendation: target senior backend/platform engineers, but always anchor each post in user-visible product value.

Series-level recommendations

  • Each post needs a sharper promise. Before the outline, add one sentence per post answering: “After reading this, the reader will understand X.”

  • Separate product value from engineering war stories.

    • The logging-to-stdout adventure, noisy neighbor issues, protocol rewrites, and fakepg are great.
    • But they should only appear where they support the main reader-facing point.
    • Otherwise, the series risks feeling like an internal postmortem.

  • The proposal should define success for the series:

    • Is this meant to build trust in Prisma Postgres?
    • Explain serverless connectivity?
    • Recruit infra talent?
    • Support launch messaging?

  • The structure should change depending on that goal.

Post 1: ppg-proxy intro

  • The first post is overloaded.
  • It tries to explain Prisma Postgres, multi-tenancy, routing, auth, billing, throttling, observability, protocol challenges, buffering, noisy neighbors, and future plans.
  • That is too much for an intro.
  • Keep the intro focused on the gateway’s purpose and the core problems it solves.

Post 1 should establish the system boundary clearly:

  • Is ppg-proxy a gateway?
  • A TCP proxy?
  • An auth layer?
  • A routing layer?
  • A metering point?
  • An observability boundary?
  • All of the above?

The outline lists responsibilities, but the reader needs a mental model early.

Also, the security angle should be promoted. The point about cordoning off Prisma Postgres hosts from public traffic is a big value point. That should not be a side note. It belongs in the main structure of post 1 because it makes the gateway feel necessary, not incidental.

The billing/metering point also needs careful placement. “Billing & holds based on queries, ingress/egress traffic, backup traffic” is important internally, but for an external audience it may feel vendor-centric. I’d frame it as:

  • accurate usage visibility
  • fair resource accounting
  • abuse protection
  • operational safety

Post 2: serverless connection pooling

  • Post 2 is the clearest structurally.

  • The connection pooling post has a strong shape already:

    • problem
    • explanation
    • tradeoffs
    • Prisma Postgres approach

This is probably the best-structured outline in the proposal.

I’d add explicit non-goals to the pooling post. The review comment is spot on:

  • pooling does not magically make queries faster
  • pooling can add latency in some cases
  • pooling mainly helps with connection lifecycle pressure, not query performance itself

That will make the post more trustworthy.

Also, avoid making the serverless intro too generic. “What are serverless workloads?” can easily become a 101 section readers skip. Keep it short and tie it directly to database connectivity:

  • short-lived processes
  • connection storms
  • missing TCP support
  • transaction semantics
  • persistent database connections vs ephemeral compute

Post 2 and Post 3 overlap

Post 2 and Post 3 both talk about serverless constraints and bridging TCP/TLS gaps.

I’d make the distinction explicit:

  • Post 2: connection lifecycle pressure
  • Post 3: transport/protocol limitations

That separation will help the series feel intentional instead of repetitive.

Post 3: HTTP/WS API and driver

  • Post 3 currently sounds too competitor-comparative.

  • The Neon case study could be useful, but “poor/short-sighted model” reads unnecessarily spicy and may distract from Prisma’s own design.

  • A better structure would be:

    • explain common industry approaches
    • describe their tradeoffs
    • show why Prisma chose a streaming-first design

Be careful with Data Proxy / Accelerate framing too. Lessons learned from past Prisma systems are valuable, but avoid making existing Prisma products sound broken. I’d frame it as:

What we learned from operating query engines and managed proxies at scale.

Post 3 has the strongest technical hook: streaming. That should be the centerpiece.

The outline should lead with:

  • why request/response breaks down
  • why streaming matters
  • what a streaming-first serverless Postgres API unlocks

The driver section risks becoming too broad. “A driver for every language” and JDBC examples are interesting, but they may belong in a future-looking closing section, not a major structural pillar. Keep the post centered on the API/driver contract.

Post 4: ppg-proxy revamped

  • Post 4 is too dense and too internal.
  • It contains many important pieces, but it currently reads like an architecture planning document.
  • For a blog post, I’d split or simplify it.
  • The reader needs fewer moving parts and a more explicit payoff.

Post 4 needs a clearer before/after structure:

  • Before: TCP proxy and serverless API evolved separately.
  • Problem: duplicated protocol handling, inconsistent lifecycle logic, harder pooling.
  • After: unified protocol pipeline with terminal adapters.
  • Benefit: better pooling, testing, streaming, maintainability, and future features.

The current outline also buries one of the most interesting architectural ideas:

Connection lifecycle and protocol handling are separate problems.

That is a strong conceptual takeaway and should be promoted earlier in Post 4.

A few specific notes:

  • “AI-accelerated re-architecting” feels out of place unless it is central to the post. It risks aging badly and distracting from the actual architecture.
  • fakepg should be a sidebar, not a main detour. It sounds fascinating, but structurally it can derail the post. Use it as a concrete testing example after the main architecture is already clear.

Titles

The titles need work. They are descriptive but not reader-oriented.

“ppg-proxy for serverless - part 1” feels internal. I’d use titles that describe the problem/value instead:

  • Why Prisma Postgres needs a gateway
  • Why serverless apps are hard on Postgres connections
  • Designing a streaming API for serverless Postgres
  • Unifying TCP and serverless connectivity in Prisma Postgres

Suggested repeated structure

The outline would benefit from a repeated structure across posts:

  1. User/platform problem
  2. Why the obvious solution breaks down
  3. Prisma’s approach
  4. Tradeoffs and lessons learned
  5. What this unlocks next

This would make each post easier to write and easier to follow.

Article endings

Each post should end with a concrete takeaway, not just “what’s next.”

The “what’s next” sections are useful, but each article should close with what the reader should now understand.

Jargon

There is a lot of jargon without staged explanation.

Terms like these are fine for the audience, but they should be introduced progressively:

  • ingress layer
  • framing
  • flow control
  • terminal adapters
  • clean/busy/dirty connections
  • transaction boundary detection
  • pgproto3
  • sub-message streaming

Overall recommendation

Keep the four-part series, but reframe it from:

Here is how ppg-proxy evolved.

to:

How Prisma Postgres is building a secure, serverless-friendly connectivity layer for Postgres.

That makes the series more valuable to external readers while still giving engineering enough room to go deep.

Loading