Data Platform Libs

Channel Revision Published Runs on
latest/stable 54 01 Nov 2023
Ubuntu 22.04 Ubuntu 20.04
latest/stable 2 21 Jul 2022
Ubuntu 22.04 Ubuntu 20.04
latest/candidate 54 01 Nov 2023
Ubuntu 22.04
latest/edge 76 13 Jun 2024
Ubuntu 22.04 Ubuntu 20.04
latest/edge 9 21 Oct 2022
Ubuntu 22.04 Ubuntu 20.04
juju deploy data-platform-libs
Show information

Platform:

Ubuntu
22.04 20.04

charms.data_platform_libs.v0.database_provides

[DEPRECATED] Relation provider side abstraction for database relation.

This library is a uniform interface to a selection of common database metadata, with added custom events that add convenience to database management, and methods to set the application related data.

It can be used as the main library in a database charm to handle relations with application charms or be extended/used as a template when creating a more complete library (like one that also handles the database and user creation using database specific APIs).

Following an example of using the DatabaseRequestedEvent, in the context of the database charm code:

from charms.data_platform_libs.v0.database_provides import DatabaseProvides

class SampleCharm(CharmBase):

    def __init__(self, *args):
        super().__init__(*args)

        # Charm events defined in the database provides charm library.
        self.provided_database = DatabaseProvides(self, relation_name="database")
        self.framework.observe(self.provided_database.on.database_requested,
            self._on_database_requested)

        # Database generic helper
        self.database = DatabaseHelper()

    def _on_database_requested(self, event: DatabaseRequestedEvent) -> None:
        # Handle the event triggered by a new database requested in the relation

        # Retrieve the database name using the charm library.
        db_name = event.database

        # generate a new user credential
        username = self.database.generate_user()
        password = self.database.generate_password()

        # set the credentials for the relation
        self.provided_database.set_credentials(event.relation.id, username, password)

        # set other variables for the relation event.set_tls("False")

As shown above, the library provides a custom event (database_requested) to handle the situation when an application charm requests a new database to be created. It's preferred to subscribe to this event instead of relation changed event to avoid creating a new database when other information other than a database name is exchanged in the relation databag.


class DatabaseEvent

Description

Base class for database events. None

Methods

DatabaseEvent. database( self )

Description

Returns the database that was requested. None

DatabaseEvent. extra_user_roles( self )

Description

Returns the extra user roles that were requested. None

class DatabaseRequestedEvent

Description

Event emitted when a new database is requested for use on this relation. None

class DatabaseEvents

Database events.

Description

This class defines the events that the database can emit.

class DatabaseProvides

Description

Provides-side of the database relation. None

Methods

DatabaseProvides. __init__( self , charm: CharmBase , relation_name: str )

DatabaseProvides. fetch_relation_data( self )

Retrieves data from relation.

Returns

a dict of the values stored in the relation data bag for all relation instances (indexed by the relation id).

Description

This function can be used to retrieve data from a relation in the charm code when outside an event callback.

DatabaseProvides. relations( self )

Description

The list of Relation instances associated with this relation_name. None

DatabaseProvides. set_credentials( self , relation_id: int , username: str , password: str )

Set database primary connections.

Arguments

relation_id

the identifier for a particular relation.

username

user that was created.

password

password of the created user.

Description

This function writes in the application data bag, therefore, only the leader unit can call it.

DatabaseProvides. set_endpoints( self , relation_id: int , connection_strings: str )

Set database primary connections.

Arguments

relation_id

the identifier for a particular relation.

connection_strings

database hosts and ports comma separated list.

Description

This function writes in the application data bag, therefore, only the leader unit can call it.

DatabaseProvides. set_read_only_endpoints( self , relation_id: int , connection_strings: str )

Set database replicas connection strings.

Arguments

relation_id

the identifier for a particular relation.

connection_strings

database hosts and ports comma separated list.

Description

This function writes in the application data bag, therefore, only the leader unit can call it.

DatabaseProvides. set_replset( self , relation_id: int , replset: str )

Set replica set name in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

replset

replica set name.

Description

MongoDB only.

DatabaseProvides. set_tls( self , relation_id: int , tls: str )

Set whether TLS is enabled.

Arguments

relation_id

the identifier for a particular relation.

tls

whether tls is enabled (True or False).

DatabaseProvides. set_tls_ca( self , relation_id: int , tls_ca: str )

Set the TLS CA in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

tls_ca

TLS certification authority.

DatabaseProvides. set_uris( self , relation_id: int , uris: str )

Set the database connection URIs in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

uris

connection URIs.

Description

MongoDB, Redis, OpenSearch and Kafka only.

DatabaseProvides. set_version( self , relation_id: int , version: str )

Set the database version in the application relation databag.

Arguments

relation_id

the identifier for a particular relation.

version

database version.