---
title: The @neondatabase/toolkit
subtitle: A terse client for AI agents that can spin up Postgres in seconds and run SQL
queries
enableTableOfContents: true
updatedOn: '2025-10-10T13:19:39.266Z'
---
What is the @neondatabase/toolkit
How to get started
TypeScript SDK for the Neon APINeon API ReferenceNeon Serverless DriverWhy we built @neondatabase/toolkit@neondatabase/toolkit@neon/toolkit (JSR)
## About the toolkit
The [@neondatabase/toolkit](https://github.com/neondatabase/toolkit) ([@neon/toolkit](https://jsr.io/@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](/docs/reference/typescript-sdk) and the [Neon Serverless Driver](https://github.com/neondatabase/serverless), 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.
This is an experimental feature and is subject to change.
Working with AI coding assistants? Check out our [AI rules for the @neondatabase/toolkit](/docs/ai/ai-rules-neon-toolkit) to help your AI assistant create, query, and destroy ephemeral Neon Postgres databases.
## Getting started
### Installation
Install the `@neondatabase/toolkit` package into your project using your preferred package manager:
```bash
npm install @neondatabase/toolkit
```
```bash
yarn add @neondatabase/toolkit
```
```bash
pnpm add @neondatabase/toolkit
```
```bash
deno add jsr:@neon/toolkit
```
### Authentication
The toolkit requires a Neon API key to interact with your account.
1. Log in to the [Neon Console](https://console.neon.tech/).
2. Navigate to [Account settings > API keys](https://console.neon.tech/app/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.
```bash
export NEON_API_KEY="YOUR_API_KEY_FROM_NEON_CONSOLE"
```
## Raw Methods
> Feel free to skip to the [Complete Example](#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.
```javascript
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](https://api-docs.neon.tech/reference/createproject).
```javascript
// 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.
```javascript
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`.
```javascript
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.
```javascript
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:
```bash
NEON_API_KEY= node index.js
```
**Expected output:**
```text
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.
```javascript
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](/docs/reference/typescript-sdk) 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](https://console.neon.tech/app/projects?modal=feedback) form in the Neon Console or our [feedback channel](https://discord.com/channels/1176467419317940276/1176788564890112042) on Discord.