Postgres

The Postgres entity runs a PostgreSQL database in a Docker container with automatic image pulling, readiness checking, and SQL initialization.

Import

import { Postgres } from "sigil";

Constructor

new Postgres(name: string, config?: Partial<Omit<PostgresConfig, "name">>)

Config

interface PostgresConfig {
  name: string        // Set via constructor, not config object
  port?: number       // Host port (default: 5432)
  database?: string   // Database name (default: "postgres")
  username?: string   // (default: "postgres")
  password?: string   // (default: "postgres")
  version?: string    // Postgres Docker image tag (default: "16")
  initSql?: string    // Absolute path to SQL file for schema setup
  seedSql?: string    // Absolute path to SQL file for test data
}

Properties

connectionString

db.connectionString: string

Returns a standard PostgreSQL connection string:

postgresql://postgres:postgres@localhost:5432/myapp

Available immediately after construction (computed from config values, does not require the database to be running).

pgInterface

db.pgInterface: PostgresInterface

The TCP interface instance. Exposes the same connection string via getConnectionString().

status

Inherited from Entity. One of: "pending", "starting", "running", "stopping", "stopped", "error".

Lifecycle

start()

1. Pulls postgres:<version> image if not already present
2. Creates a Docker container named sigil-<name>
3. Maps the specified host port to container port 5432
4. Sets POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD environment variables
5. Waits for the database to accept connections (using psql -c 'SELECT 1' inside the container)
6. Runs initSql file if provided
7. Runs seedSql file if provided

stop()

Stops and removes the Docker container.

Examples

Minimal

const db = env.add(new Postgres("db"));
// Postgres 16 on port 5432, database "postgres"

Full configuration

const db = env.add(
  new Postgres("shopping-db", {
    port: 5433,
    database: "shopping_list",
    username: "admin",
    password: "secret",
    version: "15",
    initSql: path.join(root, "db/schema.sql"),
    seedSql: path.join(root, "db/seed.sql"),
  })
);

Wiring to a service

const db = env.add(new Postgres("db", { database: "myapp" }));

env.add(
  new Service("api", {
    command: ["node", "server.js"],
    env: { DATABASE_URL: db.connectionString },
  })
);