> This page location: Tools & Workflows > API, CLI & SDKs > SDKs > The @neondatabase/toolkit
> Full Neon documentation index: https://neon.com/docs/llms.txt

# The @neondatabase/toolkit

A terse client for AI agents that can spin up Postgres in seconds and run SQL queries

**What you will learn:**

- What is the @neondatabase/toolkit
- How to get started

**Related resources**

- [Neon API TypeScript SDK](https://neon.com/docs/reference/typescript-sdk)
- [Neon API Reference](https://neon.com/docs/reference/api-reference)
- [Neon Serverless Driver](https://neon.com/docs/serverless/serverless-driver)
- [Why we built @neondatabase/toolkit](https://neon.com/blog/why-neondatabase-toolkit)

**Source code**

- [@neondatabase/toolkit](https://github.com/neondatabase/toolkit)
- [@neon/toolkit (JSR)](https://jsr.io/@neon/toolkit)

## 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 API TypeScript SDK](https://neon.com/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.

**Note:** This is an experimental feature and is subject to change.

## Getting started

### Installation

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

Tab: npm

```bash
npm install @neondatabase/toolkit
```

Tab: yarn

```bash
yarn add @neondatabase/toolkit
```

Tab: pnpm

```bash
pnpm add @neondatabase/toolkit
```

Tab: jsr

```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](https://neon.com/docs/reference/neondatabase-toolkit#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=<YOUR_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 API 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 [Neon API TypeScript SDK](https://neon.com/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.

---

## Related docs (SDKs)

- [Overview](https://neon.com/docs/reference/sdk)
- [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk)
- [Neon API TypeScript SDK](https://neon.com/docs/reference/typescript-sdk)
- [Python SDK (Neon API)](https://neon.com/docs/reference/python-sdk)
- [Go SDK (Neon API)](https://neon.com/docs/https://github.com/kislerdm/neon-sdk-go)
- [Node.js / Deno SDK (Neon API)](https://neon.com/docs/https://github.com/paambaati/neon-js-sdk)