# -*- ispell-local-dictionary: "english" -*-

* Description

=postgres-stub= allows you to declare an external =postgres= so that
your local services can connect to it. It assumes you have the host,
port of the external postgres access, and a login, password, and a
database (already created) to connect to.

For now, this stub can't manage an admin access to create database, and
more. This would be an easy addition thou.

This can be useful for instance if you have an external provider giving
you access to their postgres (use SSL then!), or in your private cloud,
or on the same host but not managed by docker, either directly on the host
or by other virtual services (LXC, VMWare...).

* Usage

You can declare a stub service by specifying at least the host of your
external =postgres= database.

#+begin_src yaml
my-postgres-stub:
  charm: postgres-stub
  options:
    host: my-host.mydomain.fr:20432
#+end_src

If you don't specify a port, then it'll be defaulted to ~5432~

Any service that want to connect to this database could then:

#+begin_src yaml
myservice:
  # ...
  relations:
    postgres-database:
      postgres-stub:
        my-postgres-stub:
          dbname: my-db-name
          user: my-username
          password: my-p4s5w0rd
#+end_src


** database name and user automatic assignation

It can be useful, if you have several services in the same ~compose.yml~
to assign database names and user automatically to avoid repeating them.

#+begin_src yaml
my-postgres-stub:
  charm: postgres-stub
  options:
    host: my-host.mydomain.fr:20432
    service-dbname-map:
      service1: u_foo
      ## Leveraging regex replacement for all other services
      .*: xyz_$0
    service-user-map:
      .*: u_$0
#+end_src