db and db‐admin relations

This reference documentation details the implementation of the db and db-admin relations. These are legacy client relations, and are used to connect to applications that use the legacy interface for postgresql; as such, they will be deprecated in the future. The file implementing these relations can be found here: src/relations/db.py.

These two relations are identical, except that the db-admin relation has total admin permissions on the postgresql charm. This is clearly a security risk, and should only be used where necessary. The updated client relation provides more finely-grained control over permissions, and is recommended for future charm development.

Expected Interface

These are the expected contents of the databags in this relation (all values are examples, generated in a running test instance):

category	keys	pgbouncer-k8s/0	finos-waltz/0
metadata	endpoint	'db'	'db'
	leader	True	True
application data	allowed-subnets	10.152.183.122/32
	allowed-units	pgbouncer-k8s/0
	database	waltz	waltz
	host	pgbouncer-k8s-0.pgbouncer-k8s-op…
	master	host=pgbouncer-k8s-0.pgbouncer-k… dbname=waltz port=6432 user=relation_3 password=BjWDKjvZyClvTl4d5VDOK3mH fallback_application_name=finos-waltz
	password	BjWDKjvZyClvTl4d5VDOK3mH
	port	6432
	standbys	host=pgbouncer-k8s-0.pgbouncer-k… dbname=waltz port=6432 user=relation_3 password=BjWDKjvZyClvTl4d5VDOK3mH fallback_application_name=finos-waltz
	state	master
	user	relation_3
	version	12.11
unit data	allowed-subnets	10.152.183.122/32
	allowed-units	pgbouncer-k8s/0
	database	waltz	waltz
	host	pgbouncer-k8s-0.pgbouncer-k8s-op…
	master	host=pgbouncer-k8s-0.pgbouncer-k… dbname=waltz port=6432 user=relation_3 password=BjWDKjvZyClvTl4d5VDOK3mH fallback_application_name=finos-waltz
	password	BjWDKjvZyClvTl4d5VDOK3mH
	port	6432
	standbys	host=pgbouncer-k8s-0.pgbouncer-k… dbname=waltz port=6432 user=relation_3 password=BjWDKjvZyClvTl4d5VDOK3mH fallback_application_name=finos-waltz
	state	master
	user	relation_3
	version	12.11

Hook Handler Flowcharts

These flowcharts detail the control flow of the hooks in this program. Unless otherwise stated, a hook deferral is always followed by a return.

db and db-admin Relation Joined Hook

flowchart TD
  hook_fired([db-relation-joined Hook]) --> is_backend_ready{Is backend database ready?}
  is_backend_ready -- no --> defer>defer]
  is_backend_ready -- yes --> is_cfg{Is pgbouncer config available?}
  is_cfg -- no --> defer2>defer]
  is_cfg -- yes --> extension_requested{Has the remote application requested extensions?}
  extension_requested -- yes --> block[Set BlockedStatus:  This charm currently doesn't support extensions.]--> rtn3([Return])
  extension_requested -- no --> get_data[Get database from databag and generate username]
  get_data --> is_leader{is this unit the leader}
  is_leader -- no --> is_pw_in_databag{Is password in   peer databag, and  has the client app shared a  database name?}
  is_pw_in_databag -- no --> defer4>defer]
  is_pw_in_databag -- yes --> store_data[Store username, password, and database  in client relation databags]
  is_leader -- yes --> gen_pw[Generate password and store in peer databag]
  gen_pw --> store_data
  store_data --> is_leader2{Is this unit the leader}
  is_leader2 -- no --> rtn([Return])
  is_leader2 -- yes --> create_pg_data[Create user and database  on backend postgres charm]
  create_pg_data --> add_to_cfg[Add database and user to pgbouncer config]
  add_to_cfg --> rtn2([Return])

Loading

db and db-admin Relation Changed Hook

flowchart TD
  hook_fired([db-relation-changed Hook]) --> is_backend_ready{Is backend database ready?}
  is_backend_ready -- no --> defer>defer]
  is_backend_ready -- yes --> is_initialised{Check databag to see if this relation is initialised}
  is_initialised -- no --> defer2>defer]
  is_initialised -- yes --> update_connection[Update connection information]
  update_connection --> update_pg[Update postgres endpoints in pgb config]
  update_pg --> update_databags[Update relation databags]
  update_databags --> rtn([return])

Loading

db And db-admin Relation Departed Hook

flowchart TD
  hook_fired([db-relation-departed Hook]) --> is_this_unit_departing{Is this unit the departing unit?}
  is_this_unit_departing -- yes --> tell_peers[update peer unit databag to tell peers this unit is departing]
  tell_peers --> rtn([return])
  is_this_unit_departing -- no --> update_databags[Update relation databags  with relevant allowed units]
  update_databags --> rtn

Loading

db and db-admin Relation Broken Hook

flowchart TD
  hook_fired([db-relation-Broken Hook]) --> is_departing{Is this unit  departing?}
  is_departing -- yes --> rtn([return])
  is_departing -- no --> is_ready{Is this relation  initialised, and is the  backend ready?}
  is_ready -- no --> defer>defer]
  is_ready -- yes --> can_remove_db{Is this relation the last one still using this database?}
  can_remove_db -- yes --> remove_db[Remove database  from config and remove auth function]
  remove_db --> remove_user
  can_remove_db -- no --> remove_user[Remove user for this relation]
  remove_user --> rtn2([return])

Loading