From 5bca2873e6f1409bfbdf37d2566220e2f99087ab Mon Sep 17 00:00:00 2001
From: Will Fitch <will.fitch@canonical.com>
Date: Thu, 10 Nov 2022 12:28:52 +0000
Subject: [PATCH] Update docs (#36)

# PR
## Proposal
The docs for this charm were unclear and outdated. This PR updates them to match the current state of the charm. Further updates coming in client relation PRs.

## Comments
* updated docs

* finished usage docs, added social docs and updated relation info
---
 README.md | 63 +++++++++++++++++++++++++++----------------------------
 1 file changed, 31 insertions(+), 32 deletions(-)

diff --git a/README.md b/README.md
index 321bb244c..e349e2bb0 100644
--- a/README.md
+++ b/README.md
@@ -2,13 +2,32 @@
 
 ## Description
 
-The PgBouncer Operator deploys and operates the [PgBouncer](https://www.pgbouncer.org) lightweight connection pooler for PostgreSQL.
+The PgBouncer Operator deploys and operates the [PgBouncer](https://www.pgbouncer.org) lightweight connection pooler for PostgreSQL. This charm is only compatible with the [data platform postgresql-operator charm](https://github.com/canonical/postgresql-operator).
 
 ## Usage
 
-As this charm is not yet published, you need to follow the build and deploy instructions from [CONTRIBUTING.md](https://github.com/canonical/pgbouncer-operator/CONTRIBUTING.md). This charm creates one pgbouncer application instance per CPU core on each machine it is deployed.
+To deploy pgbouncer in front of three units of postgres:
 
-### Config Options
+```bash
+juju deploy pgbouncer --channel=edge
+juju deploy postgresql --channel=edge -n 3
+juju add-relation pgbouncer:backend-database postgresql:database
+```
+
+To deploy and relate an application to the above cluster, using the legacy pgsql relation (not recommended - this will be deprecated in future):
+
+```bash
+juju deploy my-app
+juju add-relation pgbouncer:db my-app:db
+```
+
+Or, if my-app needs admin permissions:
+
+```bash
+juju add-relation pgbouncer:db-admin my-app:db
+```
+
+### Configuration Options
 
 Set these using the command `juju config <option>=<value>`.
 
@@ -53,36 +72,18 @@ The following config values are set as constants in the charm:
 
 ## Relations
 
-- `database`
-- `database-admin`
-- `backend-database-admin`
-  - Relates to backend postgresql database charm.
+- `backend-database`
+  - Relates to backend [postgresql-operator](https://github.com/canonical/postgresql-operator) database charm. Without a backend relation, this charm will enter BlockedStatus - if there's no Postgres backend, this charm has no purpose.
 
 ### Legacy Relations
 
-The following relations are legacy, and will be deprecated in a future release.
-
-- `db:[pgsql](https://github.com/canonical/ops-lib-pgsql/)`
-- `db-admin:[pgsql](https://github.com/canonical/ops-lib-pgsql/)`
-  - Relates
-- `backend-db-admin:[pgsql](https://github.com/canonical/ops-lib-pgsql/)`
-  - Without a backend relation, this charm will enter BlockedStatus - if there's no Postgres backend, this charm has no purpose.
-  - Provides a relation to the corresponding [postgresql-operator charm](https://github.com/canonical/postgresql-operator), as well as all charms using this legacy relation.
-  - This relation expects the following data from provider charms:
-    - `master` field, for the primary postgresql unit.
-    - `standbys` field, a \n-delimited list of standby data.
-  - This legacy relation uses the unfortunate `master` term for postgresql primaries.
-  - This relation is to be deprecated in future.
-
-### Observability
-
-TODO update to match COS.
-
-The following relations provide support for the [LMA charm bundle](https://juju.is/docs/lma2), our expected observability stack.
+The following relations are legacy, and will be deprecated in a future release in favour of relations using the [data platform provides library.](https://github.com/canonical/data-platform-libs/blob/main/lib/charms/data_platform_libs/v0/database_provides.py) For future compatibility, build relations with the [data platform **requires** library](https://github.com/canonical/data-platform-libs/blob/main/lib/charms/data_platform_libs/v0/database_requires.py).
 
-- `prometheus:prometheus_scrape`
-- `loki:loki_push_api`
-- `grafana:grafana_dashboards`
+- `db`
+  - Provides read-write access to backend database
+- `db-admin`
+  - Provides read-write access to backend database
+  - The user created by the relation (credentials provided in the relation databag) has admin permissions
 
 ## License
 
@@ -94,6 +95,4 @@ Security issues in the Charmed PgBouncer Operator can be reported through [Launc
 
 ## Contributing
 
-Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines
-on enhancements to this charm following best practice guidelines, and
-[CONTRIBUTING.md](https://github.com/canonical/pgbouncer-operator/CONTRIBUTING.md) for developer guidance.
+Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines on enhancements to this charm following best practice guidelines, and [CONTRIBUTING.md](https://github.com/canonical/pgbouncer-operator/CONTRIBUTING.md) for developer guidance. For more information, get in touch on the [Charmhub Mattermost server](https://chat.charmhub.io).