{"id":16452,"library":"neon-new","title":"Instant Neon PostgreSQL Database Provisioning","description":"`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.","status":"active","version":"0.14.0","language":"javascript","source_language":"en","source_url":"https://github.com/neondatabase/neon-pkgs","tags":["javascript","neon","database","postgres","cli","typescript"],"install":[{"cmd":"npm install neon-new","lang":"bash","label":"npm"},{"cmd":"yarn add neon-new","lang":"bash","label":"yarn"},{"cmd":"pnpm add neon-new","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { instantPostgres } = require('neon-new/sdk')","symbol":"instantPostgres","correct":"import { instantPostgres } from 'neon-new/sdk'"},{"note":"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.","wrong":"npm install -g neon-new && neon-new","symbol":"CLI usage (npm)","correct":"npx neon-new [options]"}],"quickstart":{"code":"import { instantPostgres } from \"neon-new/sdk\";\nimport fs from 'fs';\nimport path from 'path';\n\nasync function setupDatabase() {\n  const dotEnvPath = path.resolve(process.cwd(), '.env');\n  // Ensure .env file exists for the SDK to write to\n  if (!fs.existsSync(dotEnvPath)) {\n    fs.writeFileSync(dotEnvPath, '');\n  }\n\n  console.log(\"Creating a new Neon database...\");\n  const result = await instantPostgres({\n    referrer: process.env.NEON_APP_REFERRER || \"checklist-day-example\", // REQUIRED for SDK usage\n    dotEnvFile: \".env\",\n    dotEnvKey: \"DATABASE_URL\",\n    envPrefix: \"PUBLIC_\",\n    settings: {\n      logicalReplication: false,\n    },\n  });\n\n  console.log(\"Database created successfully!\");\n  console.log(`Pooled Connection String: ${result.databaseUrl}`);\n  console.log(`Direct Connection String: ${result.databaseUrlDirect}`);\n  console.log(`Claim URL (expires in 72h): ${result.claimUrl}`);\n  console.log(`Credentials saved to ${dotEnvPath}`);\n\n  // To connect, you would typically use a PostgreSQL client library (e.g., 'pg'):\n  // import { Client } from 'pg';\n  // const client = new Client({ connectionString: result.databaseUrl });\n  // await client.connect();\n  // const res = await client.query('SELECT NOW()');\n  // console.log('Database time:', res.rows[0].now);\n  // await client.end();\n}\n\nsetupDatabase().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"Always provide a `referrer` string in the options object, for example: `instantPostgres({ referrer: 'your-app-name', ... })`.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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+).","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you pass a `referrer` string in the options, such as `{ referrer: 'your-application-identifier' }`.","cause":"Attempting to use the `instantPostgres` SDK function without providing the mandatory `referrer` parameter in its options object.","error":"Error: The 'referrer' option is required."},{"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`).","cause":"Using CommonJS `require()` syntax to import `instantPostgres` when the `neon-new/sdk` module is an ES Module, or importing from the wrong path.","error":"TypeError: instantPostgres is not a function"},{"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.","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`).","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ...neon-new/sdk/index.js from ... not supported."},{"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.","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.","error":"Error: Your current Node.js version (vX.Y.Z) is not supported. Please upgrade to Node.js v22 or higher."}],"ecosystem":"npm"}