Requires: PostgreSQLClient

Example Usage

This is what a charm using this relation would look like:

from charmhelpers.core import hookenv
from charmhelpers.core.reactive import hook
from charmhelpers.core.reactive import when
from charmhelpers.core.reactive import when_file_changed
from charmhelpers.core.reactive import set_state
from charmhelpers.core.reactive import remove_state

@when('db.connected')
def request_db(pgsql):
    pgsql.set_database('mydb')

@when('config.changed')
def check_admin_pass():
    admin_pass = hookenv.config()['admin-pass']
    if admin_pass:
        set_state('admin-pass')
    else:
        remove_state('admin-pass')

@when('db.master.available', 'admin-pass')
def render_config(pgsql):
    render_template('app-config.j2', '/etc/app.conf', {
        'db_conn': pgsql.master,
        'admin_pass': hookenv.config('admin-pass'),
    })

@when_file_changed('/etc/app.conf')
def restart_service():
    hookenv.service_restart('myapp')

Reference

class requires.ConnectionString

A libpq connection string.

>>> c = ConnectionString(host='1.2.3.4', dbname='mydb',
...                      port=5432, user='anon', password='secret')
...
>>> c
'host=1.2.3.4 dbname=mydb port=5432 user=anon password=secret

Components may be accessed as attributes.

>>> c.dbname
'mydb'
>>> c.host
'1.2.3.4'
>>> c.port
'5432'

The standard URI format is also accessible:

>>> c.uri
'postgresql://anon:secret@1.2.3.4:5432/mydb'

class requires.ConnectionStrings(relid)

Collection of ConnectionString for a relation.

ConnectionString may be accessed as a dictionary lookup by unit name, or more usefully by the master and standbys attributes. Note that the dictionary lookup may return None, when the database is not ready for use.

master

The ConnectionString for the master, or None.

standbys

Iteration of ConnectionString for active hot standbys.

class requires.PostgreSQLClient(relation_name, conversations=None)

PostgreSQL client interface.

A client may be related to one or more PostgreSQL services.

In most cases, a charm will only use a single PostgreSQL service being related for each relation defined in metadata.yaml (so one per relation name). To access the connection strings, use the master and standbys attributes:

@when('productdb.master.available')
def setup_database(pgsql):
    conn_str = pgsql.master  # A ConnectionString.
    update_db_conf(conn_str)

@when('productdb.standbys.available')
def setup_cache_databases(pgsql):
    set_cache_db_list(pgsql.standbys)  # set of ConnectionString.

In somecases, a relation name may be related to several PostgreSQL services. You can also access the ConnectionStrings for a particular service by relation id or by iterating over all of them:

@when('db.master.available')
def set_dbs(pgsql):
    update_monitored_dbs(cs.master
                         for cs in pgsql  # ConnectionStrings.
                         if cs.master)

connection_string(unit=None)

ConnectionString to the remote unit, or None.

unit defaults to the active remote unit.

You should normally use the master or standbys attributes rather than this method.

If the unit is related multiple times using the same relation name, the first one found is returned.

master

ConnectionString to the master, or None.

If multiple PostgreSQL services are related using this relation name then the first master found is returned.

set_database(dbname, relid=None)

Set the database that the named relations connect to.

The PostgreSQL service will create the database if necessary. It will never remove it.

Parameters:

• dbname – The database name. If unspecified, the local service name is used.
• relid – relation id to send the database name setting to. If unset, the setting is broadcast to all relations sharing the relation name.

set_extensions(extensions, relid=None)

Provide a set of extensions to be installed into the database.

The PostgreSQL service will attempt to install the requested extensions into the database. Extensions not bundled with PostgreSQL are normally installed onto the PostgreSQL service using the extra_packages config setting.

set_roles(roles, relid=None)

Provide a set of roles to be granted to the database user.

Granting permissions to roles allows you to grant database access to other charms.

The PostgreSQL service will create the roles if necessary.

standbys

Set of class:ConnectionString to the read-only hot standbys.

If multiple PostgreSQL services are related using this relation name then all standbys found are returned.