# salt.returners.pgjsonb

Return data to a PostgreSQL server with json data stored in Pg's jsonb data type

maintainer:

  Dave Boucha <dave@saltstack.com>, Seth House <shouse@saltstack.com>, C. R. Oldham <cr@saltstack.com>

maturity:

  Stable

depends:

  python-psycopg2

platform:

  all

Note

There are three PostgreSQL returners. Any can function as an external master job cache. but each has different features. SaltStack recommends `returners.pgjsonb` if you are working with a version of PostgreSQL that has the appropriate native binary JSON types. Otherwise, review `returners.postgres` and `returners.postgres_local_cache` to see which module best suits your particular needs.

To enable this returner, the minion will need the python client for PostgreSQL installed and the following values configured in the minion or master config. These are the defaults:

    returner.pgjsonb.host: 'salt'
    returner.pgjsonb.user: 'salt'
    returner.pgjsonb.pass: 'salt'
    returner.pgjsonb.db: 'salt'
    returner.pgjsonb.port: 5432

SSL is optional. The defaults are set to None. If you do not want to use SSL, either exclude these options or set them to None.

    returner.pgjsonb.sslmode: None
    returner.pgjsonb.sslcert: None
    returner.pgjsonb.sslkey: None
    returner.pgjsonb.sslrootcert: None
    returner.pgjsonb.sslcrl: None

Added in version 2017.5.0.

Alternative configuration values can be used by prefacing the configuration with alternative.. Any values not found in the alternative configuration will be pulled from the default location. As stated above, SSL configuration is optional. The following ssl options are simply for illustration purposes:

    alternative.pgjsonb.host: 'salt'
    alternative.pgjsonb.user: 'salt'
    alternative.pgjsonb.pass: 'salt'
    alternative.pgjsonb.db: 'salt'
    alternative.pgjsonb.port: 5432
    alternative.pgjsonb.ssl_ca: '/etc/pki/mysql/certs/localhost.pem'
    alternative.pgjsonb.ssl_cert: '/etc/pki/mysql/certs/localhost.crt'
    alternative.pgjsonb.ssl_key: '/etc/pki/mysql/certs/localhost.key'

Should you wish the returner data to be cleaned out every so often, set `keep_jobs_seconds` to the number of seconds for the jobs to live in the tables. Setting it to `0` or leaving it unset will cause the data to stay in the tables.

Should you wish to archive jobs in a different table for later processing, set `archive_jobs` to True. Salt will create 3 archive tables;

- `jids_archive`

- `salt_returns_archive`

- `salt_events_archive`

and move the contents of `jids`, `salt_returns`, and `salt_events` that are more than `keep_jobs_seconds` seconds old to these tables.

Added in version 2019.2.0.

Use the following Pg database schema:

    CREATE DATABASE  salt
      WITH ENCODING 'utf-8';

    --
    -- Table structure for table `jids`
    --
    DROP TABLE IF EXISTS jids;
    CREATE TABLE jids (
       jid varchar(255) NOT NULL primary key,
       load jsonb NOT NULL
    );
    CREATE INDEX idx_jids_jsonb on jids
           USING gin (load)
           WITH (fastupdate=on);

    --
    -- Table structure for table `salt_returns`
    --

    DROP TABLE IF EXISTS salt_returns;
    CREATE TABLE salt_returns (
      fun varchar(50) NOT NULL,
      jid varchar(255) NOT NULL,
      return jsonb NOT NULL,
      id varchar(255) NOT NULL,
      success varchar(10) NOT NULL,
      full_ret jsonb NOT NULL,
      alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW());

    CREATE INDEX idx_salt_returns_id ON salt_returns (id);
    CREATE INDEX idx_salt_returns_jid ON salt_returns (jid);
    CREATE INDEX idx_salt_returns_fun ON salt_returns (fun);
    CREATE INDEX idx_salt_returns_return ON salt_returns
        USING gin (return) with (fastupdate=on);
    CREATE INDEX idx_salt_returns_full_ret ON salt_returns
        USING gin (full_ret) with (fastupdate=on);

    --
    -- Table structure for table `salt_events`
    --

    DROP TABLE IF EXISTS salt_events;
    DROP SEQUENCE IF EXISTS seq_salt_events_id;
    CREATE SEQUENCE seq_salt_events_id;
    CREATE TABLE salt_events (
        id BIGINT NOT NULL UNIQUE DEFAULT nextval('seq_salt_events_id'),
        tag varchar(255) NOT NULL,
        data jsonb NOT NULL,
        alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
        master_id varchar(255) NOT NULL);

    CREATE INDEX idx_salt_events_tag on
        salt_events (tag);
    CREATE INDEX idx_salt_events_data ON salt_events
        USING gin (data) with (fastupdate=on);

Required python modules: Psycopg2

To use this returner, append '--return pgjsonb' to the salt command.

    salt '*' test.ping --return pgjsonb

To use the alternative configuration, append '--return_config alternative' to the salt command.

Added in version 2015.5.0.

    salt '*' test.ping --return pgjsonb --return_config alternative

To override individual configuration items, append --return_kwargs '{"key:": "value"}' to the salt command.

Added in version 2016.3.0.

    salt '*' test.ping --return pgjsonb --return_kwargs '{"db": "another-salt"}'

salt.returners.pgjsonb.clean_old_jobs()

  Called in the master's event loop every loop_interval. Archives and/or deletes the events and job details from the database. :return:

salt.returners.pgjsonb.event_return(events)

  Return event to Pg server

  Requires that configuration be enabled via 'event_return' option in master config.

salt.returners.pgjsonb.get_fun(fun)

  Return a dict of the last function called for all minions

salt.returners.pgjsonb.get_jid(jid)

  Return the information returned when the specified job id was executed

salt.returners.pgjsonb.get_jids()

  Return a list of all job ids

salt.returners.pgjsonb.get_load(jid)

  Return the load data that marks a specified jid

salt.returners.pgjsonb.get_minions()

  Return a list of minions

salt.returners.pgjsonb.prep_jid(nocache=False, passed_jid=None)

  Do any work necessary to prepare a JID, including sending a custom id

salt.returners.pgjsonb.returner(ret)

  Return data to a Pg server

salt.returners.pgjsonb.save_load(jid, load, minions=None)

  Save the load to the specified jid id

salt.returners.pgjsonb.save_minions(jid, minions, syndic_id=None)

  Included for API consistency