Step 4: an app that uses Postgres through a plug
New line, in development. Installed on a four-node test cluster built from shc next
b43f0c168(ce5db649eb) on 2026-10-08. The output below is that run’s, trimmed.
Step 2’s Postgres offers a socket: “ask me for a database and a user”. An app that wants one declares a plug of the same name. Connecting the two at install makes SHC run the socket’s jobs, which create what the plug asked for, and hands the app the connection details. Here the app is pgweb, a web client for Postgres. Keep pg from step 2 installed.
pgweb/ app.yaml vars.yaml postgres.plug.yaml compose.yamlname: pgwebversion: "0.16.2"title: pgwebdescription: A web client for a Postgres it reaches through a plugcategory: developmentlicense: id: MIT
vars: 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: "ref+vault://pgweb_db_password?autogen"# pgweb/postgres.plug.yaml: the file name is the plug's name, and it matches the socket'srequired: true # pgweb does not install without a connected postgresservices: - pgweb # the services that receive the connectiondata: # what the plug asks the socket for 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 }}@{{ 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"] # this image has curl, not wget interval: 10s retries: 6 deploy: resources: limits: cpus: "0.25" memory: 128Mintegrations.postgres is the connected edge: plug.data is what this app asked for, socket what the Postgres deployment offers (its postgres.socket.yaml publishes hostname: "{{ environment }}.postgres.{{ stack }}" and port: 5432).
Install it
Section titled “Install it”$ shc install /root/tutorial/pgweb -s pgweb -t rig -i postgres=pg --expose 8081=pgweb:8081installing stack "pgweb"pgweb: startingpgweb: runningpgweb: pgweb runninginstalled deployment "pgweb"exposure: lan$ shc integration ls -t rig -e prodCONSUMER STACK NAME CONSUMER PLUG PROVIDER STACK NAME PROVIDER SOCKET STATUS IDpgweb postgres pg postgres connected 0-i postgres=pg connects the plug postgres to the deployment pg. The install may run from any node: the socket’s contract and variables are read from the replicated store, not from pg’s directory (SHC-1546, ce modules/app/provider_render.go). Where the consumer runs follows the socket’s declared placement: {colocate: location} (modules/postgres/postgres.socket.yaml), so pgweb lands in pg’s location.
What the edge did
Section titled “What the edge did”Before pgweb started, the socket’s create-database job connected to pg as its admin user and created the database and the user the plug asked for:
$ shc exec -s pg -t rig -S postgres-1 -- psql -U postgres -d postgres -tAc "select datname, pg_get_userbyid(datdba) from pg_database where datname = 'pgweb'"pgweb|pgweb$ curl -s http://<node address>:8081/api/query --data-urlencode "query=select current_user, current_database(), inet_server_addr()" | jq -c .rows[["pgweb","pgweb","10.64.49.3"]]pgweb is connected as its own user to its own database, and the server it reached is pg’s member postgres-1, at the address it answers on. The rendered environment, with the password left out:
environment: PGWEB_DATABASE_URL: postgres://pgweb:<the password>@prod.postgres.pg:5432/pgweb?sslmode=disableprod.postgres.pg is <environment>.<group>.<stack> of the Postgres deployment: the group postgres, whose name answers with its writer, member 1 here. The node resolver the render sets as the service’s dns answers it.
Remove it
Section titled “Remove it”$ shc uninstall pgweb -t rig -yuninstalling stack "pgweb"pgweb: uninstalling stack "pgweb" on node far01, which holds itpgweb: taking the safety backup of stack "pgweb"pgweb: taking stack "pgweb" out of every node's service VIP tablepgweb: tearing down stack "pgweb"pgweb: taking down the replicas of stack "pgweb" on node far01pgweb: removing the copy of stack "pgweb" on node home01uninstalled deployment "pgweb"pgweb: removed with the deployment: config lanEnforcementUninstalling the consumer leaves pg, its database pgweb and the user in place. Keep pg for step 7.