Repository files navigation

Yggdrasil for PostgreSQL is a publisher/subscriber that:

• It's easy to use and configure.
• It's fault tolerant: recovers disconnected subscriptions.
• It has reconnection support: configurable exponential backoff.
• It has OS environment variable configuration support (useful for releases).

The following example uses PostgreSQL adapter to distribute messages e.g:

Given the following channel:

iex>channel=[name:"pg_channel",adapter::postgres]

You can:

• Subscribe to it:

  iex>Yggdrasil.subscribe(channel)iex>flush(){:Y_CONNECTED,%Yggdrasil.Channel{...}}

• Publish messages to it:

  iex>Yggdrasil.publish(channel,"message")iex>flush(){:Y_EVENT,%Yggdrasil.Channel{...},"message"}

• Unsubscribe from it:

  iex>Yggdrasil.unsubscribe(channel)iex>flush(){:Y_DISCONNECTED,%Yggdrasil.Channel{...}}

And additionally, you can useYggdrasil behaviour to build a subscriber:

defmoduleSubscriberdouseYggdrasildefstart_linkdochannel=[name:"pg_channel",adapter::postgres]Yggdrasil.start_link(__MODULE__,[channel])end@implYggdrasildefhandle_event(_channel,message,_)doIO.inspectmessage{:ok,nil}endend

The previousSubscriber will print every message that comes from thePostgreSQL channelpg_channel.

The PostgreSQL adapter has the following rules:

• Theadapter name is identified by the atom:postgres.
• The channelname must be a string.
• Thetransformer must encode to a string. From thetransformers provided,it defaults to:default, but:json can also be used.
• Anybackend can be used (by default is:default).

The following is an example of a valid channel for both publishers andsubscribers:

%Yggdrasil.Channel{name:"pg_channel",adapter::postgres,transformer::json}

The previous channel expects to:

• Subscribe to or publish to the channelpg_channel.
• The adapter is:postgres, so it will connect to PostgreSQL using theappropriate adapter.
• The transformer expects valid JSONs when decoding (consuming from asubscription) andmap() orkeyword() when encoding (publishing).

Note: Though the structYggdrasil.Channel is used.keyword() andmap()are also accepted as channels as long as the contain the required keys.

This adapter supports the following list of options:

Note: Concurrency is handled byPostgrex subscriptions in order to reusedatabase connections.

For more information about the available options checkYggdrasil.Settings.Postgres.

The following shows a configuration with and without namespace:

# Without namespaceconfig:yggdrasil,postgres:[hostname:"postgres.zero"]# With namespaceconfig:yggdrasil,PostgresOne,postgres:[hostname:"postgres.one",port:1234]

All the available options are also available as OS environment variables.It's possible to even separate them by namespace e.g:

Given two namespaces, the default one andPostgres.One, it's possible toload thehostname from the OS environment variables as follows:

• $YGGDRASIL_POSTGRES_HOSTNAME for the default namespace.
• $POSTGRES_ONE_YGGDRASIL_POSTGRES_HOSTNAME forPostgres.One.

In general, the namespace will go before the name of the variable.

Using this adapter withYggdrasil is a matter of adding theavailable hex package to yourmix.exs file e.g:

defdepsdo[{:yggdrasil_postgres,"~> 5.0"}]end

Adocker-compose.yml file is provided with the project. If you don't have aPostgreSQL server, but you do have Docker installed, then you can run:

$ docker-compose up --build

And in another shell run:

$ mix deps.get$ mix test

Alexander de Sousa.

Yggdrasil is released under the MIT License. See the LICENSE file for furtherdetails.