The @neondatabase/toolkit

About the toolkit

The @neondatabase/toolkit (@neon/toolkit on JSR) is a terse client that lets you spin up a Postgres database in seconds and run SQL queries. It includes both the Neon TypeScript SDK and the Neon Serverless Driver, making it an excellent choice for AI agents that need to quickly set up an SQL database or test environments where manually deploying a new database isn't practical.

The primary goal of the toolkit is to abstract away the multi-step process of creating a project, retrieving its connection string, and then establishing a database connection. This makes it an excellent choice for:

• AI Agents: An agent can spin up a dedicated database instance in seconds to perform a task, run SQL queries, and then tear it down, all within a single, streamlined workflow.
• Testing Environments: Ideal for integration or end-to-end tests where a fresh, isolated database is required for each test run, ensuring no state is carried over.
• Demos and Prototyping: Quickly create a live Postgres database to demonstrate a feature or prototype an idea without any manual setup in the Neon Console.

Getting started

Installation

Install the @neondatabase/toolkit package into your project using your preferred package manager:

npm install @neondatabase/toolkit

Authentication

The toolkit requires a Neon API key to interact with your account.

1. Log in to the Neon Console.
2. Navigate to Account settings > API keys.
3. Click Generate new API key, give it a name, and copy the key.

For security, it's best to use this key as an environment variable.

export NEON_API_KEY="YOUR_API_KEY_FROM_NEON_CONSOLE"

Raw Methods

Feel free to skip to the Complete Example section if you want to see everything in action.

The toolkit offers a compact, useful API for handling the lifecycle of an ephemeral database.

new NeonToolkit(apiKey)

Initializes a new toolkit instance.

• apiKey (string): Your Neon API key.

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

const toolkit = new NeonToolkit(process.env.NEON_API_KEY!);

toolkit.createProject(projectOptions?)

Creates a new Neon project and returns a ToolkitProject object containing all the associated resources.

• projectOptions (object) (optional): An object specifying the project's configuration, such as name, region_id, or pg_version. For further customization options, refer to the API Reference.

// Create a project with default settings
const project = await toolkit.createProject();

// Create a project with a specific name and Postgres version
const customizedProject = await toolkit.createProject({
  name: 'my-ai-agent-db',
  pg_version: 16,
});

console.log('Project created with ID:', project.project.id);
console.log('Connection string:', project.connectionURIs[0].connection_uri);

toolkit.sql(project, query)

Executes an SQL query against the project's default database. This method uses the Neon Serverless Driver under the hood.

• project (ToolkitProject): The ToolkitProject object returned by createProject. The method automatically uses the connection string from this object.
• query (string): The SQL query string to execute.

const project = await toolkit.createProject();

// Create a table
await toolkit.sql(project, `CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT);`);

// Insert data and get the result
const result = await toolkit.sql(project, `INSERT INTO users (name) VALUES ('Alex') RETURNING id;`);

console.log(result); // [ { id: 1 } ]

toolkit.deleteProject(project)

Deletes the Neon project. This is a destructive operation and will remove the project and all its branches, databases, and data.

• project (ToolkitProject): The ToolkitProject object returned by createProject.

const project = await toolkit.createProject();

// ... use the database

await toolkit.deleteProject(project);
console.log('Project deleted.');

Complete Example

This example demonstrates the full lifecycle: creating a project, running schema and data queries, and tearing down the project.

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

async function main() {
  if (!process.env.NEON_API_KEY) {
    throw new Error('NEON_API_KEY environment variable is not set.');
  }

  const toolkit = new NeonToolkit(process.env.NEON_API_KEY);

  console.log('Creating a new Neon project...');
  const project = await toolkit.createProject({ name: 'toolkit-demo' });
  console.log(`Project "${project.project.name}" created successfully.`);

  console.log("Creating 'users' table...");
  await toolkit.sql(
    project,
    `
      CREATE TABLE IF NOT EXISTS users (
        id UUID PRIMARY KEY,
        name VARCHAR(255) NOT NULL,
        createdAt TIMESTAMP WITH TIME ZONE DEFAULT NOW()
      );
    `
  );

  console.log('Inserting a new user...');
  await toolkit.sql(
    project,
    `INSERT INTO users (id, name) VALUES (gen_random_uuid(), 'Sam Smith')`
  );

  console.log('Querying users...');
  const users = await toolkit.sql(project, `SELECT name, createdAt FROM users`);

  console.log('Found users:', users);

  console.log('Deleting the project...');
  await toolkit.deleteProject(project);
  console.log('Project deleted. Demo complete.');
}

main().catch(console.error);

To run this example, save it as index.js and execute:

NEON_API_KEY=<YOUR_NEON_API_KEY> node index.js

Expected output:

Creating a new Neon project...
Project "toolkit-demo" created successfully.
Creating 'users' table...
Inserting a new user...
Querying users...
Found users: [
  {
    name: "Sam Smith",
    createdat: 2025-09-18T12:15:35.276Z,
  }
]
Deleting the project...
Project deleted. Demo complete.

As you can see, the toolkit makes it incredibly easy to manage the lifecycle of a Neon database with just a few lines of code. The whole process from project creation to deletion is streamlined, allowing you to focus on your application's logic rather than the intricacies of database management.

Accessing the underlying API client

The toolkit is a convenience wrapper. For more advanced operations not covered by the toolkit's methods (like creating a branch, managing roles, or listing all your projects), you can access the full Neon TypeScript SDK instance via the apiClient property.

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

const toolkit = new NeonToolkit(process.env.NEON_API_KEY!);
const apiClient = toolkit.apiClient;

// Now you have the full Neon API client
// For example, listing all projects in your account:
const { data } = await apiClient.listProjects({});
console.log("All projects in your account:", data.projects);

With the apiClient, you can perform any operation supported by the Neon API. For a complete guide on its capabilities, see the TypeScript SDK for the Neon API documentation.

As with all of our experimental features, changes are ongoing. If you have any feedback, we'd love to hear it. Let us know via the Feedback form in the Neon Console or our feedback channel on Discord.