pglaunch

PGLaunch

Generate multiple PostgreSQL connection strings/databases using CLI for development environments!

📦 Zero Config / Lightweight / Easy-to-Use CLI for spinning up disposable PostgreSQL containers

Instantly launch a disposable lightweight PostgreSQL container with a unique database and connection URL - no Docker expertise required.

📖 Some Examples

See Usage to learn more.

# Launch a Postgres container using the current directory name
npx pglaunch
# Specify a custom name (defaults to current directory name)
npx pglaunch -n my-project
# Specify a custom port (defaults to a random available port)
npx pglaunch -p 5433
# Keep the container (container are removed on exit/system-restart by default)
npx pglaunch -k
# Confirm launching a second container with the same base name
npx pglaunch -n my-project -c
# View help message
npx pglaunch -h
# View version
npx pglaunch -v

✨ Features

• 🐳 One-command PostgreSQL: Spins up an isolated postgres:alpine Docker container with sensible defaults.
• 🔗 Auto-generated connection URL: Prints a POSTGRES connection URL so you can plug directly into your app or environments.
• 🎲 Random port allocation: If you don’t specify -p, PGLaunch finds an available port for you.
• 🛡️ Name collisions handled: Detects existing containers with the same base name—warns you unless you use -c to confirm.
• ♻️ Cleanup by default: Containers are removed on exit/system-restart unless you pass -k (keep) to persist them.
• 🔍 Docker sanity checks: Verifies Docker is installed and running, with actionable error messages if something’s amiss.
• 🔐 Minimal configuration: All you need is Docker; no extra files or environment variables required.

🚀 Usage

npx pglaunch [options]

• [options] are optional, if not specified, PGLaunch will use sensible defaults based on the current directory name and a random available port.

-n, --name <name>  Name for PostgresSQL database
                  (default: current directory name)
-p, --port <port>  Port for PostgresSQL database
                  (default: random available port)
-k, --keep         Keep the container after exit
                  (default: false)
-c, --confirm      Confirm starting another container with the same name
-v, --version      Display version
-h, --help         Display help

🐋 Docker Requirements

• Docker CLI: PGLaunch runs docker --version to ensure Docker is installed.
• Docker Daemon: PGLaunch runs docker info under the hood—if the daemon isn’t running, you’ll see a prompt to start it.

If Docker is missing or not running, PGLaunch will print an error like:

- Docker is not installed. Please install Docker and try again.
  Download it here: https://docs.docker.com/desktop

- Docker is installed but not running.
  Please start the Docker application/daemon and try again.

📦 Install Globally (Optional)

npm install -g pglaunch
pglaunch [options]

🔗 More Tools

Check out more projects at github.com/nrjdalal

📄 License

MIT – LICENSE