Instant Neon PostgreSQL Database Provisioning

0.14.0 · active · verified Wed Apr 22

`neon-new` (version 0.14.0) is a specialized command-line interface (CLI) and Software Development Kit (SDK) designed to facilitate the rapid, ephemeral provisioning of new, claimable Neon PostgreSQL databases. It aims to eliminate initial setup friction by allowing developers to instantiate a functional database with a single command or function call, without requiring immediate sign-up. The package currently ships with TypeScript types and targets Node.js environments. Its primary differentiating feature is the speed and ease of obtaining a fully functional PostgreSQL connection string, which is highly beneficial for rapid prototyping, local development, and CI/CD environments where temporary, on-demand databases are advantageous. While not having a strictly defined release cadence, the project is under active development, indicated by its pre-1.0.0 versioning, and has seen frequent updates. Users should be aware that databases generated this way are temporary and will expire if not formally claimed within 72 hours, making them ideal for short-lived use cases or as an initial stepping stone before migrating to a persistent, owned Neon project.

Common errors

```
Error: The 'referrer' option is required.
```
cause Attempting to use the `instantPostgres` SDK function without providing the mandatory `referrer` parameter in its options object.

fix Ensure you pass a `referrer` string in the options, such as `{ referrer: 'your-application-identifier' }`.
```
TypeError: instantPostgres is not a function
```
cause Using CommonJS `require()` syntax to import `instantPostgres` when the `neon-new/sdk` module is an ES Module, or importing from the wrong path.

fix Switch to ES Module `import` syntax: `import { instantPostgres } from 'neon-new/sdk';`. Ensure your Node.js environment is configured for ESM (e.g., `"type": "module"` in `package.json`).
```
Error [ERR_REQUIRE_ESM]: require() of ES Module ...neon-new/sdk/index.js from ... not supported.
```
cause Attempting to `require()` an ES Module (`neon-new/sdk`) from a CommonJS context (e.g., a `.js` file without `"type": "module"` in `package.json`).

fix To use the SDK, ensure your project's `package.json` contains `"type": "module"` or use `.mjs` file extensions for your source code. Then, use `import` statements.
```
Error: Your current Node.js version (vX.Y.Z) is not supported. Please upgrade to Node.js v22 or higher.
```
cause Executing the `neon-new` CLI or SDK in an environment with a Node.js version older than 22, which is explicitly required by the package.

fix Upgrade your Node.js installation to version 22 or newer. If you need to manage multiple Node.js versions, tools like `nvm` are highly recommended.

Warnings

breaking This package requires Node.js version 22 or higher. Users on older Node.js versions will encounter an error during execution, as specified by the `engines.node` field.
Fix: Upgrade your Node.js environment to version 22 or newer. Consider using a Node Version Manager (like `nvm` or `volta`) to manage different Node.js versions.
gotcha The `referrer` option is a mandatory parameter when invoking the `instantPostgres` function from the SDK. Failing to provide a referrer string will result in a runtime error.
Fix: Always provide a `referrer` string in the options object, for example: `instantPostgres({ referrer: 'your-app-name', ... })`.
gotcha Databases provisioned via `neon-new` are temporary by default and will automatically expire if not formally claimed by a Neon account within 72 hours. This is a critical consideration for data persistence.
Fix: For long-term usage, ensure you visit the provided `claimUrl` within the 72-hour window to link the database to your Neon account. For ephemeral use, be aware of the data lifetime.
gotcha The package is currently in a pre-1.0.0 state (version 0.14.0). While actively developed, the API surface, configuration options, and behaviors might be subject to change in future minor or patch releases without strictly adhering to semantic versioning for breaking changes (as would be expected for versions 1.0.0+).
Fix: It is advisable to pin your `neon-new` dependency to an exact version or to thoroughly review release notes when upgrading to new versions to anticipate and mitigate potential changes.

Install

npm install neon-new npm
yarn add neon-new yarn
pnpm add neon-new pnpm

Imports

instantPostgres
wrong:
```
const { instantPostgres } = require('neon-new/sdk')
```
correct:
```
import { instantPostgres } from 'neon-new/sdk'
```
The SDK module (`neon-new/sdk`) is an ES Module and should be imported using `import` syntax in an ES Module context. CommonJS `require()` is not supported.
CLI usage (npm)
wrong:
```
npm install -g neon-new && neon-new
```
correct:
```
npx neon-new [options]
```
The CLI is designed for ephemeral execution via `npx` (or `pnpx`, `yarn dlx`, `bunx`, `deno run npm:`), avoiding global installation and ensuring the latest version is used. Direct global installation is not the recommended pattern.

Quickstart

Demonstrates how to programmatically create a new Neon PostgreSQL database using the SDK, save its credentials to a .env file, and log the connection details and claim URL. Requires Node.js >= 22.

import { instantPostgres } from "neon-new/sdk";
import fs from 'fs';
import path from 'path';

async function setupDatabase() {
  const dotEnvPath = path.resolve(process.cwd(), '.env');
  // Ensure .env file exists for the SDK to write to
  if (!fs.existsSync(dotEnvPath)) {
    fs.writeFileSync(dotEnvPath, '');
  }

  console.log("Creating a new Neon database...");
  const result = await instantPostgres({
    referrer: process.env.NEON_APP_REFERRER || "checklist-day-example", // REQUIRED for SDK usage
    dotEnvFile: ".env",
    dotEnvKey: "DATABASE_URL",
    envPrefix: "PUBLIC_",
    settings: {
      logicalReplication: false,
    },
  });

  console.log("Database created successfully!");
  console.log(`Pooled Connection String: ${result.databaseUrl}`);
  console.log(`Direct Connection String: ${result.databaseUrlDirect}`);
  console.log(`Claim URL (expires in 72h): ${result.claimUrl}`);
  console.log(`Credentials saved to ${dotEnvPath}`);

  // To connect, you would typically use a PostgreSQL client library (e.g., 'pg'):
  // import { Client } from 'pg';
  // const client = new Client({ connectionString: result.databaseUrl });
  // await client.connect();
  // const res = await client.query('SELECT NOW()');
  // console.log('Database time:', res.rows[0].now);
  // await client.end();
}

setupDatabase().catch(console.error);

view raw JSON →