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.
$ shc uninstall db2 --no-backup -yuninstalling 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.
name: pgwebversion: "0.16.2"title: pgwebdescription: A web client for Postgres through a plugcategory: developmentlicense: id: MITvars: postgres: database@identifier!: database the plug asks for username@identifier!: user the plug asks for password@secret!: that user's passwordpostgres: database: pgweb username: pgweb password: P@ssw0rdrequired: trueservices: - pgwebdata: database: "{{ vars.postgres.database }}" username: "{{ vars.postgres.username }}" password: "{{ vars.postgres.password }}"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: 128Mapp.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).
$ shc install ~/learn/pgweb -s pgweb -i postgres=db --expose 8081=pgweb:8081installing deployment "pgweb"[pgweb] Healthy 1/1✔ pgweb healthy✔ installed deployment "pgweb"exposure: lan$ shc integration lsCONSUMER STACK NAME CONSUMER PLUG PROVIDER STACK NAME PROVIDER SOCKET STATUS IDpgweb 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:
$ sed '/^jobs:/q' /usr/lib/shc/apps/postgres/postgres.socket.yamlschema: 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.
$ 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.