Neon Serverless Updates & Release Notes

Type declarations are now fully inlined (some were previously re-exported from @types/pg and @types/node). The new types greatly reduce the size of the package with dependencies, and should be compatible in normal usage. The code that is actually run remains unchanged.

A few advanced type-level patterns could be affected. Code that depends on exact type identity with the @types/pg exports, that relies on declare module 'pg' augmentation flowing through these exports, or that assumes Buffer-specific types in places now declared as Uint8Array may need updated types.

Breaking change

the HTTP query template function can now only be called as a template function, not as a conventional function. This improves safety from accidental SQL-injection vulnerabilities. For example:

import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);
const id = 1;

// this is safe and convenient, as before
const result = await sql`SELECT * FROM table WHERE id = ${id}`;

// this looks very similar and was previously allowed, but was open to SQL
// injection attacks because it uses ordinary string interpolation -- it's now
// both a TypeScript type error and a runtime error
const throws = await sql(`SELECT * FROM table WHERE id = ${id}`);

To fill the gap left by this change, the template function has two new properties: a query() function that allows manually parameterized queries, and an unsafe() function that lets you interpolate trusted arbitrary string values. For example:

// this was previously allowed, and was safe, but is now also an error so as to
// prevent the vulnerability seen above
const throws = await sql('SELECT * FROM table WHERE id = $1', [id]);

// the `query()` function is the new way to manually specify placeholders and
// values (the same way it's done by `client.query()` and `pool.query()`)
const result = await sql.query('SELECT * FROM table WHERE id = $1', [id]);

// to interpolate strings like column or table names, **only** if you know
// they're safe, use the `unsafe()` function
const table = condition ? 'table1' : 'table2'; // known-safe string values
const result = await sql`SELECT * FROM ${sql.unsafe(table)} WHERE id = ${id}`;

// but in the above case, you might prefer to do this instead
const table = condition ? sql`table1` : sql`table2`;
const result = await sql`SELECT * FROM ${table} WHERE id = ${id}`;

In addition, HTTP template queries are now fully composable, including those with parameters. For example:

const name = 'Olivia';
const limit = 1;
const whereClause = sql`WHERE name = ${name}`;
const limitClause = sql`LIMIT ${limit}`;

// compilation to raw SQL now happens lazily, at query time, so that parameter
// placeholders can be numbered appropriately
const result = await sql`SELECT * FROM table ${whereClause} ${limitClause}`;

Node version requirement

The minimum supported version of Node is now v19 (this avoids having to do dynamic crypto imports, which can cause trouble with bundlers).

Repository changes

Lastly: the repository has been rearranged and refactored, .d.ts files are now generated automatically, packages are published via npm version, and comprehensive tests have been put in place. This should ease the way for future enhancements and contributions.