Registry / database / embedded-postgres

embedded-postgres

JSON →
library18.3.0-beta.17jsnpmunverified

Embedded Postgres is a Node.js package designed to programmatically spawn and manage PostgreSQL database clusters directly within your application runtime. It simplifies local development, testing, and CI/CD pipelines by eliminating the need for pre-installed PostgreSQL instances. The package, currently in beta (version 18.3.0-beta.17), abstracts away the complexities of PostgreSQL binary management by leveraging `zonkyio/embedded-postgres-binaries` and tracking PostgreSQL's official support policy. This means new PostgreSQL major versions are typically supported annually, with minor bug and security fixes integrated quarterly. Key differentiators include its ability to fully manage the PostgreSQL lifecycle (initialization, start, stop, create/drop databases), provide direct access to a `node-postgres` client, and offer configurable persistence, making it a robust solution for environments requiring ephemeral or managed PostgreSQL instances.

npm install embedded-postgres
INSTALL
IMPORT
SIG · EMBEDDED-POSTGRES
E
embedded-postgres
databasejavascriptv18.3.0-beta.17
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

EmbeddedPostgres
import EmbeddedPostgres from 'embedded-postgres';
const EmbeddedPostgres = require('embedded-postgres');
The library is designed for ESM environments and ships with TypeScript definitions. While CommonJS `require` might work in some setups, the recommended approach is ESM `import`.
EmbeddedPostgresOptions
import type { EmbeddedPostgresOptions } from 'embedded-postgres';
Import the type for constructor options for better type safety in TypeScript projects.

This quickstart demonstrates the full lifecycle of an embedded PostgreSQL instance, including initialization, starting the server, creating and dropping a database, connecting with a `node-postgres` client to perform queries, and properly stopping the server.

import EmbeddedPostgres from 'embedded-postgres'; async function main() { // Create the object with custom options for data directory, user, password, port, and persistence. const pg = new EmbeddedPostgres({ databaseDir: './data/db', user: 'testuser', password: 'testpassword', port: 5433, // Use a non-default port to avoid conflicts persistent: true, }); try { // Create the cluster configuration files and data directory. await pg.initialise(); // Start the PostgreSQL server process. await pg.start(); // Create a new database named 'MYAPP_DB'. await pg.createDatabase('MYAPP_DB'); // Initialize a node-postgres client using the embedded instance's connection details. const client = pg.getPgClient(); await client.connect(); // Execute a simple query to verify connection and functionality. const result = await client.query('SELECT current_database(), current_user, pg_backend_pid() AS pid;'); console.log('PostgreSQL server started and connected successfully.'); console.log('Connected to database:', result.rows[0].current_database); console.log('Current user:', result.rows[0].current_user); console.log('Backend PID:', result.rows[0].pid); // Example: Create a table and insert data await client.query('CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(255));'); await client.query("INSERT INTO users (name) VALUES ('Alice'), ('Bob');"); const users = await client.query('SELECT * FROM users;'); console.log('Users:', users.rows); // Drop the created database, cleaning up. await pg.dropDatabase('MYAPP_DB'); } catch (error) { console.error('An error occurred:', error); } finally { // Ensure the server is stopped, even if errors occur. await pg.stop(); console.log('PostgreSQL server stopped.'); } } main();
Debug
Known issues
gotchaThe package requires post-install scripts to generate necessary symlinks for PostgreSQL operation. If you have post-install scripts disabled (e.g., when using PNPM with strict settings or in certain CI/CD environments), you will need to manually approve or enable them, or the package will not function correctly.
fix
For PNPM, run `pnpm approve-builds` after installation. For other environments, ensure `ignore-scripts` is not enabled in your npm/yarn configuration, or explicitly enable script execution.
affects: >=1.0.0
breakingThe package version `18.3.0-beta.17` indicates a beta release. API stability is not guaranteed, and breaking changes might occur in subsequent beta or stable releases. Users should exercise caution when deploying beta versions in production and monitor release notes for changes.
fix
Consult the project's GitHub releases and changelog for detailed information on API changes between versions. Pin to specific beta versions if necessary, but prepare for potential refactoring when upgrading to stable releases.
affects: >=18.3.0-beta.0
gotchaPostgreSQL binaries have specific platform and architecture support. Older PostgreSQL versions might not be available for all combinations (e.g., Darwin arm64 for PostgreSQL versions prior to 15.x). Attempting to use an unsupported combination will lead to installation or startup failures.
fix
Refer to the 'PostgreSQL Versions' matrix in the documentation to verify compatibility for your desired PostgreSQL version and target platform/architecture. If an older version is required on a newer architecture, consider upgrading the PostgreSQL version.
affects: >=1.0.0
gotchaPostgreSQL, by design, cannot be run by the root user due to security considerations. In environments like Docker containers where applications often run as root by default, this can prevent the embedded database from starting.
fix
Configure your Dockerfile or runtime environment to use a non-root user (e.g., `USER node`) to execute your application and the embedded PostgreSQL instance. Alternatively, for development, you might be able to use `--privileged` with Docker, but this is not recommended for production.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Command failed with exit code 1: initdb ...
The PostgreSQL `initdb` command failed during initialization, often due to missing symlinks or incorrect permissions, which can be caused by disabled post-install scripts or running as the root user.
fix
Ensure post-install scripts are enabled (e.g., `pnpm approve-builds`). Verify that the process running `embedded-postgres` is not `root`. Check system logs for more specific `initdb` errors.
Error: libpq.so.5: cannot open shared object file: No such file or directory
This error typically occurs on Linux systems when the dynamic linker cannot find the `libpq.so.5` shared library, which is part of the PostgreSQL binaries. It means the library path is not correctly configured or the binaries were not extracted properly.
fix
Ensure the post-install script ran successfully. If the issue persists, you might need to manually add the directory containing `libpq.so.5` (usually `<databaseDir>/bin` or `<databaseDir>/lib`) to your system's dynamic linker search path (e.g., via `/etc/ld.so.conf.d/`).
Error: connect ECONNREFUSED 127.0.0.1:<port>
The Node.js `node-postgres` client attempted to connect to the PostgreSQL server but was refused. This indicates the embedded PostgreSQL server either failed to start, is not listening on the expected port, or was already stopped.
fix
Check the console output for any errors during `pg.start()` or `pg.initialise()`. Verify that the `port` option in `EmbeddedPostgres` constructor matches the one the client is trying to connect to. Ensure the server has enough time to start before the client attempts connection.
Upgrade
Version history
18.3.0-beta.17latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
Resources
embedded-postgres — npm install embedded-postgres · libregistry