s-postgres

library1.3.0jsnpmunverified

A lightweight utility for spinning up a pre-configured PostgreSQL instance in Docker, ideal for local development and CI. Version 1.3.0 requires Node >=20.17.0. Automatically configures user, password, and database with minimal setup. Differentiates from manual Docker commands by handling container lifecycle and network cleanup.

database devops

npm install s-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · S-POSTGRES

s-postgres

databasejavascriptv1.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import postgres from 's-postgres'

✗ const postgres = require('s-postgres')

Package is ESM-only; CJS require will fail.

PostgresConfig

✓ import { PostgresConfig } from 's-postgres'

✗ const { PostgresConfig } = require('s-postgres')

Type exported only if using TypeScript.

startPostgres

✓ import { startPostgres } from 's-postgres'

✗ import startPostgres from 's-postgres/startPostgres'

Named export, not a subpath export.

Shows how to start a Postgres Docker container with custom credentials, get connection URI, and stop the container.

import postgres from 's-postgres'; async function main() { const config = { user: 'myuser', password: 'mypassword', database: 'mydb', port: 5432 }; const { container, connectionUri } = await postgres.start(config); console.log(`Postgres running at ${connectionUri}`); // ... use connectionUri with pg client await postgres.stop(container); } main().catch(console.error);

Debug

Known issues

breakingNode.js version must be >=20.17.0. Older versions cause runtime errors due to ESM and import() usage.

fix

Upgrade Node.js to >=20.17.0.

affects: <20.17.0

gotchaDocker must be running and the current user must have permission to access the Docker socket.

fix

Ensure Docker daemon is running and user is in the docker group (or use sudo).

affects: all

gotchaPorts are bound to localhost by default; external access requires explicit configuration.

fix

Set host in config to '0.0.0.0' to bind to all interfaces.

affects: all

deprecatedThe config option 'imageTag' defaults to 'latest'; consider pinning for production.

fix

Explicitly set imageTag to a specific version like '16-alpine'.

affects: <1.3.0

Errors

Common errors & fixes

Error: connect ENOENT /var/run/docker.sock

Docker socket not accessible or Docker not running.

fix

Start Docker and ensure /var/run/docker.sock exists and is writable.

TypeError: Cannot find module 's-postgres'

Package not installed or ESM import used in CJS environment.

fix

Install package: npm install s-postgres. If using CommonJS, switch to dynamic import: const postgres = await import('s-postgres').

Error: container already exists with name s-postgres

Previous container not stopped/removed.

fix

Run postgres.stop(container) after use or remove existing container manually: docker rm -f s-postgres

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

dockeroderequiredDocker API client for Node to manage containers

Agent activity

11 hits · last 30 days

node