Identify Serverless driver connections

Author: conradludgate

build.sh

@@ -1,6 +1,8 @@
 #!/usr/bin/env bash 
 set -e
 
+PACKAGE_VERSION=$(node -p "require('./package.json').version")
+
 # if nothing modified, stop (`touch src` to force build)
 find src -newer index.js | read || exit 0
 
@@ -20,6 +22,7 @@ npx esbuild src/index.ts \
   --keep-names \
   --inject:src/shims/shims.js \
   --define:BUNDLE_EXT=\"js\" \
+  --define:PACKAGE_VERSION=\"$PACKAGE_VERSION\" \
   --target=es2020 \
   --outfile=index.js \
   $DEBUG_ARG $MINIFY_ARG
@@ -32,6 +35,7 @@ npx esbuild src/index.ts \
   --keep-names \
   --inject:src/shims/shims.js \
   --define:BUNDLE_EXT=\"mjs\" \
+  --define:PACKAGE_VERSION=\"$PACKAGE_VERSION\" \
   --target=es2020 \
   --banner:js='/* @ts-self-types="./index.d.mts" */' \
   --outfile=index.mjs \

index.js

@@ -1,6 +1,7 @@
 import { Client, Connection, type ClientConfig } from 'pg';
 import { Socket } from './shims/net';
 import { warnIfBrowser } from './utils';
+import { PACKAGE_URL } from './packageInfo';
 
 export declare interface NeonClient {
   connection: Connection & {
@@ -25,7 +26,11 @@ export class NeonClient extends Client {
   }
 
   constructor(public config?: string | ClientConfig) {
-    super(config);
+    super(
+      typeof config === 'string'
+        ? { connectionString: config, fallback_application_name: PACKAGE_URL }
+        : { fallback_application_name: PACKAGE_URL, ...config },
+    );
   }
 
   override connect(): Promise<void>;

index.mjs

@@ -28,6 +28,7 @@ import type {
 } from './httpTypes';
 import { SqlTemplate, UnsafeRawSql } from './sqlTemplate';
 import { warnIfBrowser } from './utils';
+import { PACKAGE_URL } from './packageInfo';
 
 import { Socket as neonConfig } from './shims/net';
 
@@ -351,6 +352,7 @@ export function neon<
       'Neon-Connection-String': connectionString,
       'Neon-Raw-Text-Output': 'true', // because we do our own parsing with node-postgres
       'Neon-Array-Mode': 'true', // this saves data and post-processing even if we return objects, not arrays
+      'Neon-Client-Info': PACKAGE_URL,
     };
 
     // --- add auth token to headers ---

src/client.ts

@@ -0,0 +1,3 @@
+declare const PACKAGE_VERSION: string;
+
+export const PACKAGE_URL = `pkg:npm/%40neondatabase/serverless@${PACKAGE_VERSION}`;

src/httpQuery.ts

@@ -8,6 +8,7 @@ import {
   type FullQueryResults,
 } from '@neondatabase/serverless'; // see package.json: this points to 'file:.'
 import { sampleQueries } from './sampleQueries';
+import packageMetadata from '../../package.json';
 
 const DATABASE_URL = process.env.VITE_NEON_DB_URL!;
 const sql = neon(DATABASE_URL);
@@ -205,6 +206,31 @@ test('custom fetch', async () => {
   }
 });
 
+test('sends the package URL with HTTP queries', async () => {
+  const prevFetchFunction = neonConfig.fetchFunction;
+  try {
+    const fn = vi.fn(async () =>
+      Response.json({
+        fields: [],
+        rows: [],
+        command: 'SELECT',
+        rowCount: 0,
+      }),
+    );
+    neonConfig.fetchFunction = fn;
+
+    const mockedSql = neon('postgres://user@example.com/database');
+    await mockedSql`SELECT`;
+
+    expect(fn).toHaveBeenCalledOnce();
+    expect(fn.mock.calls[0][1]?.headers).toMatchObject({
+      'Neon-Client-Info': `pkg:npm/%40neondatabase/serverless@${packageMetadata.version}`,
+    });
+  } finally {
+    neonConfig.fetchFunction = prevFetchFunction;
+  }
+});
+
 test('errors match WebSocket query errors', async () => {
   const q = 'SELECT 123 WHERE x';
 

src/packageInfo.ts

@@ -3,6 +3,7 @@ import { Pool as PgPool, type QueryResult } from 'pg';
 import * as subtls from 'subtls';
 import { sampleQueries } from './sampleQueries';
 import { ISRGX1Cert } from './subtlsCert';
+import packageMetadata from '../../package.json';
 import {
   neon,
   neonConfig,
@@ -34,6 +35,19 @@ const DB_POOLER_URL = process.env.VITE_NEON_DB_POOLER_URL!;
 
 const pgPool = new PgPool({ connectionString: DB_DIRECT_URL });
 
+test('uses the package URL as the default application name', () => {
+  const expected = `pkg:npm/%40neondatabase/serverless@${packageMetadata.version}`;
+
+  const defaultClient = new WsClient('postgres://user@example.com/database');
+  expect(defaultClient.getStartupConf().application_name).toBe(expected);
+
+  const namedClient = new WsClient({
+    connectionString: 'postgres://user@example.com/database',
+    application_name: 'custom-client',
+  });
+  expect(namedClient.getStartupConf().application_name).toBe('custom-client');
+});
+
 describe.each([
   {
     DB_URL: DB_DIRECT_URL,