Neon Toolkit Skill

Automates creation, management, and cleanup of temporary Neon databases using the Neon Toolkit.

When to Use

• •Creating fresh databases for each test run
• •Spinning up databases in CI/CD pipelines
• •Building isolated development environments
• •Rapid prototyping without manual setup

Not recommended for: Production databases, shared team environments, local-only development (use Docker), or free tier accounts (requires paid projects).

Code Generation Rules

When generating TypeScript/JavaScript code:

• •BEFORE generating import statements, check tsconfig.json for path aliases (compilerOptions.paths)
• •If path aliases exist (e.g., "@/": ["./src/"]), use them (e.g., import { x } from '@/lib/utils')
• •If NO path aliases exist or unsure, ALWAYS use relative imports (e.g., import { x } from '../../../lib/utils')
• •Verify imports match the project's configuration
• •Default to relative imports - they always work regardless of configuration

Reference Documentation

Primary Resource: See [neon-toolkit.mdc](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/neon-toolkit.mdc) in project root for comprehensive guidelines including:

• •Core concepts (Organization, Project, Branch, Endpoint)
• •Installation and authentication setup
• •Database lifecycle management patterns
• •API client usage examples
• •Error handling strategies

Quick Setup

Installation

npm install @neondatabase/toolkit

Basic Usage

import { NeonToolkit } from '@neondatabase/toolkit';

const neon = new NeonToolkit({ apiKey: process.env.NEON_API_KEY! });

// Create ephemeral database
const db = await neon.createEphemeralDatabase();
console.log(`Database URL: ${db.url}`);

// Use the database...

// Cleanup
await db.delete();

Templates & Scripts

• •templates/toolkit-workflow.ts - Complete ephemeral database workflow
• •scripts/create-ephemeral-db.ts - Create a temporary database
• •scripts/destroy-ephemeral-db.ts - Clean up ephemeral database

Common Use Cases

Testing

const db = await neon.createEphemeralDatabase();
// Run tests with fresh database
await db.delete();

CI/CD Integration

export NEON_API_KEY=${{ secrets.NEON_API_KEY }}
npm test  # Uses ephemeral database

Related Skills

• •neon-serverless - For connecting to databases
• •neon-drizzle - For schema and migrations

Want best practices in your project? Run neon-plugin:add-neon-docs with parameter SKILL_NAME="neon-toolkit" to add reference links.