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-postgresVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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.
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.
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/`).
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.
No dependency data recorded yet.