home / skills / sickn33 / antigravity-awesome-skills / using-neon

using-neon skill

safe

This skill helps you master Neon Serverless Postgres by guiding setup, connection methods, authentication, APIs, and platform tools.

This is most likely a fork of the using-neon skill from xfstudio

npx playbooks add skill sickn33/antigravity-awesome-skills --skill using-neon

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

4.6 KB

---
name: using-neon
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."
source: "https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres"
risk: safe
---

# 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

Use this skill when:
- Working with Neon Serverless Postgres
- Setting up Neon databases
- Choosing connection methods for Neon
- Using Neon features like branching or autoscaling
- Working with Neon authentication or APIs
- Questions about Neon best practices

## Neon Documentation

Always reference the Neon documentation before making Neon-related claims. The documentation is the source of truth for all Neon-related information.

Below you'll find a list of resources organized by area of concern. This is meant to support you find the right documentation pages to fetch and add a bit of additonal context.

You can use the `curl` commands to fetch the documentation page as markdown:

**Documentation:**

```bash
# Get list of all Neon docs
curl https://neon.com/llms.txt

# Fetch any doc page as markdown
curl -H "Accept: text/markdown" https://neon.com/docs/<path>
```

Don't guess docs pages. Use the `llms.txt` index to find the relevant URL or follow the links in the resources below.

## Overview of Resources

Reference the appropriate resource file based on the user's needs:

### Core Guides

| Area               | Resource                           | When to Use                                                    |
| ------------------ | ---------------------------------- | -------------------------------------------------------------- |
| What is Neon       | `references/what-is-neon.md`       | Understanding Neon concepts, architecture, core resources      |
| Referencing Docs   | `references/referencing-docs.md`   | Looking up official documentation, verifying information       |
| Features           | `references/features.md`           | Branching, autoscaling, scale-to-zero, instant restore         |
| Getting Started    | `references/getting-started.md`    | Setting up a project, connection strings, dependencies, schema |
| Connection Methods | `references/connection-methods.md` | Choosing drivers based on platform and runtime                 |
| Developer Tools    | `references/devtools.md`           | VSCode extension, MCP server, Neon CLI (`neon init`)           |

### Database Drivers & ORMs

HTTP/WebSocket queries for serverless/edge functions.

| Area              | Resource                        | When to Use                                         |
| ----------------- | ------------------------------- | --------------------------------------------------- |
| Serverless Driver | `references/neon-serverless.md` | `@neondatabase/serverless` - HTTP/WebSocket queries |
| Drizzle ORM       | `references/neon-drizzle.md`    | Drizzle ORM integration with Neon                   |

### Auth & Data API SDKs

Authentication and PostgREST-style data API for Neon.

| Area        | Resource                  | When to Use                                                         |
| ----------- | ------------------------- | ------------------------------------------------------------------- |
| Neon Auth   | `references/neon-auth.md` | `@neondatabase/auth` - Authentication only                          |
| Neon JS SDK | `references/neon-js.md`   | `@neondatabase/neon-js` - Auth + Data API (PostgREST-style queries) |

### Neon Platform API & CLI

Managing Neon resources programmatically via REST API, SDKs, or CLI.

| Area                  | Resource                            | When to Use                                  |
| --------------------- | ----------------------------------- | -------------------------------------------- |
| Platform API Overview | `references/neon-platform-api.md`   | Managing Neon resources via REST API         |
| Neon CLI              | `references/neon-cli.md`            | Terminal workflows, scripts, CI/CD pipelines |
| TypeScript SDK        | `references/neon-typescript-sdk.md` | `@neondatabase/api-client`                   |
| Python SDK            | `references/neon-python-sdk.md`     | `neon-api` package                           |

Overview

This skill provides practical guidance and best practices for working with Neon Serverless Postgres. It covers getting started, local development, connection method selection, Neon features (branching, autoscaling, instant restore), and Neon-specific SDKs and tools. Use it as a compact reference for common Neon workflows and decision points.

How this skill works

The skill organizes guidance by area of concern: core concepts, drivers and ORMs, auth and data APIs, and platform/CLI tooling. It points to which Neon resources and SDKs to use for a given task and outlines concrete steps for local development, connecting from serverless or edge runtimes, and using Neon authentication and PostgREST-style APIs. It emphasizes consulting Neon docs as the source of truth and provides command patterns to fetch docs where needed.

When to use it

Setting up a new Neon database or initializing a project
Choosing a connection strategy for serverless, edge, or traditional runtimes
Implementing authentication with @neondatabase/auth or using @neondatabase/neon-js
Configuring branching, autoscaling, or restore workflows
Automating Neon resources via CLI, REST Platform API, or SDKs

Best practices

Always verify details against the official Neon documentation before making infra changes
Use the serverless driver for HTTP/edge functions and standard drivers for long-running backends
Prefer Neon-auth SDKs for user flows and neon-js for combined auth + PostgREST-style queries
Develop locally with a pinned Neon branch or a local postgres-compatible shim, and test branching workflows before production
Automate resource management with Neon CLI or Platform SDKs for repeatable CI/CD scripts

Example use cases

Create a preview database branch per feature branch so reviewers can test schema and data changes
Use @neondatabase/serverless in an edge function to run short-lived queries with minimal cold-start overhead
Authenticate users with @neondatabase/auth and issue scoped access tokens for data APIs
Script database provisioning and role creation in CI using the Neon CLI or Python/TypeScript SDKs
Migrate a monolithic Postgres app to Neon, adjusting connection pooling and runtime choices for serverless components

FAQ

Which driver should I use for edge/serverless functions?

Use Neon’s serverless driver for short-lived HTTP or edge runtimes; it avoids persistent connections and works over HTTP/WebSocket patterns. Use standard Postgres drivers for long-lived backend processes.

When should I use neon-js vs @neondatabase/auth?

Use @neondatabase/auth when you only need authentication flows. Use neon-js when you need both auth and a PostgREST-style data API together for simpler client-side data access.