Routing functions
=================

bdr.create_proxy
^^^^^^^^^^^^^^^^

Create a proxy configuration.

Synopsis
^^^^^^^^

.. code:: sql

   bdr.create_proxy(proxy_name text, node_group text, proxy_mode text);

Parameters
^^^^^^^^^^

.. csv-table::
  :header: Name,Type,Default,Description
  :widths: 10,8,8,20
  :align: left
  :class: longtable

  `proxy_name`,text,"",Name of the new proxy.
  `node_group`,text,"",Name of the group to be used by the proxy.
  `proxy_mode`,text,`'default'`,"Mode of the proxy. It can be `'default'` (listen_port connections follow write leader, no read_listen_port), `'read-only'` (no listen_port, read_listen_port connections follow read-only nodes), or `'any'` (listen_port connections follow write_leader, read_listen_port connections follow read-only nodes). Default is `'default'`."

When proxy_mode is set to ``'default'`` , all read options in the proxy
config are set to NULL. When it’s set to ``'read-only'`` , all write
options in the proxy config are set to NULL. When set to ``'any'`` all
options are set to their defaults.

bdr.alter_proxy_option
^^^^^^^^^^^^^^^^^^^^^^

Change a proxy configuration.

.. _synopsis-1:

Synopsis
^^^^^^^^

.. code:: sql

   bdr.alter_proxy_option(proxy_name text, config_key text, config_value text);

.. _parameters-1:

Parameters
^^^^^^^^^^

.. csv-table::
  :header: Name,Type,Default,Description
  :widths: 10,8,8,20
  :align: left
  :class: longtable

  `proxy_name`,text,"",Name of the proxy to change.
  `config_key`,text,"",Key of the option in the proxy to change.
  `config_value`,text,"",New value to set for the given key.

The table shows the proxy options (``config_key`` ) that can be changed
using this function.

.. csv-table::
  :header: Option,Description
  :widths: 10,30
  :align: left
  :class: longtable

  `listen_address`,Address for the proxy to listen on. Default is '{0.0.0.0}'.
  `listen_port`,"Port for the proxy to listen on. Default is '6432' in 'default' or 'any' mode and '0' in 'read-only' mode, which disables the write leader following port."
  `max_client_conn`,Maximum number of connections for the proxy to accept. Default is '32767'.
  `max_server_conn`,Maximum number of connections the proxy can make to the Postgres node. Default is '32767'.
  `server_conn_timeout`,Connection timeout for server connections. Default is '2' (seconds).
  `server_conn_keepalive`,Keepalive interval for server connections. Default is '10' (seconds).
  `consensus_grace_period`,"Duration for which proxy continues to route even upon loss of a Raft leader. If set to 0s, proxy stops routing immediately. Default is generally '6' (seconds) for local proxies and '12' (seconds) for global proxies. These values will be overridden if `raft_response_timeout`, `raft_global_election_timeout`, or `raft_group_election_timeout` are changed from their defaults."
  `read_listen_address`,Address for the read-only proxy to listen on. Default is '{0.0.0.0}'.
  `read_listen_port`,"Port for the read-only proxy to listen on. Default is '6433' in 'read-only' or 'any' mode and '0' in 'default' mode, which disables the read-only port."
  `read_max_client_conn`,Maximum number of connections for the read-only proxy to accept. Default is '32767'.
  `read_max_server_conn`,Maximum number of connections the read-only proxy can make to the Postgres node. Default is '32767'.
  `read_server_conn_keepalive`,Keepalive interval for read-only server connections. Default is '10' (seconds).
  `read_server_conn_timeout`,Connection timeout for read-only server connections. Default is '2' (seconds).
  `read_consensus_grace_period`,Duration for which read-only proxy continues to route even upon loss of a Raft leader. Default is 1 hour.

Changing any of these values requires a restart of the proxy.

bdr.drop_proxy
^^^^^^^^^^^^^^

Drop a proxy configuration.

.. _synopsis-2:

Synopsis
^^^^^^^^

.. code:: sql

   bdr.drop_proxy(proxy_name text);

.. _parameters-2:

Parameters
^^^^^^^^^^

.. csv-table::
  :header: Name,Type,Default,Description
  :widths: 10,8,8,20
  :align: left
  :class: longtable

  `proxy_name`,text,"",Name of the proxy to drop.

bdr.routing_leadership_transfer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Changing the routing leader transfers the leadership of the node group
to another node.

.. _synopsis-3:

Synopsis
^^^^^^^^

.. code:: sql

   bdr.routing_leadership_transfer(node_group_name text,
                 leader_name text,
                 transfer_method text DEFAULT strict,
                 transfer_timeout interval DEFAULT 10s);

.. _parameters-3:

Parameters
^^^^^^^^^^

.. csv-table::
  :header: Name,Type,Default,Description
  :widths: 10,8,8,20
  :align: left
  :class: longtable

  `node_group_name`,text,"",Name of group where the leadership transfer is requested.
  `leader_name`,text,"",Name of node that will become write leader.
  `transfer_method`,text,`'strict'`,"Type of the transfer. It can be `'fast'` or the default, `'strict'`, which checks the maximum lag."
  `transfer_timeout`,interval,'10s',Timeout of the leadership transfer. Default is 10 seconds.