From 091706e06893c1f6b26e7cbba48c6a9ab0b9ab70 Mon Sep 17 00:00:00 2001 From: Vaibhav Srivastav Date: Tue, 14 Apr 2026 16:47:25 +0100 Subject: [PATCH] Re-add Neon Postgres plugin --- .agents/plugins/marketplace.json | 12 + .../neon-postgres/.codex-plugin/plugin.json | 44 ++++ plugins/neon-postgres/.mcp.json | 8 + plugins/neon-postgres/assets/neon-small.svg | 3 + plugins/neon-postgres/assets/neon.jpg | Bin 0 -> 3022 bytes .../neon-postgres-egress-optimizer/SKILL.md | 212 +++++++++++++++++ .../agents/openai.yaml | 15 ++ .../assets/neon-small.svg | 3 + .../assets/neon.jpg | Bin 0 -> 3022 bytes .../skills/neon-postgres/SKILL.md | 217 ++++++++++++++++++ .../skills/neon-postgres/agents/openai.yaml | 15 ++ .../neon-postgres/assets/neon-small.svg | 3 + .../skills/neon-postgres/assets/neon.jpg | Bin 0 -> 3022 bytes 13 files changed, 532 insertions(+) create mode 100644 plugins/neon-postgres/.codex-plugin/plugin.json create mode 100644 plugins/neon-postgres/.mcp.json create mode 100644 plugins/neon-postgres/assets/neon-small.svg create mode 100644 plugins/neon-postgres/assets/neon.jpg create mode 100644 plugins/neon-postgres/skills/neon-postgres-egress-optimizer/SKILL.md create mode 100644 plugins/neon-postgres/skills/neon-postgres-egress-optimizer/agents/openai.yaml create mode 100644 plugins/neon-postgres/skills/neon-postgres-egress-optimizer/assets/neon-small.svg create mode 100644 plugins/neon-postgres/skills/neon-postgres-egress-optimizer/assets/neon.jpg create mode 100644 plugins/neon-postgres/skills/neon-postgres/SKILL.md create mode 100644 plugins/neon-postgres/skills/neon-postgres/agents/openai.yaml create mode 100644 plugins/neon-postgres/skills/neon-postgres/assets/neon-small.svg create mode 100644 plugins/neon-postgres/skills/neon-postgres/assets/neon.jpg diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 4adc6d12..7477ad61 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -341,6 +341,18 @@ "authentication": "ON_INSTALL" }, "category": "Coding" + }, + { + "name": "neon-postgres", + "source": { + "source": "local", + "path": "./plugins/neon-postgres" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Coding" } ] } diff --git a/plugins/neon-postgres/.codex-plugin/plugin.json b/plugins/neon-postgres/.codex-plugin/plugin.json new file mode 100644 index 00000000..934c4ada --- /dev/null +++ b/plugins/neon-postgres/.codex-plugin/plugin.json @@ -0,0 +1,44 @@ +{ + "name": "neon-postgres", + "version": "1.0.0", + "description": "Manage Neon Serverless Postgres projects and databases with the neon-postgres agent skill and the Neon MCP Server", + "author": { + "name": "Neon", + "email": "andre@neon.tech", + "url": "https://neon.com" + }, + "homepage": "https://neon.com/docs/ai/neon-mcp-server", + "repository": "https://github.com/openai/plugins", + "license": "Apache-2.0", + "keywords": [ + "neon", + "postgres", + "serverless", + "database", + "mcp", + "sql" + ], + "skills": "./skills/", + "mcpServers": "./.mcp.json", + "interface": { + "displayName": "Neon Postgres", + "shortDescription": "Manage Neon Serverless Postgres projects and databases", + "longDescription": "Use the Neon Postgres plugin to create and manage Neon Serverless Postgres projects and databases. Includes the Neon MCP Server for project and database management, and the neon-postgres skill with guides on connection methods, branching, autoscaling, Neon Auth, and more.", + "developerName": "Neon", + "category": "Coding", + "capabilities": [ + "Interactive", + "Write" + ], + "websiteURL": "https://neon.com", + "privacyPolicyURL": "https://neon.com/privacy-policy", + "termsOfServiceURL": "https://neon.com/terms-of-service", + "defaultPrompt": [ + "Use Neon to create a new Serverless Postgres database for my project and help me connect to it." + ], + "brandColor": "#37C38F", + "composerIcon": "./assets/neon-small.svg", + "logo": "./assets/neon.jpg", + "screenshots": [] + } +} diff --git a/plugins/neon-postgres/.mcp.json b/plugins/neon-postgres/.mcp.json new file mode 100644 index 00000000..5431293b --- /dev/null +++ b/plugins/neon-postgres/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "neon": { + "type": "streamable_http", + "url": "https://mcp.neon.tech/mcp" + } + } +} diff --git a/plugins/neon-postgres/assets/neon-small.svg b/plugins/neon-postgres/assets/neon-small.svg new file mode 100644 index 00000000..013e8c8d --- /dev/null +++ b/plugins/neon-postgres/assets/neon-small.svg @@ -0,0 +1,3 @@ + diff --git a/plugins/neon-postgres/assets/neon.jpg b/plugins/neon-postgres/assets/neon.jpg new file mode 100644 index 0000000000000000000000000000000000000000..d9467e2f5a97eab8faf17cbfd242ca771b31ab8a GIT binary patch literal 3022 zcmcIldpy+J7T@z?P^6MjMo~I+a}qr~nyWIRB;=Jel~WZGj#DfC%sybwEHzs0dh%(fBf^U={(~ntf&>#c1Zw>UYwxVmli z^z!!c-R-w0_&~_PP*r?77R?SFT>mxt^PMui$>+zaBg+ zdQ?{atfG=t^}M?N^_zyqrskH`j!t%0cTaC${{WZwi9a$rCJ>4yc%feTix&F+kGzyo zURXRHhnJn;g~5hS5Ld<%<}H<(ZecIGGjPUy!^6axYf`iBmda@_bKt1#3aXQzrDN2w zfIC5LlG)!Q7X4Gqz7YG$>n&Idu#>=Hu{Z(_ha<=kP{Mek_}athP_Yrr-%xnyB0n1aKg$%In|WWcXpldz?sWA;<-jDg&h_vH@~R+*kL z$axxZ*E+jrSuv@iyFq2K*D9}u#@v1$*#_~3K)7Ht($vP1#_IQl3)!Po2u?c5N+RDO zeQSynZk=ZF^A(XQrjnEhLH{CH%dZ}{8>K*yl1Y;m<)d1iKTa&#hs>dSK%o7IM1IcL zS7)h`D@mSdZwdbWgc-05gbPGX<9Ct1hWzSt5@$g-1Uk&E5F9j+s22(y-Ry#eF_q}v zX4gR=J5W>4XhEdbTSy~gfe>WLi!_Vrk_-sC(k&pMhLS|n^0Njl?}}D@yVJU#-Rbe_ zJhx=fm9}9^h#@62$V&Vvpxa_udYX5IcgU33U(G8_il+$z#w|SP0j@=y_C$}5H&?&b zt5~Xa|DRQK9k!Mi&pkO)|0B)x1#Nuy@Zv7FtW(}@>$Os@U&*XF-*HjDtmo8)K5|%u z{Q&cQ*y-JukNLjV+`xSywT>#34pBwMG~P9)Q}HU~xj`edEfE6Bt*9-Hj_;&9xJ)U< z2q_g6@N<3$Q~pKr50R|f8XwZ-SK!X|bQc8X#vc`bSnd$fN1S@$a5Z0xW7^d38*ApBC3tIX>$&#) z??)eclfyK?i4xz7R^g3?MH0_av#^Ah{Xt@5XRgF0qYF);In1t%LF&f}2(q1-dbAOD zc82(*geGZb^7k}#+pZfU&;6gA{rdm!?3Sn*;)R8R^sIs7X-4XC1tgtb;(pb5p*8De z>k}GUs!lX!p@(BS1bsfmFC-_)>?UUjZYQCIhUI!SSL|P^<}t-*|DEO|e;D>KJ0n8! z1&9;pRnC&sn5hBtKE6USUix zR_&uI^9yKE#ZK?&yqs+^+h(w|xX(XO&qbMX6d!XSaP`-9OS#@QCo%f=l@r9$m3?%x zTDE6>=PQNEuGw+N%B>&jetf>~31h@3vapkRR9*KO5-n=XzBWB=-8{F;JL4%!65e?- z9I2TNL2oxdEl76t_t{;)A9uL!Q2)6c>&Fc9iU=pi<(Ybg*?yH~`2`J+rMmrgLrk=u zekV7WD!Gp3NmR`yQuAh%U7w_nM_K9W_GL4hTv~k_9CA28|hR)Va~< zmLA*HB>m07w``AMPeRS_CO*aF%Xc=hIQdh3@4X1TQ%NyD@a35tU8&U&^*fQgtr>~pC8Ef(+c)-F zCmqttU6)7Ek|EK_>(yx9mzBmfy%$GvJ?9Sh|B@q#cUt(zP#O z8tsIIVHu^zgPcHULUa7Xr6t){Fx%b0OfCA5FD$Fyt6 z9WDYFX&9O!$W#*Nh8T^h8QPJU@lO?xEhe=zBf>FKk!IMpzv?$QB%NLV#FW76&l}JQ z+SJq5f|NZeds^P1E4slPOW|#$1rO3m1d3Yvsx@-v;Y(Qe?JZS&`Lmri3~HF$)Vpg4 zoaqZ4ZYSe@k$t17*EVy;%4_F-oAV$x!uX27abw1Yx?Mc~q-XbHhtw(0akb%!4R0FU c?TU2AKZpk!WaARb>XTMhF16NqM1n1U0w$fX&;S4c literal 0 HcmV?d00001 diff --git a/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/SKILL.md b/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/SKILL.md new file mode 100644 index 00000000..174027a6 --- /dev/null +++ b/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/SKILL.md @@ -0,0 +1,212 @@ +--- +name: neon-postgres-egress-optimizer +description: >- + Diagnose and fix excessive Postgres egress (network data transfer) in a codebase. + Use when a user mentions high database bills, unexpected data transfer costs, + network transfer charges, egress spikes, "why is my Neon bill so high", + "database costs jumped", SELECT * optimization, query overfetching, + reduce Neon costs, optimize database usage, or wants to reduce data sent + from their database to their application. Also use when reviewing query + patterns for cost efficiency, even if the user doesn't explicitly mention + egress or data transfer. +--- + +# Postgres Egress Optimizer + +Guide the user through diagnosing and fixing application-side query patterns that cause excessive data transfer (egress) from their Postgres database. Most high egress bills come from the application fetching more data than it uses. + +## Step 1: Diagnose + +Identify which queries transfer the most data. The primary tool is the `pg_stat_statements` extension. + +### Check if pg_stat_statements is available + +```sql +SELECT 1 FROM pg_stat_statements LIMIT 1; +``` + +If this errors, the extension needs to be created: + +```sql +CREATE EXTENSION IF NOT EXISTS pg_stat_statements; +``` + +On Neon, it is available by default but may need this CREATE EXTENSION step. + +### Handle empty stats + +Stats are cleared when a Neon compute scales to zero and restarts. If the stats are empty or the compute recently woke up: + +1. Reset the stats to start a clean measurement window: `SELECT pg_stat_statements_reset();` +2. Let the application run under representative traffic for at least an hour. +3. Return and run the diagnostic queries below. + +If the user has stats from a production database, use those. If they have no access to production stats, proceed to Step 2 and analyze the codebase directly — code-level patterns are often sufficient to identify the worst offenders. + +### Diagnostic queries + +Run these to identify the top egress contributors. Focus on queries that return many rows, return wide rows (JSONB, TEXT, BYTEA columns), or are called very frequently. + +**Queries returning the most total rows:** + +```sql +SELECT query, calls, rows AS total_rows, rows / calls AS avg_rows_per_call +FROM pg_stat_statements +WHERE calls > 0 +ORDER BY rows DESC +LIMIT 10; +``` + +**Queries returning the most rows per execution** (poorly scoped SELECTs, missing pagination): + +```sql +SELECT query, calls, rows AS total_rows, rows / calls AS avg_rows_per_call +FROM pg_stat_statements +WHERE calls > 0 +ORDER BY avg_rows_per_call DESC +LIMIT 10; +``` + +**Most frequently called queries** (candidates for caching): + +```sql +SELECT query, calls, rows AS total_rows, rows / calls AS avg_rows_per_call +FROM pg_stat_statements +WHERE calls > 0 +ORDER BY calls DESC +LIMIT 10; +``` + +**Longest running queries** (not a direct egress measure, but helps identify problem queries during a spike): + +```sql +SELECT query, calls, rows AS total_rows, + round(total_exec_time::numeric, 2) AS total_exec_time_ms +FROM pg_stat_statements +WHERE calls > 0 +ORDER BY total_exec_time DESC +LIMIT 10; +``` + +### Interpret the results + +Rank findings by estimated egress impact: + +- **High row count + wide rows** = biggest egress. A query returning 1,000 rows where each row includes a 50KB JSONB column transfers ~50MB per call. +- **Extreme call frequency** on even small queries adds up. A query called 50,000 times/day returning 10 rows each = 500,000 rows/day. +- **Cross-reference with the schema** to identify which columns are wide. Look for JSONB, TEXT, BYTEA, and large VARCHAR columns. + +## Step 2: Analyze codebase + +For each query identified in Step 1, or for each database query in the codebase if no stats are available, check: + +- Does it select only the columns the response needs? +- Does it return a bounded number of rows (LIMIT/pagination)? +- Is it called frequently enough to benefit from caching? +- Does it fetch raw data that gets aggregated in application code? +- Does it use a JOIN that duplicates parent data across child rows? + +## Step 3: Fix + +Apply the appropriate fix for each problem found. Below are the most common egress anti-patterns and how to fix them. + +### Unused columns (SELECT \*) + +**Problem:** The query fetches all columns but the application only uses a few. Large columns (JSONB blobs, TEXT fields) get transferred over the wire and discarded. + +**Before:** + +```sql +SELECT * FROM products; +``` + +**After:** + +```sql +SELECT id, name, price, image_urls FROM products; +``` + +### Missing pagination + +**Problem:** A list endpoint returns all rows with no LIMIT. This is an unbounded egress risk — every new row in the table increases data transfer on every request. Flag this regardless of current table size. + +This is easy to miss because the application may work fine with small datasets. But at scale, an unpaginated endpoint returning 10,000 rows with even moderate column widths can transfer hundreds of megabytes per day. + +**Before:** + +```sql +SELECT id, name, price FROM products; +``` + +**After:** + +```sql +SELECT id, name, price FROM products +ORDER BY id +LIMIT 50 OFFSET 0; +``` + +When adding pagination, check whether the consuming client already supports paginated responses. If not, pick sensible defaults and document the pagination parameters in the API. + +### High-frequency queries on static data + +**Problem:** A query is called thousands of times per day but returns data that rarely changes. Every call transfers the same rows from the database. This pattern is only visible from `pg_stat_statements` — the code itself looks normal. + +Look for queries with extremely high call counts relative to other queries. Common examples: configuration tables, category lists, feature flags, user role definitions. + +**Fix:** Add a caching layer between the application and the database so it avoids hitting the database on every request. + +### Application-side aggregation + +**Problem:** The application fetches all rows from a table and then computes aggregates (averages, counts, sums, groupings) in application code. The full dataset transfers over the wire even though the result is a small summary. + +**Fix:** Push the aggregation into SQL. + +**Before:** The application fetches entire tables and aggregates in code with loops or `.reduce()`. + +**After:** + +```sql +SELECT p.category_id, + AVG(r.rating) AS avg_rating, + COUNT(r.id) AS review_count +FROM reviews r +INNER JOIN products p ON r.product_id = p.id +GROUP BY p.category_id; +``` + +### JOIN duplication + +**Problem:** A JOIN between a wide parent table and a child table duplicates all parent columns across every child row. If a product has 200 reviews and the product row includes a 50KB JSONB column, the join sends that 50KB x 200 = ~10MB for a single request. + +This is distinct from the SELECT \* problem. Even if you select only needed columns, a JOIN still repeats the parent data for every child row. The fix is structural: avoid the join entirely. + +**Before:** + +```sql +SELECT * FROM products +LEFT JOIN reviews ON reviews.product_id = products.id +WHERE products.id = 1; +``` + +**After (two separate queries):** + +```sql +SELECT id, name, price, description, image_urls FROM products WHERE id = 1; +SELECT id, user_name, rating, body FROM reviews WHERE product_id = 1; +``` + +Two queries instead of one JOIN. The product data is fetched once. The reviews are fetched once. No duplication. + +## Step 4: Verify + +After applying fixes: + +1. **Run existing tests** to confirm nothing broke. +2. **Check the responses** — make sure the API still returns the same data shape. Column selection and pagination changes can break clients that depend on specific fields or full result sets. +3. **Measure the improvement** — if pg_stat_statements data is available, reset it (`SELECT pg_stat_statements_reset();`), let traffic run, then re-run the diagnostic queries to compare before and after. + +## Further reading + +- https://neon.com/docs/introduction/network-transfer.md +- https://neon.com/docs/introduction/cost-optimization.md diff --git a/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/agents/openai.yaml b/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/agents/openai.yaml new file mode 100644 index 00000000..0b8cd935 --- /dev/null +++ b/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/agents/openai.yaml @@ -0,0 +1,15 @@ +interface: + display_name: "Neon Postgres Egress Optimizer" + short_description: "Diagnose and fix excessive Postgres data transfer costs" + icon_small: "./assets/neon-small.svg" + icon_large: "./assets/neon.jpg" + brand_color: "#37C38F" + default_prompt: "Analyze my codebase for database query patterns that cause excessive data transfer and help me optimize them." + +dependencies: + tools: + - type: "mcp" + value: "neon" + description: "Neon MCP server" + transport: "streamable_http" + url: "https://mcp.neon.tech/mcp" diff --git a/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/assets/neon-small.svg b/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/assets/neon-small.svg new file mode 100644 index 00000000..013e8c8d --- /dev/null +++ b/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/assets/neon-small.svg @@ -0,0 +1,3 @@ + diff --git a/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/assets/neon.jpg b/plugins/neon-postgres/skills/neon-postgres-egress-optimizer/assets/neon.jpg new file mode 100644 index 0000000000000000000000000000000000000000..d9467e2f5a97eab8faf17cbfd242ca771b31ab8a GIT binary patch literal 3022 zcmcIldpy+J7T@z?P^6MjMo~I+a}qr~nyWIRB;=Jel~WZGj#DfC%sybwEHzs0dh%(fBf^U={(~ntf&>#c1Zw>UYwxVmli z^z!!c-R-w0_&~_PP*r?77R?SFT>mxt^PMui$>+zaBg+ zdQ?{atfG=t^}M?N^_zyqrskH`j!t%0cTaC${{WZwi9a$rCJ>4yc%feTix&F+kGzyo zURXRHhnJn;g~5hS5Ld<%<}H<(ZecIGGjPUy!^6axYf`iBmda@_bKt1#3aXQzrDN2w zfIC5LlG)!Q7X4Gqz7YG$>n&Idu#>=Hu{Z(_ha<=kP{Mek_}athP_Yrr-%xnyB0n1aKg$%In|WWcXpldz?sWA;<-jDg&h_vH@~R+*kL z$axxZ*E+jrSuv@iyFq2K*D9}u#@v1$*#_~3K)7Ht($vP1#_IQl3)!Po2u?c5N+RDO zeQSynZk=ZF^A(XQrjnEhLH{CH%dZ}{8>K*yl1Y;m<)d1iKTa&#hs>dSK%o7IM1IcL zS7)h`D@mSdZwdbWgc-05gbPGX<9Ct1hWzSt5@$g-1Uk&E5F9j+s22(y-Ry#eF_q}v zX4gR=J5W>4XhEdbTSy~gfe>WLi!_Vrk_-sC(k&pMhLS|n^0Njl?}}D@yVJU#-Rbe_ zJhx=fm9}9^h#@62$V&Vvpxa_udYX5IcgU33U(G8_il+$z#w|SP0j@=y_C$}5H&?&b zt5~Xa|DRQK9k!Mi&pkO)|0B)x1#Nuy@Zv7FtW(}@>$Os@U&*XF-*HjDtmo8)K5|%u z{Q&cQ*y-JukNLjV+`xSywT>#34pBwMG~P9)Q}HU~xj`edEfE6Bt*9-Hj_;&9xJ)U< z2q_g6@N<3$Q~pKr50R|f8XwZ-SK!X|bQc8X#vc`bSnd$fN1S@$a5Z0xW7^d38*ApBC3tIX>$&#) z??)eclfyK?i4xz7R^g3?MH0_av#^Ah{Xt@5XRgF0qYF);In1t%LF&f}2(q1-dbAOD zc82(*geGZb^7k}#+pZfU&;6gA{rdm!?3Sn*;)R8R^sIs7X-4XC1tgtb;(pb5p*8De z>k}GUs!lX!p@(BS1bsfmFC-_)>?UUjZYQCIhUI!SSL|P^<}t-*|DEO|e;D>KJ0n8! z1&9;pRnC&sn5hBtKE6USUix zR_&uI^9yKE#ZK?&yqs+^+h(w|xX(XO&qbMX6d!XSaP`-9OS#@QCo%f=l@r9$m3?%x zTDE6>=PQNEuGw+N%B>&jetf>~31h@3vapkRR9*KO5-n=XzBWB=-8{F;JL4%!65e?- z9I2TNL2oxdEl76t_t{;)A9uL!Q2)6c>&Fc9iU=pi<(Ybg*?yH~`2`J+rMmrgLrk=u zekV7WD!Gp3NmR`yQuAh%U7w_nM_K9W_GL4hTv~k_9CA28|hR)Va~< zmLA*HB>m07w``AMPeRS_CO*aF%Xc=hIQdh3@4X1TQ%NyD@a35tU8&U&^*fQgtr>~pC8Ef(+c)-F zCmqttU6)7Ek|EK_>(yx9mzBmfy%$GvJ?9Sh|B@q#cUt(zP#O z8tsIIVHu^zgPcHULUa7Xr6t){Fx%b0OfCA5FD$Fyt6 z9WDYFX&9O!$W#*Nh8T^h8QPJU@lO?xEhe=zBf>FKk!IMpzv?$QB%NLV#FW76&l}JQ z+SJq5f|NZeds^P1E4slPOW|#$1rO3m1d3Yvsx@-v;Y(Qe?JZS&`Lmri3~HF$)Vpg4 zoaqZ4ZYSe@k$t17*EVy;%4_F-oAV$x!uX27abw1Yx?Mc~q-XbHhtw(0akb%!4R0FU c?TU2AKZpk!WaARb>XTMhF16NqM1n1U0w$fX&;S4c literal 0 HcmV?d00001 diff --git a/plugins/neon-postgres/skills/neon-postgres/SKILL.md b/plugins/neon-postgres/skills/neon-postgres/SKILL.md new file mode 100644 index 00000000..23dc2241 --- /dev/null +++ b/plugins/neon-postgres/skills/neon-postgres/SKILL.md @@ -0,0 +1,217 @@ +--- +name: neon-postgres +description: Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/auth), PostgREST-style data API (@neondatabase/neon-js), Neon CLI, and Neon's Platform API/SDKs. Use for any Neon-related questions. +--- + +# Neon Serverless Postgres + +Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres. + +## When to Use This Skill + +Activate this skill when users want to: +- Create or manage a Postgres database +- Set up a Neon project or branch +- Connect an application to Neon Postgres +- Use Neon features like branching, autoscaling, or scale-to-zero +- Set up Neon Auth for user authentication +- Use the Neon MCP server, CLI, or API +- Work with the `@neondatabase/serverless` driver or `@neondatabase/neon-js` SDK + +## Prerequisites + +The Neon MCP server is required for project and database management. It uses OAuth and authenticates via browser on first use — no API key needed. + +If MCP tools are not available, guide the user through manual setup: + +### Codex + +The Neon MCP server should be configured automatically via this plugin. If it isn't, the user can add it manually: + +```bash +codex mcp add neon --url https://mcp.neon.tech/mcp +``` + +Restart Codex, then verify by attempting to list projects. + +### Other Tools + +Direct the user to the Neon MCP docs for setup steps: https://neon.com/docs/ai/neon-mcp-server + +## Neon Documentation + +The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data. + +### Fetching Docs as Markdown + +Any Neon doc page can be fetched as markdown in two ways: + +1. **Append `.md` to the URL** (simplest): https://neon.com/docs/introduction/branching.md +2. **Request `text/markdown`** on the standard URL: `curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching` + +Both return the same markdown content. Use whichever method your tools support. + +### Finding the Right Page + +The docs index lists every available page with its URL and a short description: + +``` +https://neon.com/docs/llms.txt +``` + +Common doc URLs are organized in the topic links below. If you need a page not listed here, search the docs index — don't guess URLs. + +## What Is Neon + +Use this for architecture explanations and terminology (organizations, projects, branches, endpoints) before giving implementation advice. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/what-is-neon.md + +## Getting Started + +Use this for first-time setup: org/project selection, connection strings, driver installation, optional auth, and initial schema setup. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/getting-started.md + +## Connection Methods & Drivers + +Use this when you need to pick the correct transport and driver based on runtime constraints (TCP, HTTP, WebSocket, edge, serverless, long-running). + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/connection-methods.md + +### Serverless Driver + +Use this for `@neondatabase/serverless` patterns, including HTTP queries, WebSocket transactions, and runtime-specific optimizations. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-serverless.md + +### Neon JS SDK + +Use this for combined Neon Auth + Data API workflows with PostgREST-style querying and typed client setup. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-js.md + +## Developer Tools + +Use this for local development enablement with `npx neonctl@latest init`, VSCode extension setup, and Neon MCP server configuration. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/devtools.md + +### Neon CLI + +Use this for terminal-first workflows, scripts, and CI/CD automation with `neonctl`. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-cli.md + +## Neon Admin API + +The Neon Admin API can be used to manage Neon resources programmatically. It is used behind the scenes by the Neon CLI and MCP server, but can also be used directly for more complex automation workflows or when embedding Neon in other applications. + +### Neon REST API + +Use this for direct HTTP automation, endpoint-level control, API key auth, rate-limit handling, and operation polling. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-rest-api.md + +### Neon TypeScript SDK + +Use this when implementing typed programmatic control of Neon resources in TypeScript via `@neondatabase/api-client`. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-typescript-sdk.md + +### Neon Python SDK + +Use this when implementing programmatic Neon management in Python with the `neon-api` package. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-python-sdk.md + +## Neon Auth + +Use this for managed user authentication setup, UI components, auth methods, and Neon Auth integration pitfalls in Next.js and React apps. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-auth.md + +Neon Auth is also embedded in the Neon JS SDK — so depending on your use case, you may want to use the Neon JS SDK instead of Neon Auth. See https://neon.com/docs/ai/skills/neon-postgres/references/connection-methods.md for more details. + +## Branching + +Use this when the user is planning isolated environments, schema migration testing, preview deployments, or branch lifecycle automation. + +Key points: + +- Branches are instant, copy-on-write clones (no full data copy). +- Each branch has its own compute endpoint. +- Use the neonctl CLI or MCP server to create, inspect, and compare branches. + +Link: https://neon.com/docs/ai/skills/neon-postgres/references/branching.md + +## Autoscaling + +Use this when the user needs compute to scale automatically with workload and wants guidance on CU sizing and runtime behavior. + +Link: https://neon.com/docs/introduction/autoscaling.md + +## Scale to Zero + +Use this when optimizing idle costs and discussing suspend/resume behavior, including cold-start trade-offs. + +Key points: + +- Idle computes suspend automatically (default 5 minutes, configurable) (unless disabled — launch & scale plan only) +- First query after suspend typically has a cold-start penalty (around hundreds of ms) +- Storage remains active while compute is suspended. + +Link: https://neon.com/docs/introduction/scale-to-zero.md + +## Instant Restore + +Use this when the user needs point-in-time recovery or wants to restore data state without traditional backup restore workflows. + +Key points: + +- Restore windows depend on plan limits. +- Users can create branches from historical points-in-time. +- Time Travel queries can be used for historical inspection workflows. + +Link: https://neon.com/docs/introduction/branch-restore.md + +## Read Replicas + +Use this for read-heavy workloads where the user needs dedicated read-only compute without duplicating storage. + +Key points: + +- Replicas are read-only compute endpoints sharing the same storage. +- Creation is fast and scaling is independent from primary compute. +- Typical use cases: analytics, reporting, and read-heavy APIs. + +Link: https://neon.com/docs/introduction/read-replicas.md + +## Connection Pooling + +Use this when the user is in serverless or high-concurrency environments and needs safe, scalable Postgres connection management. + +Key points: + +- Neon pooling uses PgBouncer. +- Add `-pooler` to endpoint hostnames to use pooled connections. +- Pooling is especially important in serverless runtimes with bursty concurrency. + +Link: https://neon.com/docs/connect/connection-pooling.md + +## IP Allow Lists + +Use this when the user needs to restrict database access by trusted networks, IPs, or CIDR ranges. + +Link: https://neon.com/docs/introduction/ip-allow.md + +## Logical Replication + +Use this when integrating CDC pipelines, external Postgres sync, or replication-based data movement. + +Key points: + +- Neon supports native logical replication workflows. +- Useful for replicating to/from external Postgres systems. + +Link: https://neon.com/docs/guides/logical-replication-guide.md diff --git a/plugins/neon-postgres/skills/neon-postgres/agents/openai.yaml b/plugins/neon-postgres/skills/neon-postgres/agents/openai.yaml new file mode 100644 index 00000000..9bb6ae97 --- /dev/null +++ b/plugins/neon-postgres/skills/neon-postgres/agents/openai.yaml @@ -0,0 +1,15 @@ +interface: + display_name: "Neon Postgres" + short_description: "Guides and best practices for Neon Serverless Postgres" + icon_small: "./assets/neon-small.svg" + icon_large: "./assets/neon.jpg" + brand_color: "#37C38F" + default_prompt: "Use $neon to create a Serverless Postgres database, run SQL queries, or manage branches." + +dependencies: + tools: + - type: "mcp" + value: "neon" + description: "Neon MCP server" + transport: "streamable_http" + url: "https://mcp.neon.tech/mcp" diff --git a/plugins/neon-postgres/skills/neon-postgres/assets/neon-small.svg b/plugins/neon-postgres/skills/neon-postgres/assets/neon-small.svg new file mode 100644 index 00000000..013e8c8d --- /dev/null +++ b/plugins/neon-postgres/skills/neon-postgres/assets/neon-small.svg @@ -0,0 +1,3 @@ + diff --git a/plugins/neon-postgres/skills/neon-postgres/assets/neon.jpg b/plugins/neon-postgres/skills/neon-postgres/assets/neon.jpg new file mode 100644 index 0000000000000000000000000000000000000000..d9467e2f5a97eab8faf17cbfd242ca771b31ab8a GIT binary patch literal 3022 zcmcIldpy+J7T@z?P^6MjMo~I+a}qr~nyWIRB;=Jel~WZGj#DfC%sybwEHzs0dh%(fBf^U={(~ntf&>#c1Zw>UYwxVmli z^z!!c-R-w0_&~_PP*r?77R?SFT>mxt^PMui$>+zaBg+ zdQ?{atfG=t^}M?N^_zyqrskH`j!t%0cTaC${{WZwi9a$rCJ>4yc%feTix&F+kGzyo zURXRHhnJn;g~5hS5Ld<%<}H<(ZecIGGjPUy!^6axYf`iBmda@_bKt1#3aXQzrDN2w zfIC5LlG)!Q7X4Gqz7YG$>n&Idu#>=Hu{Z(_ha<=kP{Mek_}athP_Yrr-%xnyB0n1aKg$%In|WWcXpldz?sWA;<-jDg&h_vH@~R+*kL z$axxZ*E+jrSuv@iyFq2K*D9}u#@v1$*#_~3K)7Ht($vP1#_IQl3)!Po2u?c5N+RDO zeQSynZk=ZF^A(XQrjnEhLH{CH%dZ}{8>K*yl1Y;m<)d1iKTa&#hs>dSK%o7IM1IcL zS7)h`D@mSdZwdbWgc-05gbPGX<9Ct1hWzSt5@$g-1Uk&E5F9j+s22(y-Ry#eF_q}v zX4gR=J5W>4XhEdbTSy~gfe>WLi!_Vrk_-sC(k&pMhLS|n^0Njl?}}D@yVJU#-Rbe_ zJhx=fm9}9^h#@62$V&Vvpxa_udYX5IcgU33U(G8_il+$z#w|SP0j@=y_C$}5H&?&b zt5~Xa|DRQK9k!Mi&pkO)|0B)x1#Nuy@Zv7FtW(}@>$Os@U&*XF-*HjDtmo8)K5|%u z{Q&cQ*y-JukNLjV+`xSywT>#34pBwMG~P9)Q}HU~xj`edEfE6Bt*9-Hj_;&9xJ)U< z2q_g6@N<3$Q~pKr50R|f8XwZ-SK!X|bQc8X#vc`bSnd$fN1S@$a5Z0xW7^d38*ApBC3tIX>$&#) z??)eclfyK?i4xz7R^g3?MH0_av#^Ah{Xt@5XRgF0qYF);In1t%LF&f}2(q1-dbAOD zc82(*geGZb^7k}#+pZfU&;6gA{rdm!?3Sn*;)R8R^sIs7X-4XC1tgtb;(pb5p*8De z>k}GUs!lX!p@(BS1bsfmFC-_)>?UUjZYQCIhUI!SSL|P^<}t-*|DEO|e;D>KJ0n8! z1&9;pRnC&sn5hBtKE6USUix zR_&uI^9yKE#ZK?&yqs+^+h(w|xX(XO&qbMX6d!XSaP`-9OS#@QCo%f=l@r9$m3?%x zTDE6>=PQNEuGw+N%B>&jetf>~31h@3vapkRR9*KO5-n=XzBWB=-8{F;JL4%!65e?- z9I2TNL2oxdEl76t_t{;)A9uL!Q2)6c>&Fc9iU=pi<(Ybg*?yH~`2`J+rMmrgLrk=u zekV7WD!Gp3NmR`yQuAh%U7w_nM_K9W_GL4hTv~k_9CA28|hR)Va~< zmLA*HB>m07w``AMPeRS_CO*aF%Xc=hIQdh3@4X1TQ%NyD@a35tU8&U&^*fQgtr>~pC8Ef(+c)-F zCmqttU6)7Ek|EK_>(yx9mzBmfy%$GvJ?9Sh|B@q#cUt(zP#O z8tsIIVHu^zgPcHULUa7Xr6t){Fx%b0OfCA5FD$Fyt6 z9WDYFX&9O!$W#*Nh8T^h8QPJU@lO?xEhe=zBf>FKk!IMpzv?$QB%NLV#FW76&l}JQ z+SJq5f|NZeds^P1E4slPOW|#$1rO3m1d3Yvsx@-v;Y(Qe?JZS&`Lmri3~HF$)Vpg4 zoaqZ4ZYSe@k$t17*EVy;%4_F-oAV$x!uX27abw1Yx?Mc~q-XbHhtw(0akb%!4R0FU c?TU2AKZpk!WaARb>XTMhF16NqM1n1U0w$fX&;S4c literal 0 HcmV?d00001