neon-toolkit

✓ Official★ 86

by neondatabase · part of neondatabase/ai-rules

Creates and manages ephemeral Neon databases for testing, CI/CD pipelines, and isolated development environments. Use when building temporary databases for…

🔥🔥🔥✓ VerifiedFreeQuick setup

#database #devops #git

🧰 Not standalone. This skill ships with neondatabase/ai-rules and only works together with that tool — install the tool first, then add this skill.

Creates and manages ephemeral Neon databases for testing, CI/CD pipelines, and isolated development environments. Use when building temporary databases for…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

name: neon-toolkit description: Creates and manages ephemeral Neon databases for testing, CI/CD pipelines, and isolated development environments. Use when building temporary databases for automated tests or rapid prototyping. allowed-tools: ["bash"]

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

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

Copy & paste — that's it

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

CI/CD Integration

Copy & paste — that's it

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.

Copy & paste — that's it

npx skills add https://github.com/neondatabase/ai-rules --skill neon-toolkit

Run this in your project — your agent picks the skill up automatically.

Quick Setup

Installation

Copy & paste — that's it

npm install @neondatabase/toolkit

Basic Usage

Copy & paste — that's it

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();