DOCSEARCHbyAlgolia
Submit Docs

Pgpool-II Documentation

repository·master·Indexed 19 days ago

https://github.com/pgpool/pgpool2

Middleware for PostgreSQL providing connection pooling, load balancing, and high availability. Documentation covers core logic, online recovery workflows via pcp_recovery_node, configuration parameter implementation, the pgpool CLI for process management, and node detachment procedures in streaming replication mode.

Tokens
7.6K
Snippets
24
Records
35
Agent score
65%

What's inside Pgpool-II

  1. SGML linking guidelines and best practices

    master

    Follow these rules when implementing links in SGML documents:

    1. Text Selection: If you want to supply specific text for the link, use <link>. Otherwise, use <xref> to leverage automatic numbering/titles.
    2. External Links: Do not provide text inside a <ulink> if you want the URL to appear in the printed output.
    3. Technical Terms: Specific nouns such as GUC variables, SQL commands, and contrib modules usually have xreflabels defined; use <xref> to reference them correctly.

  2. Control parser output using conditional compilation in gram_template.y

    master

    You can control which code is included in the minimal vs. standard parser by using #ifdef pgpool_minimal_parser directives within the gram_template.y file:

    • Minimal Parser Only: Wrap code in #ifdef pgpool_minimal_parser or #ifndef pgpool_minimal_parser (depending on the logic used) to ensure it only appears in gram_minimal.y.
    • Standard Parser Only: Wrap code in #ifndef pgpool_minimal_parser to ensure it only appears in gram.y.
    • Both Parsers: Place code outside of any #ifdef pgpool_minimal_parser blocks to include it in both generated files.

    Logic Patterns:

    Pattern 1 (Using #ifdef):

    #ifdef pgpool_minimal_parser
// Code included ONLY in gram_minimal.y
#else
// Code included ONLY in gram.y
#endif
// Code included in BOTH

    Pattern 2 (Using #ifndef):

    #ifndef pgpool_minimal_parser
// Code included ONLY in gram.y
#else
// Code included ONLY in gram_minimal.y
#endif
// Code included in BOTH
    #ifdef pgpool_minimal_parser
code only for the minimal parser
#else
code only for the standard parser
#endif
code for both parsers

  3. Understand which files are processed by pgindent and pgperltidy

    master

    C Code (pgindent)

    Processes nearly all *.c and *.h files. Exclusions:

    • *.y and *.l files.
    • *.c and *.h files derived from *.y and *.l files.
    • Files matching patterns in exclude_file_patterns.
    • Note: ecpg header files are not excluded, though they may require updating ecpg expected files after reformatting.

    Perl Code (pgperltidy)

    Processes:

    • All *.pl and *.pm files.
    • Executable Perl scripts that do not have a .pl or .pm extension (based on find rules in pgperltidy).

  4. How online recovery works in Pgpool-II

    master

    Online recovery is a multi-stage process triggered via the pcp_recovery_node command/API. It allows a node to be recovered while the rest of the cluster remains operational.

    Recovery Workflow

    1. Trigger: The pcp_recovery_node(int node_id) API is called, which sends an "O" request to the pcp_child process.
    2. Stage 1 (Initial Recovery):
      • The start_recovery() function sets the request kind to NODE_RECOVERY_REQUEST.
      • An execute_checkpoint() is performed to run the PostgreSQL CHECKPOINT command.
      • exec_recovery is called to execute SELECT pgpool_recovery(), which runs the first stage of the recovery script.
    3. Stage 2 (Post-Recovery Setup):
      • The system sets InRecovery to 1 and waits for all frontend connections to close via wait_connection_closed().
      • Another execute_checkpoint() is performed.
      • exec_recovery is called again to execute the second stage of the recovery script.
      • exec_remote_start is called to start the PostgreSQL postmaster.
      • The system waits for the postmaster to start via check_postmaster_started.
    4. Failback and Completion:
      • The system sets the pcp_wakeup request to 0 and calls send_failback_request().
      • It monitors the pcp_wakeup_request every 1 second until it becomes non-zero.
      • finish_recovery() sets InRecovery to 0 and sends a SIGUSR2 signal to the parent process.
    5. Parent Notification:
      • Upon receiving SIGUSR2, the Pgpool parent calls kill_all_children(), which propagates SIGUSR2 to all children, waking them from pause().

  5. Use external linking in SGML

    master

    To link to external resources via a URL, use the <ulink> tag.

    • The url= attribute is required to specify the destination URL.
    • If no text is provided inside the <ulink> tags, the URL itself will appear as the link text.
    • <ulink> requires a closing </ulink> tag.
    <!-- Example of ulink with URL as text -->
<ulink url="http://example.com" />

<!-- Example of ulink with custom text -->
<ulink url="http://example.com">Visit Example</ulink>

  6. How to add a new PCP protocol

    master
    To implement a new PCP (Process Check Protocol) command, you must implement logic on both the server side (pcp_worker.c) and the client side (pcp_frontend_client.c). The process involves defining a protocol identifier, handling the server-side command dispatch, constructing the response packet, and updating the client-side utility to handle the new command type.

  7. Update the POOL_CONFIG struct

    master

    The POOL_CONFIG struct holds all global configuration variables. You must add your new parameter to this struct in src/include/pool_config.h. For enum types, use the enum type you defined in the previous step.

    DLBOW_OPTION	disable_load_balance_on_write; /* Load balance behavior when write query is issued... */

  8. How to use pgindent to format PostgreSQL files

    master

    pgindent is a tool used to format PostgreSQL files within the pgpool2 repository. It respects an exclude_files list to avoid touching specific files. To run the tool, you should execute the run_pgindent script from the src directory.

    Before running the formatter, you must ensure that the necessary type definitions and enums are included in typedefs.list.

    cd pgpool2/src
tools/pgindent/run_pgindent

  9. How to detach a standby node without killing client sessions

    master

    By default, a failover causes all existing client sessions to be killed because child processes are forced to restart. However, if you are operating in streaming replication mode and the node going down is a standby server, you can use pcp_detach_node to remove a node without disturbing all sessions.

    To ensure client sessions survive when detaching a node, the following conditions must be met:

    1. The node being detached is not the primary.
    2. The load balancing node currently assigned to the specific client session is not the node being detached.

    If the session's assigned load balancing node is the one being detached, the pgpool-II parent process will signal the child process to exit, killing the session. In a two-node setup (one primary, one standby) with equal weights, there is a 50% chance a session will survive.

  10. How to add a new configuration parameter

    master

    To add a new configuration parameter to Pgpool, you must follow a multi-step process involving defining an enum (if applicable), updating the core configuration structures, registering the variable in the configuration engine, and updating sample files and reporting utilities. This process ensures the new parameter is correctly typed, reloadable, and visible to users and monitoring tools.

    Follow the 7-step process:
1. Add enum definition in `src/include/pool_config.h`.
2. Add entry to `POOL_CONFIG` struct in `src/include/pool_config.h`.
3. Add `config_enum_entry` array in `src/config/pool_config.c`.
4. Add entry to `ConfigureNamesEnum[]` in `src/config/pool_config.c`.
5. Update sample config files in `src/sample/pgpool.conf.sample*`.
6. Update reporting program in `src/utils/pool_process_reporting.c`.
7. Add documentation and tests.

  11. Generate minimal and standard parser files

    master

    To generate the grammar files used by Pgpool-II, run the make generate_parsers command from the Pgpool-II/src/parser directory. This process uses the gram_template.y file as a source to produce two distinct grammar files:

    1. gram_minimal.y: Used for the minimal parser.
    2. gram.y: Used for the standard parser.

    The generation process relies on the sunifdef utility. If sunifdef is in your system's standard path, the configure script will detect it automatically. If it is located in a non-standard directory, you must specify the path during the configuration step using the --with-sunifdef switch.

    # Navigate to the parser directory
cd Pgpool-II/src/parser

# Generate the grammar files
make generate_parsers

# If sunifdef is in a custom location, configure first:
./configure --with-sunifdef=/path/to/sunifdef_dir

  12. Install prerequisites for pgindent

    master

    Before using pgindent, ensure the following tools are installed and available in your PATH:

    1. pg_bsd_indent: This is a standardized version of FreeBSD's indent. Its source is located in src/tools/pg_bsd_indent.
    2. perltidy: Specifically version 20230309. Using other versions will cause inconsistent formatting.

    You can install the required perltidy version using cpan or cpanm:

    cpan SHANCOCK/Perl-Tidy-20230309.tar.gz
# OR
cpanm https://cpan.metacpan.org/authors/id/S/SH/SHANCOCK/Perl-Tidy-20230309.tar.gz
    cpan SHANCOCK/Perl-Tidy-20230309.tar.gz