Skip to content
SHC Docs

A Postgres socket

Postgres offers a socket named postgres. An app with a plug of that name can ask it for a database and user. This app is pgweb, a web client for Postgres.

Remove the second database from the last page to make room. Keep db. uninstall backs a deployment up before it removes it, and this node has no backup repository yet, so that backup would refuse: --no-backup removes db2 without one.

home01
$ shc uninstall db2 --no-backup -y
uninstalling deployment "db2"
[db2] Complete 3/3
✔ remove from home01
✔ leave every node's service VIP table
✔ tear down
✔ uninstalled deployment "db2"

Create these four files on home01.

~/learn/pgweb/app.yaml
name: pgweb
version: "0.16.2"
title: pgweb
description: A web client for Postgres through a plug
category: development
license:
id: MIT
vars:
postgres:
database@identifier!: database the plug asks for
username@identifier!: user the plug asks for
password@secret!: that user's password
~/learn/pgweb/vars.yaml
postgres:
database: pgweb
username: pgweb
password: P@ssw0rd
~/learn/pgweb/postgres.plug.yaml
required: true
services:
- pgweb
data:
database: "{{ vars.postgres.database }}"
username: "{{ vars.postgres.username }}"
password: "{{ vars.postgres.password }}"
~/learn/pgweb/compose.yaml
services:
pgweb:
image: sosedoff/pgweb:0.16.2
environment:
PGWEB_DATABASE_URL: "postgres://{{ integrations.postgres.plug.data.username }}:{{ integrations.postgres.plug.data.password | urlencode }}@{{ integrations.postgres.socket.hostname }}:{{ integrations.postgres.socket.port }}/{{ integrations.postgres.plug.data.database }}?sslmode=disable"
command: ["pgweb", "--bind=0.0.0.0", "--listen=8081"]
expose:
- "8081"
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8081/api/info"]
interval: 10s
retries: 6
deploy:
resources:
limits:
cpus: "0.25"
memory: 128M

app.yaml declares three variables under postgres; @identifier takes a name Postgres accepts unquoted (App definition). vars.yaml gives them values (Variables). postgres.plug.yaml is a plug named postgres: required refuses an install that does not connect it, services names the only services that reach the socket’s deployment, and data is what it sends the socket (Plugs and sockets). compose.yaml reads the plug’s data and the socket’s answer from integrations.postgres (Compose keys).

home01
$ shc install ~/learn/pgweb -s pgweb -i postgres=db --expose 8081=pgweb:8081
installing deployment "pgweb"
[pgweb] Healthy 1/1
✔ pgweb healthy
✔ installed deployment "pgweb"
exposure: lan
$ shc integration ls
CONSUMER STACK NAME CONSUMER PLUG PROVIDER STACK NAME PROVIDER SOCKET STATUS ID
pgweb postgres db postgres connected 0
$ shc exec -s db -S postgres-1 -- psql -U postgres -d postgres -tAc "select datname, pg_get_userbyid(datdba) from pg_database where datname = 'pgweb'"
pgweb|pgweb

-i postgres=db connects this app’s postgres plug to deployment db. The socket creates database pgweb and its owner pgweb before the app starts.

The socket is the catalogue’s postgres.socket.yaml. Up to its jobs it reads:

home01
$ sed '/^jobs:/q' /usr/lib/shc/apps/postgres/postgres.socket.yaml
schema:
plug:
database@identifier!: Database name to create
username@identifier: Dedicated username (if omitted, uses admin credentials)
password@secret: Password for dedicated user (required if username provided)
extensions@json: Optional list of PostgreSQL extensions to install (e.g., ["cube", "earthdistance"])
cleanup@boolean: Drop the database and role this server made for the consumer when the consumer is uninstalled
socket:
hostname@string!: PostgreSQL hostname
readHostname@string!: PostgreSQL read replica hostname
port@port!: PostgreSQL port
database@string!: Database name
username@string!: Username
password@secret!: Password
adopt@string: Databases a consumer that moves its plug here from another provider may bind as they stand, space separated
placement:
colocate: location
data:
hostname: "{{ environment }}.postgres.{{ stack }}"
readHostname: "postgres-ro.{{ stack }}.{{ environment }}.{{ tenant }}.shc.internal"
port: 5432
database: "{{ vars.postgres.database }}"
username: "{{ vars.postgres.username }}"
password: "{{ vars.postgres.password }}"
adopt: "{{ vars.postgres.adopt | default('') }}"
jobs:

schema.plug is what a plug may send, which is pgweb’s data, and schema.socket is what the socket answers with, which is its own data. pgweb’s compose file reads that answer as integrations.postgres.socket. The jobs after it check that Postgres is up and make the database and the user.

Run the curl command again if the published port is not answering yet.

home01
$ curl -s http://localhost:8081/api/query --data-urlencode 'query=select current_user, current_database()'
{"columns":["current_user","current_database"],"rows":[["pgweb","pgweb"]],"stats":{"columns_count":2,"rows_count":1,"rows_affected":0,"query_start_time":"2026-10-07T10:06:13.944236396Z","query_finish_time":"2026-10-07T10:06:13.944690945Z","query_duration_ms":0}}

Read Underneath the socket before going on; it reads what this page left running.

Next: A label and a location.