Internal system functions v5.6

The following are internal system functions. Many are used when creating various views. We recommend that you do not use the functions directly but instead use the views that they serve.

General internal functions

bdr.bdr_get_commit_decisions

Convenience routine to inspect shared memory state.

Synopsis

bdr.bdr_get_commit_decisions(dbid OID,
            origin_node_id OID,
            origin_xid xid,
            local_xid xid,
            decision "char",
            decision_ts timestamptz,
            is_camo boolean)

bdr.bdr_track_commit_decision

Save the transaction commit status in the shared memory hash table. This dunction is used by the upgrade scripts to transfer commit decisions saved in bdr.node_pre_commit catalog to the shared memory hash table. The transaction commit status will also be logged to the WAL and hence can be reloaded from WAL.

Synopsis

bdr.bdr_track_commit_decision(OID, xid, xid, "char", timestamptz, boolean);

bdr.consensus_kv_fetch

Fetch value from the consistent KV Store in JSON format.

Synopsis

bdr.consensus_kv_fetch(IN key text) RETURNS jsonb

Parameters

ParameterDescription
keyAn arbitrary key to fetch.

Notes

This function is an internal function, mainly used by HARP.

Warning

Don't use this function in user applications.

bdr.consensus_kv_store

Stores value in the consistent KV Store.

Returns the timestamp of the value expiration time. This function depends on ttl. If ttl is NULL, then this function returns infinity. If the value was deleted, it returns -infinity.

Synopsis

bdr.consensus_kv_store(key text, value jsonb,
        prev_value jsonb DEFAULT NULL, ttl int DEFAULT NULL)

Parameters

ParameterDescription
keyAn arbitrary unique key to insert, update, or delete.
valueJSON value to store. If NULL, any existing record is deleted.
prev_valueIf set, the write operation is done only if the current value is equal to prev_value.
ttlTime-to-live of the new value, in milliseconds.

Notes

This is an internal function, mainly used by HARP.

Warning

Don't use this function in user applications.

bdr.decode_message_payload

PGD message payload function that decodes the payloads of consensus messages to a more human-readable output. Used primarily by the bdr.global_consensus_journal_details debug view.

bdr.decode_message_response_payload

PGD message payload function that decodes the payloads of responses to consensus messages to a more human-readable output. Used primarily by the bdr.global_consensus_journal_details debug view.

bdr.difference_fix_origin_create

Creates a replication origin with a given name passed as an argument but adding a bdr_ prefix. Returns the internal id of the origin. This function has the same functionality as pg_replication_origin_create() except this function requires bdr_superuser rather than postgres superuser permissions.

bdr.difference_fix_session_reset

Marks the current session as not replaying from any origin, essentially resetting the effect of bdr.difference_fix_session_setup(). It returns void. This function has the same functionality as pg_replication_origin_session_reset() except this function requires bdr_superuser rather than postgres superuser permissions.

Synopsis

bdr.difference_fix_session_reset()

bdr.difference_fix_session_setup

Marks the current session as replaying from the current origin. The function uses the pre-created bdr_local_only_origin local replication origin implicitly for the session. It allows replay progress to be reported and returns void. This function has the same functionality as pg_replication_origin_session_setup() except that this function requires bdr_superuser rather than postgres superuser permissions. The earlier form of the function, bdr.difference_fix_session_setup(text), was deprecated and will be removed in a future release.

Synopsis

bdr.difference_fix_session_setup()

bdr.difference_fix_xact_set_avoid_conflict

Marks the current transaction as replaying a transaction that committed at LSN '0/0' and timestamp '2000-01-01'. This function has the same functionality as pg_replication_origin_xact_setup('0/0', '2000-01-01') except this function requires bdr_superuser rather than postgres superuser permissions.

Synopsis

bdr.difference_fix_xact_set_avoid_conflict()

bdr.drop_node

Drops a node's metadata.

This function removes the metadata for a given node from the local database. The node can be either:

  • The local node, in which case it removes all the node metadata, including information about remote nodes.
  • A remote node, in which case it removes only metadata for that specific node.
When to use bdr.drop_node()

Do not use bdr.drop_node() to drop node metadata and reuse node names. PGD can reuse existing node names providing the node name belongs to a node in a PARTED state. Use bdr.part_node() to remove the original node and place it in a PARTED state.

Use of this internal function is limited to:

  • When you're instructed to by EDB Technical Support.
  • Where you're specifically instructed to in the documentation.

Use bdr.part_node to remove a node from a PGD group. That function sets the node to PARTED state and enables reuse of the node name.

Synopsis

bdr.drop_node(node_name text, cascade boolean DEFAULT false, force boolean DEFAULT false)

Parameters

ParameterDescription
node_nameName of an existing node.
cascadeDeprecated, will be removed in a future release.
forceCircumvents all sanity checks and forces the removal of all metadata for the given PGD node despite a possible danger of causing inconsistencies. Only Technical Support uses a forced node drop in case of emergencies related to parting.

Notes

Before you run this function, part the node using bdr.part_node().

This function removes metadata for a given node from the local database. The node can be the local node, in which case all the node metadata is removed, including information about remote nodes. Or it can be the remote node, in which case only metadata for that specific node is removed.

Note

PGD can have a maximum of 1024 node records (both ACTIVE and PARTED) at one time because each node has a unique sequence number assigned to it, for use by snowflakeid and timeshard sequences. PARTED nodes aren't automatically cleaned up. If this becomes a problem, you can use this function to remove those records.

bdr.get_global_locks

Shows information about global locks held on the local node.

Used to implement the bdr.global_locks view to provide a more detailed overview of the locks.

bdr.get_node_conflict_resolvers

Displays a text string of all the conflict resolvers on the local node.

bdr.get_slot_flush_timestamp

Retrieves the timestamp of the last flush position confirmation for a given replication slot.

Used internally to implement the bdr.node_slots view.

bdr.internal_alter_sequence_set_kind

A function previously used internally for replication of the various function calls. No longer used by the current version of PGD. Exists only for backward compatibility during rolling upgrades.

bdr.internal_replication_set_add_table

A function previously used internally for replication of the various function calls. No longer used by the current version of PGD. Exists only for backward compatibility during rolling upgrades.

bdr.internal_replication_set_remove_table

A function previously used internally for replication of the various function calls. No longer used by the current version of PGD. Exists only for backward compatibility during rolling upgrades.

bdr.internal_submit_join_request

Submits a consensus request for joining a new node.

Needed by the PGD group reconfiguration internal mechanisms.

bdr.isolation_test_session_is_blocked

A helper function, extending (and actually invoking) the original pg_isolation_test_session_is_blocked with an added check for blocks on global locks.

Used for isolation/concurrency tests.

bdr.local_node_info

Displays information for the local node needed by the PGD group reconfiguration internal mechanisms.

The view bdr.local_node_summary provides similar information useful for user consumption.

bdr.msgb_connect

Connects to the connection pooler of another node. Used by the consensus protocol.

bdr.msgb_deliver_message

Sends messages to another node's connection pooler. Used by the consensus protocol.

bdr.node_catchup_state_name

Converts catchup state code in name.

Synopsis

bdr.node_catchup_state_name(catchup_state oid);

Parameters

ParameterDescription
catchup_stateOid code of the catchup state.

bdr.node_kind_name

Returns human-friendly name of the node kind (data|standby|witness|subscriber-only).

bdr.peer_state_name

Transforms the node state (node_state) into a textual representation. Used mainly to implement the bdr.node_summary view.

bdr.pg_xact_origin

Returns the origin id of a given transaction.

Synopsis

bdr.pg_xact_origin(xmin xid)

Parameters

ParameterDescription
xidTransaction id whose origin is returned.

bdr.request_replay_progress_update

Requests the immediate writing of a 'replay progress update' Raft message. Used mainly for test purposes but can also be used to test if the consensus mechanism is working.

bdr.reset_relation_stats

Returns a Boolean result after resetting the relation stats, as viewed by bdr.stat_relation.

bdr.reset_subscription_stats

Returns a Boolean result after resetting the statistics created by subscriptions, as viewed by bdr.stat_subscription.

bdr.resynchronize_table_from_node

Resynchronizes the relation from a remote node.

Synopsis

bdr.resynchronize_table_from_node(node_name name, relation regclass)

Parameters

ParameterDescription
node_nameThe node from which to copy or resync the relation data.
relationThe relation to copy from the remote node.

Notes

This function acquires a global DML lock on the relation, truncates the relation locally, and copies data into it from the remote node.

The relation must exist on both nodes with the same name and definition.

The following are supported:

  • Resynchronizing partitioned tables with identical partition definitions
  • Resynchronizing partitioned table to nonpartitioned table and vice versa
  • Resynchronizing referenced tables by temporarily dropping and re-creating foreign key constraints

After running the function on a referenced table, if the referenced column data no longer matches the referencing column values, the function throws an error. After resynchronizing the referencing table data, rerun the function.

Furthermore, it supports resynchronization of tables with generated columns by computing the generated column values locally after copying the data from remote node.

Currently, row_filters are ignored by this function.

The bdr.resynchronize_table_from_node function can be executed only by the owner of the table, provided the owner has bdr_superuser privileges.

bdr.seq_currval

Part of the internal implementation of global sequence manipulation.

Invoked automatically when currval() is called on a galloc or snowflakeid sequence.

bdr.seq_lastval

Part of the internal implementation of global sequence manipulation.

Invoked automatically when lastval() is called on a galloc or snowflakeid sequence.

bdr.seq_nextval

Part of the internal implementation of global sequence increments.

Invoked automatically when nextval() is called on a galloc or snowflakeid sequence

bdr.show_subscription_status

Retrieves information about the subscription status. Used mainly to implement the bdr.subscription_summary view.

bdr.show_workers

Information related to the bdr workers.

Synopsis

bdr.show_workers(
    worker_pid int,
    worker_role int,
    worker_role_name text,
    worker_subid oid)

bdr.show_writers

Function used in the bdr.writers view.

Task manager functions

bdr.taskmgr_set_leader

Requests the given node to be the task manager leader node. The leader node is responsible for creating new tasks. (Currently only autopartition makes use of this facility.) A witness node, a logical standby, or a subscriber-only node can't become a leader. Such requests will fail with an error.

Synopsis

bdr.taskmgr_set_leader(node name, wait_for_completion boolean DEFAULT true);

bdr.taskmgr_get_last_completed_workitem

Return the id of the last workitem successfully completed on all nodes in the cluster.

Synopsis

bdr.taskmgr_get_last_completed_workitem();

bdr.taskmgr_work_queue_check_status

Lets you see the status of the background workers that are doing their job to generate and finish the tasks.

The status can be seen through these views:

  • bdr.taskmgr_work_queue_local_status
  • bdr.taskmgr_work_queue_global_status

Synopsis

bdr.taskmgr_work_queue_check_status(workid bigint
                           local boolean DEFAULT false);

Parameters

ParameterDescription
workidThe key of the task.
localCheck the local status only.

Notes

Taskmgr workers are always running in the background, even before the bdr.autopartition function is called for the first time. If an invalid workid is used, the function returns unknown. In-progress is the typical status.

bdr.pglogical_proto_version_ranges

Internal function for diagnostic use only.

bdr.get_min_required_replication_slots

Internal function intended for use by PGD-CLI.

bdr.get_min_required_worker_processes

Internal function intended for use by PGD-CLI.

bdr.stat_get_activity

Internal function underlying view bdr.stat_activity. Do not use directly. Use the bdr.stat_activity view instead.

bdr.worker_role_id_name

Internal helper function used when generating view bdr.worker_tasks. Do not use directly. Use the bdr.worker_tasks view instead.

bdr.lag_history

Internal function used when generating view bdr.node_replication_rates. Do not use directly. Use the bdr.node_replication_rates view instead.

bdr.get_raft_instance_by_nodegroup

Internal function used when generating view bdr.group_raft_details. Do not use directly. Use the bdr.group_raft_details view instead.

bdr.monitor_camo_on_all_nodes

Internal function used when generating view bdr.group_camo_details. Do not use directly. Use the bdr.group_camo_details view instead.

bdr.monitor_raft_details_on_all_nodes

Internal function used when generating view bdr.group_raft_details. Do not use directly. Use the bdr.group_raft_details view instead.

bdr.monitor_replslots_details_on_all_nodes

Internal function used when generating view bdr.group_replslots_details. Do not use directly. Use the bdr.group_replslots_details view instead.

bdr.monitor_subscription_details_on_all_nodes

Internal function used when generating view bdr.group_subscription_summary. Do not use directly. Use the bdr.group_subscription_summary view instead.

bdr.monitor_version_details_on_all_nodes

Internal function used when generating view bdr.group_versions_details. Do not use directly. Use the bdr.group_versions_details view instead.

bdr.node_group_member_info

Internal function used when generating view bdr.group_raft_details. Do not use directly. Use the bdr.group_raft_details view instead.