GitHub - mayfer/pg-here: Per-project Postgres instances with instant snapshot & restore to support yolo development methods

https://github.com/mayfer/pg-here • Feb 19, 2026 22:15

Extracto

Per-project Postgres instances with instant snapshot & restore to support yolo development methods - mayfer/pg-here

Resumen

Resumen Principal

pg-here se posiciona como una herramienta esencial para desarrolladores, ofreciendo una solución ágil y eficiente para la gestión de instancias locales de PostgreSQL directamente dentro de la carpeta de un proyecto. Su principal fortaleza radica en la simplicidad, permitiendo el lanzamiento de un servidor de base de datos completamente funcional en aproximadamente 30 segundos con una única instrucción de comando. Esta facilidad de uso erradica la complejidad inherente a la configuración manual de bases de datos, promoviendo un ciclo de desarrollo más rápido y fluido. La herramienta demuestra inteligencia al reutilizar directorios de datos existentes (pg_local/data/) y adaptarse a diferentes versiones almacenadas en caché, lo que optimiza el rendimiento y la consistencia del entorno. Su diseño facilita un proceso continuo de desarrollo, manteniendo la instancia activa hasta una detención explícita, y provee una cadena de conexión psql lista para ser utilizada. Además, pg-here es altamente personalizable, permitiendo a los usuarios modificar parámetros clave como el nombre de usuario, contraseña, base de datos, puerto y versión de PostgreSQL tanto a través de la línea de comandos como mediante una interfaz programática, lo que la hace sumamente flexible para adaptarse a los requisitos específicos de cualquier proyecto.

Elementos Clave

Inicio Rápido y Entorno Localizado: pg-here permite iniciar una instancia de PostgreSQL en la carpeta del proyecto en solo 30 segundos, lanzando por defecto la versión 18.0.0 y proporcionando una cadena de conexión psql preconfigurada (postgresql://postgres:postgres@localhost:55432/postgres). Este enfoque garantiza un entorno de base de datos self-contained

Contenido

pg-here

Run a local PostgreSQL instance in your project folder with one command.

30-second start

Default output:

Launching PostgreSQL 18.0.0 into new pg_local/
psql postgresql://postgres:postgres@localhost:55432/postgres

If a data folder already exists:

Reusing existing pg_local/data/ with PostgreSQL 18.0.0
psql postgresql://postgres:postgres@localhost:55432/postgres

If the cached folder version differs:

Reusing existing pg_local/data/ (pg_local/bin has 18.0.0, running PostgreSQL is 18.0)
psql postgresql://postgres:postgres@localhost:55432/postgres

The process stays alive until you stop it.
Ctrl+C → exits and stops Postgres.

Defaults (all args optional)

bunx pg-here

username = postgres
password = postgres
database = postgres
port = 55432
pg-version = auto

Custom run

bunx pg-here --username me --password secret --database my_app --port 55433 --pg-version 17.0.0

You can also run locally in this repo:

Same CLI flags are supported.

Programmatic

import { startPgHere } from "pg-here";

const pg = await startPgHere({
  projectDir: process.cwd(),
  database: "my_app",
  createDatabaseIfMissing: true,
});

console.log(pg.databaseConnectionString); // psql-ready URL
await pg.stop();

Linux runtime error (quick fix)

If startup fails with missing libxml2 libraries, install runtime packages and retry:

sudo apt-get update && sudo apt-get install -y libxml2 libxml2-utils
sudo dnf install -y libxml2
sudo apk add libxml2

This release already retries startup with a project-local libxml2 compatibility fallback when needed.

Version pin / stale cache

If your environment keeps resolving an older release, force a specific version: