{"id":25887880,"url":"https://github.com/leinelissen/embedded-postgres","last_synced_at":"2025-04-04T21:05:45.217Z","repository":{"id":47262498,"uuid":"501234422","full_name":"leinelissen/embedded-postgres","owner":"leinelissen","description":"🐘 A Node package that allows you to spawn a Postgresql cluster programatically.","archived":false,"fork":false,"pushed_at":"2025-02-24T09:40:10.000Z","size":1705,"stargazers_count":64,"open_issues_count":0,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T20:05:38.980Z","etag":null,"topics":["node","nodejs","postgres","postgresql","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leinelissen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-08T12:08:20.000Z","updated_at":"2025-03-28T14:32:03.000Z","dependencies_parsed_at":"2023-12-07T10:34:54.980Z","dependency_job_id":"a7bf45cb-a569-423d-8c18-0d254d76fd2d","html_url":"https://github.com/leinelissen/embedded-postgres","commit_stats":null,"previous_names":[],"tags_count":126,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leinelissen%2Fembedded-postgres","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leinelissen%2Fembedded-postgres/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leinelissen%2Fembedded-postgres/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leinelissen%2Fembedded-postgres/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leinelissen","download_url":"https://codeload.github.com/leinelissen/embedded-postgres/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["node","nodejs","postgres","postgresql","typescript"],"created_at":"2025-03-02T18:19:52.121Z","updated_at":"2025-04-04T21:05:45.187Z","avatar_url":"https://github.com/leinelissen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Embedded Postgres](./docs/images/embedded-postgres-header.svg)\n\n\u003cdiv align=\"center\"\u003e\n\n![npm](https://img.shields.io/npm/v/embedded-postgres)\n![npm type definitions](https://img.shields.io/npm/types/embedded-postgres)\n![npm](https://img.shields.io/npm/dy/embedded-postgres)\n![NPM](https://img.shields.io/npm/l/embedded-postgres)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/leinelissen/embedded-postgres/test.yml)\n\n\n\u003c/div\u003e\n\n\u003ch3 align=\"center\"\u003e\n    🐘 A Node package that spawns PostgresQL clusters programatically.\n\u003c/h3\u003e\n\n## Installation\n`embedded-postgres` is available from NPM:\n\n```sh\nnpm i embedded-postgres\n```\n\n\u003cbr /\u003e\n\n## Usage\nThis package contains a simple API that allows you to create clusters, start\nthem, create / delete database and stop any existing processes.\n\n```ts\nimport EmbeddedPostgres from 'embedded-postgres';\n\nasync function main() {\n    // Create the object\n    const pg = new EmbeddedPostgres({\n        databaseDir: './data/db',\n        user: 'postgres',\n        password: 'password',\n        port: 5432,\n        persistent: true,\n    });\n\n    // Create the cluster config files\n    await pg.initialise();\n\n    // Start the server\n    await pg.start();\n\n    // Create and/or drop database\n    await pg.createDatabase('TEST');\n    await pg.dropDatabase('TEST');\n\n    // Initialize a node-postgres client\n    const client = pg.getPgClient();\n    await client.connect();\n    const result = await client.query('SELECT datname FROM pg_database');\n\n    // Stop the server\n    await pg.stop();\n}\n\nmain();\n```\n\n\u003cbr /\u003e\n\n## PostgresQL Versions\nThis package aims to track the [PostgresQL support\npolicy](https://www.postgresql.org/support/versioning/) for supported versions.\nAdditionally, we track the binaries that are created upstream in [zonky's\nembedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). This\nleads to the following current support matrix:\n\n| Platform / Architecture   | 13.20.0 | 14.17.0 | 15.12.0 | 16.8.0 | 17.4.0 |\n|---------------------------|---------|---------|---------|--------|--------|\n| 🍎 Darwin / x64           | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🍎 Darwin / arm64[[1]](https://github.com/zonkyio/embedded-postgres/issues/86#issuecomment-1120425822) | 🚫 | 🚫 | ✅ | ✅ | ✅ |\n| 🪟 Windows / x64          | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🐧 Linux / x64            | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🐧 Linux / arm            | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🐧 Linux / arm64          | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🐧 Linux / ia32           | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🐧 Linux / ppc64          | ✅ | ✅ | ✅ | ✅ | ✅ |\n\nIn order to install a particular version, look for the latest tag in\n[NPM](https://www.npmjs.com/package/embedded-postgres). For example, if you\nwould like to install `v10.20.0`, you can currently use the following tag:\n```sh\nnpm i embedded-postgres@10.20.0-beta.6\n```\n\nInstalling particular versions of PostgresQL (i.e. versions not released on NPM)\nis currently not possible. If you would have a need for doing so, please create\nan issue.\n\n\u003cbr /\u003e\n\n## API\nOptions in the constructor can be used to modify the behaviour of the\napplication. The parameters that are available as part of the options can be\nseen here:\n\n| Property | Type | Description |\n|---|---|---|\n| databaseDir | string | The location where the data should be persisted to. Defaults to `./data/db` |\n| port | number | The port where the Postgres database should be listening. Defaults to:  `5432` |\n| user | string | The username for logging into the Postgres database. Defaults to `postgres` |\n| password | string | The password for logging into the Postgres database. Defaults to `password` |\n| authMethod | 'scram-sha-256' \\| 'password' \\| 'md5' | The authentication method to use when authenticating against Postgres. Defaults to `password`  |\n| persistent | boolean | Whether all data should be left in place when the database is shut down. Defaults to `true`. |\n| 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. `[\"--debug\"]` or `[\"--locale=en-GB\"]`  Defaults to `[]` \n| 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. `[\"--debug\"]` or `[\"--locale=en-GB\"]`. Defaults to `[]`.  |\n| 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. \u003cbr /\u003eNOTE: 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 `false`. |\n| onLog | (message \\| string) =\u003e 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.log` |\n| onError | (messageOrError \\| string \\| Error \\| unknown) =\u003e void | Pass in a custom error logging handler. This will catch and stderr results coming in from the postgres and initdb processes. Defaults to `console.error` |\n\n\u003cbr /\u003e\n\n## Contributing\nThis package is open to issues, feedback, ideas and pull requests. Create an\nissue on this repository to get started! In order to get started with\ndevelopment, you might need some extra pointers\n\n### Development\nIn order to get yourself situated for development, you will need to the\nreopistory up and running. In order to make this work, start with a relatively\nrecent install of NodeJS (at least v18, v20+ recommended). You can then run this\ncommand to install all packages:\n```\nnpm install --force\n```\n\n\u003e [!NOTE]\n\u003e You must include `--force` or else NPM will refuse to install the\n\u003e dependencies for all packages, including those not for the current architecture.\n\nThen, you must pre-compile all Typescript using the following command:\n```\nnpm run build\n```\n\nAs soon as that is complete, we'll download the requisite PostgresQL binaries\nfor your particular architecture using:\n```\nnpm run download\n```\n\nLastly, you can hop over to `packages/embedded-postgres` and do some development\nthere:\n```\ncd packages/embedded-postgres\n```\n\nYou can force automatic recompliation of the Typescript files by running:\n```\nnpm start\n```\n\nDon't forget to add and run tests when you are developing new functionality. Add\nthem to `tests/index.test.ts`, and run the tests by running:\n```\nnpm test\n```\n\n\u003cbr /\u003e\n\n## Troubleshotting\n\n### Running in Docker containers\nRunning in Docker containers might fail, because many are setup to run with the\nroot user as default. Either you resolve to setting up a container with a\nspecific user yourself, or you set the `createPostgresUser` option to true,\nafter which embedded-postgres will automatically set up a postgres user on the\nsystem for usage by your script.\n\n\u003cbr /\u003e\n\n## Credits and Licensing\nEmbedded Postgres was created by Lei Nelissen for [BMD\nStudio](https://bmd.studio). It is based on [zonky's\nembedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The\nbinaries are made available under the Apache License 2.0, whereas the specific\ncode in this package is made available under the MIT license.\n\n\u003ca href=\"https://bmd.studio\"\u003e\n    \u003cimg src=\"./docs/images/logo-bmd.svg\" alt=\"BMD Studio\" width=\"150\" height=\"150\" /\u003e\n\u003c/a\u003e\n\n\u003cbr /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleinelissen%2Fembedded-postgres","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleinelissen%2Fembedded-postgres","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleinelissen%2Fembedded-postgres/lists"}