Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

portable-postgres

Build Status License

  1. What is it?
  2. Platforms
  3. What is included
  4. Limitations
  5. Usage
  6. Alternatives
  7. Contributing
  8. License

What is it?

PostgreSQL 18 in a native archive for local development and integration tests. Extract the archive and run PostgreSQL directly on your machine.

Status: pre-release. No archives are published yet. GitHub Actions will build the .tar.gz archives for download from GitHub Releases. The Node.js wrapper will follow on npm.

Platforms

Platform Status Host requirement
Linux x64 (glibc) Built glibc 2.35 or newer; tested on Ubuntu 22.04.
Windows x64 Built Microsoft Visual C++ runtime (vcruntime140.dll) and the Universal CRT.
macOS arm64 Planned Not built yet.

Linux distributions based on musl, such as Alpine, are not supported.

What is included

The archives contain PostgreSQL 18 and the extensions below. The exact source releases and their checksums are listed in binaries/sources/sources.json.

Extension What it does
pgvector Stores vectors and finds similar ones.
TimescaleDB (Apache-only) Adds hypertables for storing and querying time-series data.
pg_textsearch Adds full-text search that ranks matches by relevance using BM25.
HypoPG Shows how a proposed index would affect a query plan before you create it.
plpgsql_check Finds errors in PL/pgSQL functions and procedures before you run them.
pg_cron Schedules SQL jobs to run inside PostgreSQL.
pg_partman (SQL only) Creates and maintains table partitions based on time or integer values.
pgTAP (SQL only) Adds SQL assertions for testing database schemas and behavior.

Limitations

The archives are built for development and tests, with as few external dependencies as possible. Do not use them for production databases.

  • No TLS: PostgreSQL is built without OpenSSL, so connections are unencrypted.
  • No ICU collations.
  • No zlib, LZ4, or Zstandard compression, including for pg_dump and pg_basebackup.
  • psql has no line editing or command history, because readline is excluded.
  • TimescaleDB is the Apache-only build. Features under the Timescale License, such as compression and continuous aggregates, are not included.
  • pg_partman has no background worker. Call partman.run_maintenance_proc() yourself, for example from a pg_cron job.
  • pg_textsearch ranks with statistics over all indexed rows, including rows that row-level security hides. A user who knows a term can learn how often it occurs in rows they cannot read. A superuser can set pg_textsearch.allow_rls = off to refuse creating or rebuilding BM25 indexes on tables with row-level security, and enabling row-level security on tables that have them. The setting is checked only when these commands run, so indexes created while it was on keep working. On a partitioned table, each partition keeps its own statistics, so scores from different partitions are not comparable.
  • pgTAP comes without the pg_prove command-line runner. Run the test SQL with psql and read the TAP output.

Usage

Choose an archive for your platform and verify its SHA-256 against a trusted digest before extracting it. The commands below run from the extracted directory. Keep the database and its log outside that directory, so that it holds only the archive's files and can be replaced. On Linux, initdb creates the data directory, and any missing parent, readable only by you. On Windows, the directory below lies in your own profile. --pwprompt asks for the password of the postgres user, so the password is never written to a file or the shell history.

Create a data directory:

pgwork="$HOME/portable-postgres"
bin/initdb -D "$pgwork/data" -U postgres --pwprompt --auth=scram-sha-256 --encoding=UTF8 --no-locale

On Windows, in cmd.exe:

set "pgwork=%LOCALAPPDATA%\portable-postgres"
bin\initdb.exe -D "%pgwork%\data" -U postgres --pwprompt --auth=scram-sha-256 --encoding=UTF8 --no-locale

TimescaleDB, pg_textsearch, and pg_cron must be loaded when the server starts. If you use any of them, add this line to postgresql.conf in the data directory first, listing only the ones you need:

shared_preload_libraries = 'timescaledb,pg_textsearch,pg_cron'

pg_cron keeps its jobs in one database and by default runs each job over a new client connection, which the password authentication above refuses without a stored password. If you use pg_cron, add these lines as well, so that jobs run in background workers instead:

cron.database_name = 'postgres'
cron.use_background_workers = on
max_worker_processes = 16

max_worker_processes limits all background workers, including those of pg_cron and TimescaleDB. The archives' native tests run with these settings.

Start the server, connect, and stop the server again:

bin/pg_ctl -D "$pgwork/data" -l "$pgwork/server.log" -o "-p 5432" -w start
bin/psql -h 127.0.0.1 -p 5432 -U postgres -d postgres
bin/pg_ctl -D "$pgwork/data" -m fast -w stop

On Windows:

bin\pg_ctl.exe -D "%pgwork%\data" -l "%pgwork%\server.log" -o "-p 5432" -w start
bin\psql.exe -h 127.0.0.1 -p 5432 -U postgres -d postgres
bin\pg_ctl.exe -D "%pgwork%\data" -m fast -w stop

Enable the extensions you need with CREATE EXTENSION in each database:

CREATE EXTENSION vector;

Install pg_partman in the partman schema to use partman.run_maintenance_proc().

CREATE SCHEMA partman;
CREATE EXTENSION pg_partman SCHEMA partman;

pg_cron can only be created in the database that cron.database_name names. To run a job in another database, schedule it with cron.schedule_in_database(), which takes that database's name.

For archive layout and platform requirements, see the native artifact format.

Alternatives

portable-postgres is a native PostgreSQL server with a fixed set of extensions that runs without a container runtime or an installation. The table compares it with other ways to run PostgreSQL locally, as of November 2026.

portable-postgres Docker image PGlite Zonky Embedded Postgres Binaries EDB installers
Runs as Native server Server in a container WebAssembly in a JavaScript runtime Native server Installed native server
Works without a container runtime ✅ ❌ ✅ ✅ ✅
Multiple connections ✅ ✅ ❌ ✅ ✅
pgvector, pg_textsearch, pgTAP ✅ Included ❌ Not included ✅ Separate npm packages ❌ Not included ❌ Not included
TimescaleDB, pg_cron, HypoPG, plpgsql_check, pg_partman ✅ Included ❌ Not included ❌ Not available ❌ Not included ❌ Not included
TLS ❌ ✅ Not applicable ✅ ✅
ICU collations ❌ ✅ ✅ ✅ ✅
Linux x64 (glibc) ✅ ✅ ✅ ✅ ❌
Linux x64 (musl) ❌ ✅ ✅ ✅ ❌
Windows x64 ✅ In a Linux VM ✅ ✅ ✅
macOS arm64 Planned In a Linux VM ✅ ✅ ✅
Intended for Development and tests Any use, including production Embedding in applications, tests Tests Any use, including production

The Docker image and the EDB installers also support compression, which portable-postgres lacks; see Limitations. You can add extensions to the Docker image by building your own image on top of it. The Embedded Postgres Binaries contain only initdb, pg_ctl, and postgres. Wrappers such as the embedded-postgres npm package download and start them for you.

Contributing

See CONTRIBUTING.md for build and test instructions.

License

All files are released under the Apache License 2.0.

Individual files contain the following tag instead of the full license text:

SPDX-License-Identifier: Apache-2.0

This enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/.

PostgreSQL, extensions, and their dependencies retain their own licenses and notices. The archives include those notices in their notices/ directory.

Microsoft code in the Windows archives

The released Windows archives are built with Microsoft Visual Studio 2026. As in every program built with it, the linker adds a small amount of Microsoft runtime code to each Windows program and library. If you redistribute a released Windows archive, the conditions in its notices/msvc-runtime.txt apply to that code. An archive that you build yourself with another Visual Studio version contains another notices/msvc-runtime.txt, which applies instead.

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages