How to integrate a database with your charm

Charmed PostgreSQL can be integrated with any charmed application that supports its interfaces. This page provides some guidance and resources for charm developers to develop, integrate, and troubleshoot their charm so that it may connect with PostgreSQL.

Summary

• Check supported interfaces
• Integrate your charm with PostgreSQL
• Troubleshooting & testing
• FAQ

Check supported interfaces

First, we recommend that you check the supported interfaces of the current charm. You have options to use modern (preferred) or legacy interfaces.

Most existing charms currently use ops-lib-pgsql interface (legacy). For new charms, Canonical recommends using data-platform-libs instead.

Legacy charm details are described here.

Integrate your charm with PostgreSQL

For an introduction to the concepts of Juju integrations, see Juju | Integration.

For a detailed tutorial about integrating your charm with the PostgreSQL charm, refer to Juju | Integrate your charm with PostgreSQL.

For some practical examples, take a look at the following:

• postgresql-test-app GitHub repository
• juju-sdk-tutorial-k8s - the branch 04_integrate_with_psql describes integration with Charmed PostgreSQL K8s
• How to migrate Nextcloud to new PostgreSQL (vm-charms) guide

Troubleshooting & testing

• To learn the basics of charm debugging, start with Juju | How to debug a charm
• To troubleshoot PostgreSQL, check the Troubleshooting reference
• To test PostgreSQL and other charms, check the Testing reference

FAQ

Does the requirer need to set anything in relation data?

It depends on the interface. Check the postgresql_client interface requirements.

Is there a charm library available, or does my charm need to compile the postgresql relation data on its own?

Yes, the library is available: data-platform-libs. The integration is trivial: example.

How do I obtain the database url/uri?

This feature is planned but currently missing.

Meanwhile, use this example or refer to the function below.

def _db_connection_string(self) -> str:
   """Report database connection string using info from relation databag."""
   relation = self.model.get_relation("database")
   if not relation:
       return ""

   data = self._database.fetch_relation_data()[relation.id]
   username = data.get("username")
   password = data.get("password")
   endpoints = data.get("endpoints")
   
   return f"postgres://{username}:{password}@{endpoints}/ratings"

Success stories

• How to migrate Nextcloud to new PostgreSQL (vm-charms).

Contact us if you have any questions, issues, or ideas!