Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ const Client = require('pg-native');
✗ import { Client } from 'pg-native';
pg-native is primarily designed for CommonJS (`require`). Direct ESM `import` syntax is not officially supported and can cause resolution issues in bundlers or ESM-only environments, as it's a native module.
Client (via pg main package)
✓ const { native } = require('pg');
const { Client } = native;
✗ const Client = require('pg').native;
While `pg-native` can be required directly, it's often consumed via the `pg` package's `.native` property, which handles its lazy loading and API normalization. Direct access to `pg.native` for `Client` is preferred.
This example demonstrates how to establish an asynchronous connection to a PostgreSQL database using `pg-native`, execute basic text queries, parameterized statements, and prepared statements, ensuring proper error handling and client termination.
const Client = require('pg-native');
const client = new Client();
client.connect(process.env.PG_CONNECTION_STRING ?? 'postgresql://user:password@localhost:5432/database', function(err) {
if(err) {
console.error('Connection error:', err.message);
return;
}
console.log('Connected to PostgreSQL database.');
// Text queries
client.query('SELECT NOW() AS the_date', function(err, rows) {
if(err) throw err;
console.log('Current date:', rows[0].the_date);
// Parameterized statements
client.query('SELECT $1::text as twitter_handle', ['@briancarlson'], function(err, rows) {
if(err) throw err;
console.log('Twitter handle:', rows[0].twitter_handle);
});
});
// Using prepared statements
client.prepare('get_twitter', 'SELECT $1::text as twitter_handle', 1, function(err) {
if(err) throw err;
client.execute('get_twitter', ['@briancarlson'], function(err, rows) {
if(err) throw err;
console.log('Prepared statement result 1:', rows[0].twitter_handle);
client.execute('get_twitter', ['@realcarrotfacts'], function(err, rows) {
if(err) throw err;
console.log('Prepared statement result 2:', rows[0].twitter_handle);
client.end(function() {
console.log('Client ended connection.');
});
});
});
});
});
Debug
Known issues
breakingThe `pg-native` package requires specific PostgreSQL client libraries (like `libpq-dev`) to be pre-installed on the system for successful compilation and runtime. Installation will fail with an error code 1 if these dependencies are missing, impacting environments like Docker images without proper setup.fixBefore installing `pg-native` via npm, ensure your operating system has the necessary PostgreSQL client development packages. Examples: `apt-get install libpq-dev python3 g++ make` (Debian/Ubuntu), `brew install libpq` (macOS), `yum install postgresql-devel` (RHEL/CentOS).
affects: >=1.0.0
gotchaUsing synchronous methods like `connectSync`, `querySync`, and `executeSync` in `pg-native` can block the Node.js event loop, leading to performance issues and unresponsiveness in non-blocking environments like web servers.fixFor server-side applications, always prefer the asynchronous API (`client.connect`, `client.query`, etc.) to maintain non-blocking I/O. Reserve synchronous methods for utilities, scripts, or application bootstrapping where blocking is acceptable.
affects: >=1.0.0
breakingThere have been instances where `pg-native` might not work correctly with newer Node.js versions due to dependencies like `nan`. For example, `pg-native` failed on Node.js 23 because `node-libpq` depended on `nan` 2.19.0, which didn't officially support Node.js 23.fixCheck the `pg-native` and `node-libpq` GitHub repositories for compatibility updates with new Node.js releases. A workaround might involve overriding `nan` peer dependencies in your `package.json` to a compatible version (e.g., `"nan": "2.22.0"` for Node.js 23).
affects: >=3.x for Node.js versions >22
gotchaWhen bundling applications (e.g., with esbuild or for serverless deployments like AWS Lambda), `pg-native` can cause resolution errors because it's a native module and often a lazy `require` dependency of the main `pg` package.fixConfigure your bundler to mark `pg-native` as external. For example, in esbuild, use `external: ['pg-native']`. If using the main `pg` package, `pg.native` will return `null` if the native bindings are not found, allowing graceful fallback in some scenarios.
affects: >=1.0.0
Errors
Common errors & fixes
npm ERR! code 1
npm ERR! Failed at the pg-native@X.Y.Z install script.
PostgreSQL client development libraries (e.g., `libpq-dev`) are missing on the system, preventing `pg-native` from compiling its native bindings.
fixInstall the required system dependencies using your operating system's package manager: `sudo apt-get install libpq-dev python3 g++ make` (Debian/Ubuntu), `brew install libpq` (macOS), `sudo yum install postgresql-devel` (RHEL/CentOS).
Client.connect: connection failed: fe_sendauth: no password supplied
The PostgreSQL connection string is missing required authentication parameters (e.g., username, password, host, database name) or the server is not configured to accept the connection.
fixEnsure your connection string (e.g., `postgresql://user:password@host:port/database`) includes all necessary credentials and parameters, or that environment variables (like `PGUSER`, `PGPASSWORD`) are set, and the PostgreSQL server is configured to allow connections from your application.
ERROR: Could not resolve "pg-native" (in bundler output or serverless logs)
A bundler (like esbuild) is attempting to package `pg-native`, but it's a native module and cannot be bundled this way. It's often required lazily by `pg`.
fixMark `pg-native` as an external dependency in your bundler configuration. For esbuild, add `external: ['pg-native']` to your build options. This ensures `pg-native` is not included in the bundle and is resolved at runtime.
Audit
Dependencies
node-libpqrequiredProvides the underlying C/C++ native bindings to the PostgreSQL libpq client library.
PostgreSQL client libraries (e.g., libpq-dev)requiredRequired system-level libraries for `pg-native` to compile and function, providing `pg_config` and `libpq`.