Skip to content

Commit

Permalink
Update docs (#36)
Browse files Browse the repository at this point in the history
# 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
  • Loading branch information
Will Fitch authored Nov 10, 2022
1 parent 74ba1d5 commit 5bca287
Showing 1 changed file with 31 additions and 32 deletions.
63 changes: 31 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>`.

Expand Down Expand Up @@ -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

Expand All @@ -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).

0 comments on commit 5bca287

Please sign in to comment.