pg-here tool launches local PostgreSQL with one command

New tool launches PostgreSQL with one command

The new open-source tool pg-here lets developers launch a local PostgreSQL database in their project folder with a single terminal command. Created by developer Marc Rousavy, it automatically handles version management, data persistence, and connection strings.

The tool is designed to simplify local development setups, which often require manual installation and configuration of database servers. It runs as a Node.js package and can be used via command line, npm scripts, or directly in Node.js code.

How the pg-here command works

Running the basic command bunx pg-here in a project directory performs several automated steps. It checks for an existing data folder and either reuses it or creates a new one named pg_local/.

The tool downloads the necessary PostgreSQL binaries if they aren't already cached locally. It then starts the database server on a default port and outputs a ready-to-use connection URL.

• Default username: postgres
• Default password: postgres
• Default port: 55432
• Default database: postgres

The process runs in the foreground until stopped with Ctrl+C, which also shuts down the PostgreSQL instance.

Customizing your database setup

Developers can override all default settings using command-line flags. This allows for custom usernames, passwords, database names, ports, and specific PostgreSQL versions.

For example, the command bunx pg-here --username me --password secret --database my_app --port 55433 --pg-version 17.0.0 creates a customized instance. The tool manages multiple versioned binaries side-by-side, preventing conflicts between projects that require different PostgreSQL releases.

You can also integrate it into a project's npm scripts. Adding a script like "db:up": "pg-here" to package.json lets team members start the database simply by running npm run db:up or bun run db:up.

Using pg-here programmatically in Node.js

For more control in testing or application code, pg-here can be imported as a module. The startPgHere function returns a promise that resolves to an object containing the connection string and a stop method.

This is useful for integration tests that need a fresh, isolated database. The function accepts options like projectDir, database, and createDatabaseIfMissing.

Fixing common Linux runtime errors

On some Linux distributions, PostgreSQL startup may fail due to missing shared libraries. A common error involves libxml2, which is a dependency for certain PostgreSQL features.

The pg-here documentation provides quick-fix commands for major package managers to install the required runtime packages:

• Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y libxml2 libxml2-utils
• Fedora/RHEL: sudo dnf install -y libxml2
• Alpine: sudo apk add libxml2

The tool also includes a compatibility fallback that retries startup with a project-local library workaround. If your environment defaults to an older version, you can force a specific release with the --pg-version flag.