4 |
5 | 
6 | 
7 | 
8 | 
9 | 
10 |
11 |
12 |
13 | 14 | 🐘 A Node package that spawns PostgresQL clusters programatically. 15 |
16 | 17 | This package contains the `linux-arm` Postgres binaries for use with the `embedded-postgres` 18 | package. See 19 | [embedded-postgres](https://github.com/leinelissen/embedded-postgres) for a more 20 | developer-friendly way of spawning PostgresQL clusters. 21 | 22 | ## Installation 23 | `embedded-postgres` is available from NPM: 24 | 25 | ```sh 26 | npm i embedded-postgres 27 | ``` 28 | 29 |30 | 31 | ## Using just the binaries 32 | If you just want to use the binaries, you can also just use this package 33 | directly. It exports the paths to the 34 | [`pg_ctl`](https://www.postgresql.org/docs/current/app-pg-ctl.html), 35 | [`initdb`](https://www.postgresql.org/docs/current/app-initdb.html) and 36 | [`postgres`](https://www.postgresql.org/docs/current/app-postgres.html) binaries 37 | for `linux-arm`. 38 | 39 | ```sh 40 | npm i @embedded-postgres/linux-arm 41 | ``` 42 | 43 | 44 | Follow the documentation to discover how to interface with the binaries. Any implementation is going to look something like this: 45 | ```ts 46 | import { pg_ctl, initdb, postgres } from '@embedded-postgres/linux-arm' 47 | import { execSync, spawn } from 'child_process'; 48 | 49 | execSync(initdb); 50 | spawn(postgres); 51 | ``` 52 | 53 | > [!IMPORTANT] 54 | > A more friendly wrapper for using these binaries is provided as the 55 | > [embedded-postgres](https://github.com/leinelissen/embedded-postgres) package. 56 | > Please use it if you're confused by the binaries. 57 | 58 | ## Credits and Licensing 59 | Embedded Postgres was created by Lei Nelissen for [BMD 60 | Studio](https://bmd.studio). It is based on [zonky's 61 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The 62 | binaries are made available under the Apache License 2.0, whereas the specific 63 | code in this package is made available under the MIT license. 64 | 65 | 66 |
67 |
68 |
69 | 70 | -------------------------------------------------------------------------------- /packages/linux-x64/README.md: -------------------------------------------------------------------------------- 1 |  2 | 3 |
4 |
5 | 
6 | 
7 | 
8 | 
9 | 
10 |
11 |
12 |
13 | 14 | 🐘 A Node package that spawns PostgresQL clusters programatically. 15 |
16 | 17 | This package contains the `linux-x64` Postgres binaries for use with the `embedded-postgres` 18 | package. See 19 | [embedded-postgres](https://github.com/leinelissen/embedded-postgres) for a more 20 | developer-friendly way of spawning PostgresQL clusters. 21 | 22 | ## Installation 23 | `embedded-postgres` is available from NPM: 24 | 25 | ```sh 26 | npm i embedded-postgres 27 | ``` 28 | 29 |30 | 31 | ## Using just the binaries 32 | If you just want to use the binaries, you can also just use this package 33 | directly. It exports the paths to the 34 | [`pg_ctl`](https://www.postgresql.org/docs/current/app-pg-ctl.html), 35 | [`initdb`](https://www.postgresql.org/docs/current/app-initdb.html) and 36 | [`postgres`](https://www.postgresql.org/docs/current/app-postgres.html) binaries 37 | for `linux-x64`. 38 | 39 | ```sh 40 | npm i @embedded-postgres/linux-x64 41 | ``` 42 | 43 | 44 | Follow the documentation to discover how to interface with the binaries. Any implementation is going to look something like this: 45 | ```ts 46 | import { pg_ctl, initdb, postgres } from '@embedded-postgres/linux-x64' 47 | import { execSync, spawn } from 'child_process'; 48 | 49 | execSync(initdb); 50 | spawn(postgres); 51 | ``` 52 | 53 | > [!IMPORTANT] 54 | > A more friendly wrapper for using these binaries is provided as the 55 | > [embedded-postgres](https://github.com/leinelissen/embedded-postgres) package. 56 | > Please use it if you're confused by the binaries. 57 | 58 | ## Credits and Licensing 59 | Embedded Postgres was created by Lei Nelissen for [BMD 60 | Studio](https://bmd.studio). It is based on [zonky's 61 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The 62 | binaries are made available under the Apache License 2.0, whereas the specific 63 | code in this package is made available under the MIT license. 64 | 65 | 66 |
67 |
68 |
69 | 70 | -------------------------------------------------------------------------------- /packages/darwin-x64/README.md: -------------------------------------------------------------------------------- 1 |  2 | 3 |
4 |
5 | 
6 | 
7 | 
8 | 
9 | 
10 |
11 |
12 |
13 | 14 | 🐘 A Node package that spawns PostgresQL clusters programatically. 15 |
16 | 17 | This package contains the `darwin-x64` Postgres binaries for use with the `embedded-postgres` 18 | package. See 19 | [embedded-postgres](https://github.com/leinelissen/embedded-postgres) for a more 20 | developer-friendly way of spawning PostgresQL clusters. 21 | 22 | ## Installation 23 | `embedded-postgres` is available from NPM: 24 | 25 | ```sh 26 | npm i embedded-postgres 27 | ``` 28 | 29 |30 | 31 | ## Using just the binaries 32 | If you just want to use the binaries, you can also just use this package 33 | directly. It exports the paths to the 34 | [`pg_ctl`](https://www.postgresql.org/docs/current/app-pg-ctl.html), 35 | [`initdb`](https://www.postgresql.org/docs/current/app-initdb.html) and 36 | [`postgres`](https://www.postgresql.org/docs/current/app-postgres.html) binaries 37 | for `darwin-x64`. 38 | 39 | ```sh 40 | npm i @embedded-postgres/darwin-x64 41 | ``` 42 | 43 | 44 | Follow the documentation to discover how to interface with the binaries. Any implementation is going to look something like this: 45 | ```ts 46 | import { pg_ctl, initdb, postgres } from '@embedded-postgres/darwin-x64' 47 | import { execSync, spawn } from 'child_process'; 48 | 49 | execSync(initdb); 50 | spawn(postgres); 51 | ``` 52 | 53 | > [!IMPORTANT] 54 | > A more friendly wrapper for using these binaries is provided as the 55 | > [embedded-postgres](https://github.com/leinelissen/embedded-postgres) package. 56 | > Please use it if you're confused by the binaries. 57 | 58 | ## Credits and Licensing 59 | Embedded Postgres was created by Lei Nelissen for [BMD 60 | Studio](https://bmd.studio). It is based on [zonky's 61 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The 62 | binaries are made available under the Apache License 2.0, whereas the specific 63 | code in this package is made available under the MIT license. 64 | 65 | 66 |
67 |
68 |
69 | 70 | -------------------------------------------------------------------------------- /packages/linux-ia32/README.md: -------------------------------------------------------------------------------- 1 |  2 | 3 |
4 |
5 | 
6 | 
7 | 
8 | 
9 | 
10 |
11 |
12 |
13 | 14 | 🐘 A Node package that spawns PostgresQL clusters programatically. 15 |
16 | 17 | This package contains the `linux-ia32` Postgres binaries for use with the `embedded-postgres` 18 | package. See 19 | [embedded-postgres](https://github.com/leinelissen/embedded-postgres) for a more 20 | developer-friendly way of spawning PostgresQL clusters. 21 | 22 | ## Installation 23 | `embedded-postgres` is available from NPM: 24 | 25 | ```sh 26 | npm i embedded-postgres 27 | ``` 28 | 29 |30 | 31 | ## Using just the binaries 32 | If you just want to use the binaries, you can also just use this package 33 | directly. It exports the paths to the 34 | [`pg_ctl`](https://www.postgresql.org/docs/current/app-pg-ctl.html), 35 | [`initdb`](https://www.postgresql.org/docs/current/app-initdb.html) and 36 | [`postgres`](https://www.postgresql.org/docs/current/app-postgres.html) binaries 37 | for `linux-ia32`. 38 | 39 | ```sh 40 | npm i @embedded-postgres/linux-ia32 41 | ``` 42 | 43 | 44 | Follow the documentation to discover how to interface with the binaries. Any implementation is going to look something like this: 45 | ```ts 46 | import { pg_ctl, initdb, postgres } from '@embedded-postgres/linux-ia32' 47 | import { execSync, spawn } from 'child_process'; 48 | 49 | execSync(initdb); 50 | spawn(postgres); 51 | ``` 52 | 53 | > [!IMPORTANT] 54 | > A more friendly wrapper for using these binaries is provided as the 55 | > [embedded-postgres](https://github.com/leinelissen/embedded-postgres) package. 56 | > Please use it if you're confused by the binaries. 57 | 58 | ## Credits and Licensing 59 | Embedded Postgres was created by Lei Nelissen for [BMD 60 | Studio](https://bmd.studio). It is based on [zonky's 61 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The 62 | binaries are made available under the Apache License 2.0, whereas the specific 63 | code in this package is made available under the MIT license. 64 | 65 | 66 |
67 |
68 |
69 | 70 | -------------------------------------------------------------------------------- /packages/linux-arm64/README.md: -------------------------------------------------------------------------------- 1 |  2 | 3 |
4 |
5 | 
6 | 
7 | 
8 | 
9 | 
10 |
11 |
12 |
13 | 14 | 🐘 A Node package that spawns PostgresQL clusters programatically. 15 |
16 | 17 | This package contains the `linux-arm64` Postgres binaries for use with the `embedded-postgres` 18 | package. See 19 | [embedded-postgres](https://github.com/leinelissen/embedded-postgres) for a more 20 | developer-friendly way of spawning PostgresQL clusters. 21 | 22 | ## Installation 23 | `embedded-postgres` is available from NPM: 24 | 25 | ```sh 26 | npm i embedded-postgres 27 | ``` 28 | 29 |30 | 31 | ## Using just the binaries 32 | If you just want to use the binaries, you can also just use this package 33 | directly. It exports the paths to the 34 | [`pg_ctl`](https://www.postgresql.org/docs/current/app-pg-ctl.html), 35 | [`initdb`](https://www.postgresql.org/docs/current/app-initdb.html) and 36 | [`postgres`](https://www.postgresql.org/docs/current/app-postgres.html) binaries 37 | for `linux-arm64`. 38 | 39 | ```sh 40 | npm i @embedded-postgres/linux-arm64 41 | ``` 42 | 43 | 44 | Follow the documentation to discover how to interface with the binaries. Any implementation is going to look something like this: 45 | ```ts 46 | import { pg_ctl, initdb, postgres } from '@embedded-postgres/linux-arm64' 47 | import { execSync, spawn } from 'child_process'; 48 | 49 | execSync(initdb); 50 | spawn(postgres); 51 | ``` 52 | 53 | > [!IMPORTANT] 54 | > A more friendly wrapper for using these binaries is provided as the 55 | > [embedded-postgres](https://github.com/leinelissen/embedded-postgres) package. 56 | > Please use it if you're confused by the binaries. 57 | 58 | ## Credits and Licensing 59 | Embedded Postgres was created by Lei Nelissen for [BMD 60 | Studio](https://bmd.studio). It is based on [zonky's 61 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The 62 | binaries are made available under the Apache License 2.0, whereas the specific 63 | code in this package is made available under the MIT license. 64 | 65 | 66 |
67 |
68 |
69 | 70 | -------------------------------------------------------------------------------- /packages/linux-ppc64/README.md: -------------------------------------------------------------------------------- 1 |  2 | 3 |
4 |
5 | 
6 | 
7 | 
8 | 
9 | 
10 |
11 |
12 |
13 | 14 | 🐘 A Node package that spawns PostgresQL clusters programatically. 15 |
16 | 17 | This package contains the `linux-ppc64` Postgres binaries for use with the `embedded-postgres` 18 | package. See 19 | [embedded-postgres](https://github.com/leinelissen/embedded-postgres) for a more 20 | developer-friendly way of spawning PostgresQL clusters. 21 | 22 | ## Installation 23 | `embedded-postgres` is available from NPM: 24 | 25 | ```sh 26 | npm i embedded-postgres 27 | ``` 28 | 29 |30 | 31 | ## Using just the binaries 32 | If you just want to use the binaries, you can also just use this package 33 | directly. It exports the paths to the 34 | [`pg_ctl`](https://www.postgresql.org/docs/current/app-pg-ctl.html), 35 | [`initdb`](https://www.postgresql.org/docs/current/app-initdb.html) and 36 | [`postgres`](https://www.postgresql.org/docs/current/app-postgres.html) binaries 37 | for `linux-ppc64`. 38 | 39 | ```sh 40 | npm i @embedded-postgres/linux-ppc64 41 | ``` 42 | 43 | 44 | Follow the documentation to discover how to interface with the binaries. Any implementation is going to look something like this: 45 | ```ts 46 | import { pg_ctl, initdb, postgres } from '@embedded-postgres/linux-ppc64' 47 | import { execSync, spawn } from 'child_process'; 48 | 49 | execSync(initdb); 50 | spawn(postgres); 51 | ``` 52 | 53 | > [!IMPORTANT] 54 | > A more friendly wrapper for using these binaries is provided as the 55 | > [embedded-postgres](https://github.com/leinelissen/embedded-postgres) package. 56 | > Please use it if you're confused by the binaries. 57 | 58 | ## Credits and Licensing 59 | Embedded Postgres was created by Lei Nelissen for [BMD 60 | Studio](https://bmd.studio). It is based on [zonky's 61 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The 62 | binaries are made available under the Apache License 2.0, whereas the specific 63 | code in this package is made available under the MIT license. 64 | 65 | 66 |
67 |
68 |
69 | 70 | -------------------------------------------------------------------------------- /packages/windows-x64/README.md: -------------------------------------------------------------------------------- 1 |  2 | 3 |
4 |
5 | 
6 | 
7 | 
8 | 
9 | 
10 |
11 |
12 |
13 | 14 | 🐘 A Node package that spawns PostgresQL clusters programatically. 15 |
16 | 17 | This package contains the `windows-x64` Postgres binaries for use with the `embedded-postgres` 18 | package. See 19 | [embedded-postgres](https://github.com/leinelissen/embedded-postgres) for a more 20 | developer-friendly way of spawning PostgresQL clusters. 21 | 22 | ## Installation 23 | `embedded-postgres` is available from NPM: 24 | 25 | ```sh 26 | npm i embedded-postgres 27 | ``` 28 | 29 |30 | 31 | ## Using just the binaries 32 | If you just want to use the binaries, you can also just use this package 33 | directly. It exports the paths to the 34 | [`pg_ctl`](https://www.postgresql.org/docs/current/app-pg-ctl.html), 35 | [`initdb`](https://www.postgresql.org/docs/current/app-initdb.html) and 36 | [`postgres`](https://www.postgresql.org/docs/current/app-postgres.html) binaries 37 | for `windows-x64`. 38 | 39 | ```sh 40 | npm i @embedded-postgres/windows-x64 41 | ``` 42 | 43 | 44 | Follow the documentation to discover how to interface with the binaries. Any implementation is going to look something like this: 45 | ```ts 46 | import { pg_ctl, initdb, postgres } from '@embedded-postgres/windows-x64' 47 | import { execSync, spawn } from 'child_process'; 48 | 49 | execSync(initdb); 50 | spawn(postgres); 51 | ``` 52 | 53 | > [!IMPORTANT] 54 | > A more friendly wrapper for using these binaries is provided as the 55 | > [embedded-postgres](https://github.com/leinelissen/embedded-postgres) package. 56 | > Please use it if you're confused by the binaries. 57 | 58 | ## Credits and Licensing 59 | Embedded Postgres was created by Lei Nelissen for [BMD 60 | Studio](https://bmd.studio). It is based on [zonky's 61 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The 62 | binaries are made available under the Apache License 2.0, whereas the specific 63 | code in this package is made available under the MIT license. 64 | 65 | 66 |
67 |
68 |
69 | 70 | -------------------------------------------------------------------------------- /packages/darwin-arm64/README.md: -------------------------------------------------------------------------------- 1 |  2 | 3 |
4 |
5 | 
6 | 
7 | 
8 | 
9 | 
10 |
11 |
12 |
13 | 14 | 🐘 A Node package that spawns PostgresQL clusters programatically. 15 |
16 | 17 | This package contains the `darwin-arm64` Postgres binaries for use with the `embedded-postgres` 18 | package. See 19 | [embedded-postgres](https://github.com/leinelissen/embedded-postgres) for a more 20 | developer-friendly way of spawning PostgresQL clusters. 21 | 22 | ## Installation 23 | `embedded-postgres` is available from NPM: 24 | 25 | ```sh 26 | npm i embedded-postgres 27 | ``` 28 | 29 |30 | 31 | ## Using just the binaries 32 | If you just want to use the binaries, you can also just use this package 33 | directly. It exports the paths to the 34 | [`pg_ctl`](https://www.postgresql.org/docs/current/app-pg-ctl.html), 35 | [`initdb`](https://www.postgresql.org/docs/current/app-initdb.html) and 36 | [`postgres`](https://www.postgresql.org/docs/current/app-postgres.html) binaries 37 | for `darwin-arm64`. 38 | 39 | ```sh 40 | npm i @embedded-postgres/darwin-arm64 41 | ``` 42 | 43 | 44 | Follow the documentation to discover how to interface with the binaries. Any implementation is going to look something like this: 45 | ```ts 46 | import { pg_ctl, initdb, postgres } from '@embedded-postgres/darwin-arm64' 47 | import { execSync, spawn } from 'child_process'; 48 | 49 | execSync(initdb); 50 | spawn(postgres); 51 | ``` 52 | 53 | > [!IMPORTANT] 54 | > A more friendly wrapper for using these binaries is provided as the 55 | > [embedded-postgres](https://github.com/leinelissen/embedded-postgres) package. 56 | > Please use it if you're confused by the binaries. 57 | 58 | ## Credits and Licensing 59 | Embedded Postgres was created by Lei Nelissen for [BMD 60 | Studio](https://bmd.studio). It is based on [zonky's 61 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The 62 | binaries are made available under the Apache License 2.0, whereas the specific 63 | code in this package is made available under the MIT license. 64 | 65 | 66 |
67 |
68 |
69 | 70 | -------------------------------------------------------------------------------- /packages/symlink-reader/src/index.ts: -------------------------------------------------------------------------------- 1 | import { Dirent } from 'fs'; 2 | import fs from 'fs/promises'; 3 | import path from 'path'; 4 | 5 | const binaryDirectory = path.join(process.cwd(), 'native'); 6 | export const symlinkFile = path.join(binaryDirectory, 'pg-symlinks.json'); 7 | 8 | // A tuple that contains an entry and its path relative to a base directory 9 | type EntryTuple = { entryPath: string; entry: Dirent }; 10 | 11 | /** 12 | * Recursively read all files in a directory, returning not only the names but 13 | * the Dirents as well. 14 | */ 15 | async function deepRead(directory: string) { 16 | // Retrieve all files in given directory 17 | const entries = await fs.readdir(directory, { withFileTypes: true }); 18 | 19 | // Loop through all files 20 | const paths = await Promise.all(entries.map(async (entry): Promise
5 |
6 | 
7 | 
8 | 
9 | 
10 | 
11 |
12 |
13 |
14 |
15 | 16 | 🐘 A Node package that spawns PostgresQL clusters programatically. 17 |
18 | 19 | ## Installation 20 | `embedded-postgres` is available from NPM: 21 | 22 | ```sh 23 | npm i embedded-postgres 24 | ``` 25 | 26 |27 | 28 | ## Usage 29 | This package contains a simple API that allows you to create clusters, start 30 | them, create / delete database and stop any existing processes. 31 | 32 | ```ts 33 | import EmbeddedPostgres from 'embedded-postgres'; 34 | 35 | async function main() { 36 | // Create the object 37 | const pg = new EmbeddedPostgres({ 38 | databaseDir: './data/db', 39 | user: 'postgres', 40 | password: 'password', 41 | port: 5432, 42 | persistent: true, 43 | }); 44 | 45 | // Create the cluster config files 46 | await pg.initialise(); 47 | 48 | // Start the server 49 | await pg.start(); 50 | 51 | // Create and/or drop database 52 | await pg.createDatabase('TEST'); 53 | await pg.dropDatabase('TEST'); 54 | 55 | // Initialize a node-postgres client 56 | const client = pg.getPgClient(); 57 | await client.connect(); 58 | const result = await client.query('SELECT datname FROM pg_database'); 59 | 60 | // Stop the server 61 | await pg.stop(); 62 | } 63 | 64 | main(); 65 | ``` 66 | 67 |
68 | 69 | ## PostgresQL Versions 70 | This package aims to track the [PostgresQL support 71 | policy](https://www.postgresql.org/support/versioning/) for supported versions. 72 | Additionally, we track the binaries that are created upstream in [zonky's 73 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). This 74 | leads to the following current support matrix: 75 | 76 | | Platform / Architecture | 12.20.0 | 13.16.0 | 14.13.0 | 15.8.0 | 16.4.0 | 17.0.0 | 77 | |---------------------------|---------|---------|---------|--------|--------|--------| 78 | | 🍎 Darwin / x64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 79 | | 🍎 Darwin / arm64[[1]](https://github.com/zonkyio/embedded-postgres/issues/86#issuecomment-1120425822) | 🚫 | 🚫 | 🚫 | ✅ | ✅ | ✅ | 80 | | 🪟 Windows / x64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 81 | | 🐧 Linux / x64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 82 | | 🐧 Linux / arm | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 83 | | 🐧 Linux / arm64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 84 | | 🐧 Linux / ia32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 85 | | 🐧 Linux / ppc64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 86 | 87 | In order to install a particular version, look for the latest tag in 88 | [NPM](https://www.npmjs.com/package/embedded-postgres). For example, if you 89 | would like to install `v10.20.0`, you can currently use the following tag: 90 | ```sh 91 | npm i embedded-postgres@10.20.0-beta.6 92 | ``` 93 | 94 | Installing particular versions of PostgresQL (i.e. versions not released on NPM) 95 | is currently not possible. If you would have a need for doing so, please create 96 | an issue. 97 | 98 |
99 | 100 | ## API 101 | Options in the constructor can be used to modify the behaviour of the 102 | application. The parameters that are available as part of the options can be 103 | seen here: 104 | 105 | | Property | Type | Description | 106 | |---|---|---| 107 | | databaseDir | string | The location where the data should be persisted to. Defaults to `./data/db` | 108 | | port | number | The port where the Postgres database should be listening. Defaults to: `5432` | 109 | | user | string | The username for logging into the Postgres database. Defaults to `postgres` | 110 | | password | string | The password for logging into the Postgres database. Defaults to `password` | 111 | | authMethod | 'scram-sha-256' \| 'password' \| 'md5' | The authentication method to use when authenticating against Postgres. Defaults to `password` | 112 | | persistent | boolean | Whether all data should be left in place when the database is shut down. Defaults to `true`. | 113 | | 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 `[]` 114 | | 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 `[]`. | 115 | | 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 `false`. | 116 | | 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.log` | 117 | | 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 `console.error` | 118 | 119 |
120 | 121 | ## Contributing 122 | This package is open to issues, feedback, ideas and pull requests. Create an 123 | issue on this repository to get started! In order to get started with 124 | development, you might need some extra pointers 125 | 126 | ### Development 127 | In order to get yourself situated for development, you will need to the 128 | repository up and running. In order to make this work, start with a relatively 129 | recent install of NodeJS (at least v18, v20+ recommended). You can then run this 130 | command to install all packages: 131 | ``` 132 | npm install --force 133 | ``` 134 | 135 | > [!NOTE] 136 | > You must include `--force` or else NPM will refuse to install the 137 | > dependencies for all packages, including those not for the current architecture. 138 | 139 | Then, you must pre-compile all Typescript using the following command: 140 | ``` 141 | npm run build 142 | ``` 143 | 144 | As soon as that is complete, we'll download the requisite PostgresQL binaries 145 | for your particular architecture using: 146 | ``` 147 | npm run download 148 | ``` 149 | 150 | Lastly, you can hop over to `packages/embedded-postgres` and do some development 151 | there: 152 | ``` 153 | cd packages/embedded-postgres 154 | ``` 155 | 156 | You can force automatic recompliation of the Typescript files by running: 157 | ``` 158 | npm start 159 | ``` 160 | 161 | Don't forget to add and run tests when you are developing new functionality. Add 162 | them to `tests/index.test.ts`, and run the tests by running: 163 | ``` 164 | npm test 165 | ``` 166 | 167 |
168 | 169 | ## Troubleshotting 170 | 171 | ### Running in Docker containers 172 | Running in Docker containers might fail, because many are setup to run with the 173 | root user as default. Either you resolve to setting up a container with a 174 | specific user yourself, or you set the `createPostgresUser` option to true, 175 | after which embedded-postgres will automatically set up a postgres user on the 176 | system for usage by your script. 177 | 178 |
179 | 180 | ## Credits and Licensing 181 | Embedded Postgres was created by Lei Nelissen for [BMD 182 | Studio](https://bmd.studio). It is based on [zonky's 183 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). The 184 | binaries are made available under the Apache License 2.0, whereas the specific 185 | code in this package is made available under the MIT license. 186 | 187 | 188 |
189 |
190 |
191 | 192 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |  2 | 3 |
4 |
5 | 
6 | 
7 | 
8 | 
9 | 
10 |
11 |
12 |
13 |
14 | 15 | 🐘 A Node package that spawns PostgresQL clusters programatically. 16 |
17 | 18 | ## Installation 19 | `embedded-postgres` is available from NPM: 20 | 21 | ```sh 22 | npm i embedded-postgres 23 | ``` 24 | 25 |26 | 27 | ## Usage 28 | This package contains a simple API that allows you to create clusters, start 29 | them, create / delete database and stop any existing processes. 30 | 31 | ```ts 32 | import EmbeddedPostgres from 'embedded-postgres'; 33 | 34 | async function main() { 35 | // Create the object 36 | const pg = new EmbeddedPostgres({ 37 | databaseDir: './data/db', 38 | user: 'postgres', 39 | password: 'password', 40 | port: 5432, 41 | persistent: true, 42 | }); 43 | 44 | // Create the cluster config files 45 | await pg.initialise(); 46 | 47 | // Start the server 48 | await pg.start(); 49 | 50 | // Create and/or drop database 51 | await pg.createDatabase('TEST'); 52 | await pg.dropDatabase('TEST'); 53 | 54 | // Initialize a node-postgres client 55 | const client = pg.getPgClient(); 56 | await client.connect(); 57 | const result = await client.query('SELECT datname FROM pg_database'); 58 | 59 | // Stop the server 60 | await pg.stop(); 61 | } 62 | 63 | main(); 64 | ``` 65 | 66 |
67 | 68 | ## PostgresQL Versions 69 | This package aims to track the [PostgresQL support 70 | policy](https://www.postgresql.org/support/versioning/) for supported versions. 71 | Additionally, we track the binaries that are created upstream in [zonky's 72 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). This 73 | leads to the following current support matrix: 74 | 75 | | Platform / Architecture | 13.23.0 | 14.20.0 | 15.15.0 | 16.11.0 | 17.7.0 | 18.1.0 | 76 | |---------------------------|---------|---------|---------|---------|--------|--------| 77 | | 🍎 Darwin / x64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 78 | | 🍎 Darwin / arm64[[1]](https://github.com/zonkyio/embedded-postgres/issues/86#issuecomment-1120425822) | 🚫 | ✅ | ✅ | ✅ | ✅ | ✅ | 79 | | 🪟 Windows / x64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 80 | | 🐧 Linux / x64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 81 | | 🐧 Linux / arm | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 82 | | 🐧 Linux / arm64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 83 | | 🐧 Linux / ia32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 84 | | 🐧 Linux / ppc64 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 85 | 86 | In order to install a particular version, look for the latest tag in 87 | [NPM](https://www.npmjs.com/package/embedded-postgres). For example, if you 88 | would like to install `v10.20.0`, you can currently use the following tag: 89 | ```sh 90 | npm i embedded-postgres@10.20.0-beta.6 91 | ``` 92 | 93 | Installing particular versions of PostgresQL (i.e. versions not released on NPM) 94 | is currently not possible. If you would have a need for doing so, please create 95 | an issue. 96 | 97 |
98 | 99 | ## API 100 | Options in the constructor can be used to modify the behaviour of the 101 | application. The parameters that are available as part of the options can be 102 | seen here: 103 | 104 | | Property | Type | Description | 105 | |---|---|---| 106 | | databaseDir | string | The location where the data should be persisted to. Defaults to `./data/db` | 107 | | port | number | The port where the Postgres database should be listening. Defaults to: `5432` | 108 | | user | string | The username for logging into the Postgres database. Defaults to `postgres` | 109 | | password | string | The password for logging into the Postgres database. Defaults to `password` | 110 | | authMethod | 'scram-sha-256' \| 'password' \| 'md5' | The authentication method to use when authenticating against Postgres. Defaults to `password` | 111 | | persistent | boolean | Whether all data should be left in place when the database is shut down. Defaults to `true`. | 112 | | 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 `[]` 113 | | 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 `[]`. | 114 | | 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 `false`. | 115 | | 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.log` | 116 | | 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 `console.error` | 117 | 118 |
119 | 120 | ## Contributing 121 | This package is open to issues, feedback, ideas and pull requests. Create an 122 | issue on this repository to get started! In order to get started with 123 | development, you might need some extra pointers 124 | 125 | ### Development 126 | In order to get yourself situated for development, you will need to the 127 | repository up and running. In order to make this work, start with a relatively 128 | recent install of NodeJS (at least v18, v20+ recommended). You can then run this 129 | command to install all packages: 130 | ``` 131 | npm install --force 132 | ``` 133 | 134 | > [!NOTE] 135 | > You must include `--force` or else NPM will refuse to install the 136 | > dependencies for all packages, including those not for the current architecture. 137 | 138 | Then, you must pre-compile all Typescript using the following command: 139 | ``` 140 | npm run build 141 | ``` 142 | 143 | As soon as that is complete, we'll download the requisite PostgresQL binaries 144 | for your particular architecture using: 145 | ``` 146 | npm run download 147 | ``` 148 | 149 | Lastly, you can hop over to `packages/embedded-postgres` and do some development 150 | there: 151 | ``` 152 | cd packages/embedded-postgres 153 | ``` 154 | 155 | You can force automatic recompliation of the Typescript files by running: 156 | ``` 157 | npm start 158 | ``` 159 | 160 | Don't forget to add and run tests when you are developing new functionality. Add 161 | them to `tests/index.test.ts`, and run the tests by running: 162 | ``` 163 | npm test 164 | ``` 165 | 166 |
167 | 168 | ## Troubleshotting 169 | 170 | ### Running in Docker containers 171 | Running in Docker containers might fail, because many are setup to run with the 172 | root user as default. Either you resolve to setting up a container with a 173 | specific user yourself, or you set the `createPostgresUser` option to true, 174 | after which embedded-postgres will automatically set up a postgres user on the 175 | system for usage by your script. 176 | 177 |
178 | 179 | ## Credits and Licensing 180 | Embedded Postgres was created by Lei Nelissen for [BMD 181 | Studio](https://bmd.studio). It is currently maintained by [Studio Falkland](https://falkland.studio) The package is based on [zonky's 182 | embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres). 183 | 184 | The 185 | binaries are made available under the Apache License 2.0, whereas the specific 186 | code in this package is made available under the MIT license. 187 | 188 |
189 |
190 | 
191 |
192 |
193 | 
194 |
195 |
198 | -------------------------------------------------------------------------------- /packages/embedded-postgres/src/index.ts: -------------------------------------------------------------------------------- 1 | import path from 'path'; 2 | import crypto from 'crypto'; 3 | import fs from 'fs/promises'; 4 | import { platform, tmpdir, userInfo } from 'os'; 5 | import { ChildProcess, spawn, exec } from 'child_process'; 6 | 7 | import pg from 'pg'; 8 | import AsyncExitHook from 'async-exit-hook'; 9 | 10 | import getBinaries from './binary.js'; 11 | import { PostgresOptions } from './types.js'; 12 | 13 | const bin = getBinaries(); 14 | const { Client } = pg; 15 | 16 | /** 17 | * We have to specify the LC_MESSAGES locale because we rely on inspecting the 18 | * output of the `initdb` command to see if Postgres is ready. As we're looking 19 | * for a particular string, we need to force that string into the right locale. 20 | * @see https://github.com/leinelissen/embedded-postgres/issues/15 21 | */ 22 | const LC_MESSAGES_LOCALE = 'en_US.UTF-8'; 23 | 24 | /** 25 | * Previosuly, options were specified in snake_case rather than camelCase. Old 26 | * options are still translated to new variants. 27 | */ 28 | interface LegacyOptions { 29 | database_dir: string; 30 | auth_method: 'scram-sha-256' | 'password' | 'md5'; 31 | } 32 | 33 | // The default configuration options for the class 34 | const defaults: PostgresOptions = { 35 | databaseDir: path.join(process.cwd(), 'data', 'db'), 36 | port: 5432, 37 | user: 'postgres', 38 | password: 'password', 39 | authMethod: 'password', 40 | persistent: true, 41 | initdbFlags: [], 42 | postgresFlags: [], 43 | createPostgresUser: false, 44 | onLog: console.log, 45 | onError: console.error, 46 | }; 47 | 48 | /** 49 | * This will track instances of all current initialised clusters. We need this 50 | * because we want to be able to shutdown any clusters when the script is exited. 51 | */ 52 | const instances = new Set