{"id":43406,"library":"neon-serverless","title":"Neon Serverless PostgreSQL Driver","description":"@neondatabase/serverless is a PostgreSQL driver optimized for serverless and edge environments (e.g., Vercel Edge, Cloudflare Workers) from Neon.tech. At version 0.5.3 (beta), it offers two APIs: a simple `neon` function for one-shot queries over HTTPS fetch, and Pool/Client for sessions/transactions via WebSockets. It is a drop-in replacement for the popular `pg` package (node-postgres) with message pipelining for low latency. It ships TypeScript types and is ESM-only. Key differentiators: works in edge runtimes without Node.js TCP, supports SQL template tag injection safety, and integrates tightly with Neon's serverless Postgres offering.","status":"active","version":"0.5.3","language":"javascript","source_language":"en","source_url":"https://github.com/neondatabase/serverless","tags":["javascript","Neon","serverless","Postgres","PostgreSQL","pg","database","SQL","edge","typescript"],"install":[{"cmd":"npm install neon-serverless","lang":"bash","label":"npm"},{"cmd":"yarn add neon-serverless","lang":"bash","label":"yarn"},{"cmd":"pnpm add neon-serverless","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional peer dependency for WebSocket support in Node.js environments lacking native WebSocket","package":"ws","optional":true},{"reason":"Inherits types and some internals from the `pg` package for compatibility","package":"pg","optional":false}],"imports":[{"note":"Default export is not available; must use named import. ESM-only, no CJS require().","wrong":"import neon from '@neondatabase/serverless'","symbol":"neon","correct":"import { neon } from '@neondatabase/serverless'"},{"note":"CommonJS require is not supported since v0.x ESM-only. Pool uses WebSockets, requires a WebSocket constructor in Node.js.","wrong":"const { Pool } = require('@neondatabase/serverless')","symbol":"Pool","correct":"import { Pool } from '@neondatabase/serverless'"},{"note":"Use the provided Client, not the one from 'pg'. Must be created and closed within each request handler in serverless environments.","wrong":"import { Client } from 'pg'","symbol":"Client","correct":"import { Client } from '@neondatabase/serverless'"},{"note":"Used for advanced configuration like setting custom WebSocket constructor or fetch implementation.","wrong":"import { Config } from '@neondatabase/serverless'","symbol":"NeonConfig","correct":"import { NeonConfig } from '@neondatabase/serverless'"}],"quickstart":{"code":"import { neon } from '@neondatabase/serverless';\n\nconst sql = neon(process.env.DATABASE_URL ?? '');\n\nasync function getPost(postId: number) {\n  const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;\n  return post;\n}\n\n// Example usage\nconst post = await getPost(1);\nconsole.log(post);","lang":"typescript","description":"Shows how to set up and use the `neon` function for a simple one-shot query with SQL template tag safety and TypeScript."},"warnings":[{"fix":"Use dynamic import or switch to ESM in your project (set `\"type\": \"module\"` in package.json).","message":"ESM-only: The package does not support CommonJS require(). Using require() will throw a runtime error.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Create, use, and close Pool/Client inside the request handler. Do not store them globally.","message":"Pool/Client cannot be reused across requests in serverless environments (e.g., Vercel Edge, Cloudflare Workers). WebSocket connections are request-scoped.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Replace `arrayMode: true` with `fullResults: true` in the options object.","message":"The `neon` function's `arrayMode` option is deprecated in favor of the `fullResults` option.","severity":"deprecated","affected_versions":">=0.3.0"},{"fix":"Use import { Pool, Client, neon } from '@neondatabase/serverless' instead of from 'pg'.","message":"Using `pg` types directly may cause incompatibility; always import types from `@neondatabase/serverless`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For transactions, use `import { Pool } from '@neondatabase/serverless'` and wrap queries in `BEGIN`/`COMMIT`.","message":"The `neon` function does not support transactions or multiple statements in one call. Use Pool/Client for transactions.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.5.3':25 'api':30 'beta':26 'cloudflar':19 'databas':109 'differenti':80 'driver':4,9 'drop':53 'drop-in':52 'e.g':16 'edg':14,18,83,111 'environ':15 'esm':77 'esm-on':76 'fetch':42 'function':34 'https':41 'inject':92 'integr':95 'javascript':103 'key':79 'latenc':69 'low':68 'messag':65 'neon':1,33,98,104 'neon.tech':22 'neondatabase/serverless':5 'node':62 'node-postgr':61 'node.js':86 'offer':28,102 'one':37 'one-shot':36 'optim':10 'packag':60 'pg':59,108 'pipelin':66 'pool/client':44 'popular':58 'postgr':63,101,106 'postgresql':3,8,107 'queri':39 'replac':55 'runtim':84 'safeti':93 'serverless':2,12,100,105 'sessions/transactions':46 'ship':71 'shot':38 'simpl':32 'sql':89,110 'support':88 'tag':91 'tcp':87 'templat':90 'tight':96 'two':29 'type':73 'typescript':72,112 'vercel':17 'version':24 'via':47 'websocket':48 'without':85 'work':81 'worker':20","created_at":"2026-06-05T16:59:38.756059+00:00","updated_at":"2026-06-05T16:59:38.756059+00:00","problems":[{"fix":"Change to dynamic import: `const { neon } = await import('@neondatabase/serverless');` or set `\"type\": \"module\"`.","cause":"Package is ESM-only but being imported with require()","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /node_modules/@neondatabase/serverless/index.js from /app/index.js not supported."},{"fix":"Install the `ws` package and set `NeonConfig.webSocketConstructor = WebSocket;` before creating Pool/Client.","cause":"Using Pool/Client in Node.js without providing a WebSocket constructor","error":"TypeError: WebSocket is not defined"},{"fix":"Move the `new Pool()` call inside the request handler and close it before returning.","cause":"Pool is created at module scope in a serverless environment","error":"Error: Cannot create a Pool outside of a request handler"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://neon.tech","github":"https://github.com/neondatabase/serverless","docs":null,"changelog":null,"pypi":null,"npm":"neon-serverless","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}