Neon

````instructions
---
name: neon
description: 'Operate Neon PostgreSQL safely in this repository: validate DATABASE_URL configuration, enforce TLS requirements, choose migration strategy with Prisma, and troubleshoot connectivity issues across local, preview, and production environments. Use when requests mention Neon, neon.tech URLs, pooled vs direct connections, DATABASE_URL, branch databases, or Neon-backed deployment problems.'
---

# Neon

## Overview

Use this skill to keep Neon connectivity and schema change workflows safe and repeatable.
Treat environment targeting and connection validation as mandatory before any write operation.

## Follow This Workflow

### 1. Validate connection settings

- Confirm the target `DATABASE_URL` before migrations or seed scripts.
- Run:

```bash
node .github/skills/neon/scripts/validate-neon-url.mjs
```

- If needed, pass an explicit URL:

```bash
node .github/skills/neon/scripts/validate-neon-url.mjs --url "postgresql://..."
```

### 2. Confirm environment intent

- Local-only work: use local Docker/Postgres URL from `.env.example`.
- Shared/dev/staging/prod: use managed URL with TLS (`sslmode=require`).
- Do not run destructive commands against production unless explicitly requested.

### 3. Run schema operations with Prisma wrapper

- Preferred entrypoint:

```bash
pnpm tsx scripts/prisma.ts <prisma-subcommand>
```

- Common operations:

```bash
pnpm tsx scripts/prisma.ts migrate dev
pnpm tsx scripts/prisma.ts migrate deploy
pnpm tsx scripts/prisma.ts db push
pnpm tsx scripts/prisma.ts studio
```

### 4. Verify health after changes

- Check app health endpoint (includes DB env checks):

```bash
curl -s http://localhost:3001/api/health
```

- Confirm application reads and writes succeed for changed tables.

### 5. Report and close

- Report environment target, connection host, migration command, and verification result.
- Include rollback or mitigation note when production-impacting work was performed.

## Use These Decision Rules

| Situation                                   | Action                               |
| ------------------------------------------- | ------------------------------------ |
| Unsure if URL is safe/valid                 | Run `validate-neon-url.mjs` first    |
| Local development schema changes            | `migrate dev`                        |
| CI or production apply                      | `migrate deploy`                     |
| Prototype only, no migration history needed | `db push` (explicitly note tradeoff) |
| Need quick DB inspection                    | `studio`                             |

## Safety Rules

1. Validate URL and SSL mode before DB writes.
2. Prefer migration files over `db push` for shared environments.
3. Never commit secrets from `.env`.
4. Keep Neon-specific assumptions in config, not hardcoded in app logic.

## References

- Repository Neon/DB profile: `references/repo-profile.md`
- Connection and migration playbook: `references/connection-playbook.md`
````