A package to run an embedded Postgresql database right from NodeJS
npm install embedded-postgresembedded-postgres is available from NPM:``sh`
npm i embedded-postgres
`ts
import EmbeddedPostgres from 'embedded-postgres';
async function main() {
// Create the object
const pg = new EmbeddedPostgres({
databaseDir: './data/db',
user: 'postgres',
password: 'password',
port: 5432,
persistent: true,
});
// Create the cluster config files
await pg.initialise();
// Start the server
await pg.start();
// Create and/or drop database
await pg.createDatabase('TEST');
await pg.dropDatabase('TEST');
// Initialize a node-postgres client
const client = pg.getPgClient();
await client.connect();
const result = await client.query('SELECT datname FROM pg_database');
// Stop the server
await pg.stop();
}
main();
`
| Platform / Architecture | 12.20.0 | 13.16.0 | 14.13.0 | 15.8.0 | 16.4.0 | 17.0.0 |
|---------------------------|---------|---------|---------|--------|--------|--------|
| 🍎 Darwin / x64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 🍎 Darwin / arm64[[1]](https://github.com/zonkyio/embedded-postgres/issues/86#issuecomment-1120425822) | 🚫 | 🚫 | 🚫 | ✅ | ✅ | ✅ |
| 🪟 Windows / x64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 🐧 Linux / x64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 🐧 Linux / arm | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 🐧 Linux / arm64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 🐧 Linux / ia32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 🐧 Linux / ppc64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
In order to install a particular version, look for the latest tag in
NPM. For example, if you
would like to install v10.20.0, you can currently use the following tag:`sh`
npm i embedded-postgres@10.20.0-beta.6
Installing particular versions of PostgresQL (i.e. versions not released on NPM)
is currently not possible. If you would have a need for doing so, please create
an issue.
| Property | Type | Description |
|---|---|---|
| databaseDir | string | The location where the data should be persisted to. Defaults to ./data/db |5432
| port | number | The port where the Postgres database should be listening. Defaults to: |postgres
| user | string | The username for logging into the Postgres database. Defaults to |password
| password | string | The password for logging into the Postgres database. Defaults to |password
| authMethod | 'scram-sha-256' \| 'password' \| 'md5' | The authentication method to use when authenticating against Postgres. Defaults to |true
| persistent | boolean | Whether all data should be left in place when the database is shut down. Defaults to . |["--debug"]
| initdbFlags | string[] | Pass any additional flags to the initdb process. You can find all available flags here: https://www.postgresql.org/docs/current/app-initdb.html. Flags should be passed as a string array, e.g. or ["--locale=en-GB"] Defaults to [] ["--debug"]
| postgresFlags | string[] | Pass any additional flags to the postgres process. You can find all available flags here: https://www.postgresql.org/docs/current/app-postgres.html. Flags should be passed as a string array, e.g. or ["--locale=en-GB"]. Defaults to []. |false
| createPostgresUser | boolean | Postgres does not allow binaries to be run by root. In case you're running in root-only enviroments, such as Docker containers, you may need to create an extra user on your system in order to be able to call the binaries.
NOTE: This WILL irreversibly modify your host system. The effects are somewhat minor, but it's still recommend to only use this in Docker containers. Defaults to . |console.log
| onLog | (message \| string) => void | Pass in a custom logging handler. This will relay and console messages that are generated by the postgres and initdb processes. Defaults to |console.error
| onError | (messageOrError \| string \| Error \| unknown) => void | Pass in a custom error logging handler. This will catch and stderr results coming in from the postgres and initdb processes. Defaults to |
npm install --force
`> [!NOTE]
> You must include
--force or else NPM will refuse to install the
> dependencies for all packages, including those not for the current architecture.Then, you must pre-compile all Typescript using the following command:
`
npm run build
`As soon as that is complete, we'll download the requisite PostgresQL binaries
for your particular architecture using:
`
npm run download
`Lastly, you can hop over to
packages/embedded-postgres and do some development
there:
`
cd packages/embedded-postgres
`You can force automatic recompliation of the Typescript files by running:
`
npm start
`Don't forget to add and run tests when you are developing new functionality. Add
them to
tests/index.test.ts, and run the tests by running:
`
npm test
`
Troubleshotting
$3
Running in Docker containers might fail, because many are setup to run with the
root user as default. Either you resolve to setting up a container with a
specific user yourself, or you set the createPostgresUser` option to true,