Issue Overview: –exe Argument Not Respected in Local sqlite3_rsync Operations

The sqlite3_rsync utility is designed to synchronize SQLite databases across systems, with support for specifying a custom executable name via the --exe parameter. However, when both the origin and replica databases are local (i.e., residing on the same machine), the --exe argument is not honored. Instead of using the user-provided executable name stored in the zExe variable, the tool defaults to using argv[0] (the name by which the program was invoked). This leads to incorrect command generation during synchronization, particularly in embedded or wrapped environments where the executable name differs from the default sqlite3_rsync.

For example, when invoking a custom binary such as pihole-FTL sqlite3_rsync --exe "pihole-FTL sqlite3_rsync", the tool constructs internal commands using argv[0] (which might resolve to a bare sqlite3_rsync string) rather than the value provided via --exe. This mismatch disrupts workflows where the tool is embedded within a larger binary or requires a specific invocation path. The root of the problem lies in the sqlite3-rsync.c source code, where the local replication logic hardcodes argv[0] instead of referencing the zExe variable that holds the --exe parameter’s value. Additionally, the help text for --exe inaccurately states that the parameter applies only to the remote side, further confusing users.

Possible Causes: Misaligned Parameter Handling and Documentation

Three primary factors contribute to this issue:

1. Hardcoded argv[0] in Local Replication Logic
   The code responsible for generating the command string for local replication explicitly uses argv[0] (the zeroth argument of the program invocation) to reference the executable. This bypasses the zExe variable, which is intended to store the user-specified executable name from --exe. The assumption here is that the local executable name is always derived from the invocation context, but this fails in scenarios where the program is embedded within a larger binary or aliased.

2. Inconsistent Initialization of zExe
   The zExe variable may not be properly initialized to handle local replication cases. If zExe is only populated when remote replication is detected (e.g., via SSH or network paths), it will remain unset for local operations. This leaves the code reliant on argv[0] as a fallback, even when --exe is explicitly provided by the user.

3. Misleading Documentation in Help Text
   The help text for --exe states that it specifies the name of the sqlite3_rsync program on the remote side, implying that the parameter is irrelevant for local operations. This creates ambiguity and discourages users from applying --exe in local replication scenarios, even though the parameter is necessary for correct behavior in embedded environments.

Troubleshooting Steps, Solutions & Fixes: Aligning Code and Documentation with Expected Behavior

Step 1: Modify Local Replication Logic to Use zExe

In sqlite3-rsync.c, locate the code block responsible for constructing the command string when both origin and replica are local. Replace the reference to argv[0] with zExe to ensure the user-provided executable name is used. For example:

/* Original code (incorrect) */
sqlite3_str *pStr = sqlite3_str_new(0);
append_escaped_arg(pStr, argv[0], 1);  // Uses argv[0]
append_escaped_arg(pStr, "--replica", 0);

/* Fixed code */
sqlite3_str *pStr = sqlite3_str_new(0);
append_escaped_arg(pStr, zExe, 1);     // Uses zExe
append_escaped_arg(pStr, "--replica", 0);

Step 2: Initialize zExe with argv[0] by Default

Ensure zExe is initialized to argv[0] at program startup, allowing the --exe parameter to override this default. This guarantees that zExe is always populated, whether the user provides --exe or not. Example initialization:

char *zExe = sqlite3_mprintf("%s", argv[0]);  // Default to argv[0]

// Later, parse command-line arguments...
if( find_arg("--exe", ...) ){
  zExe = value_from_arg;  // Override with user-provided value
}

Step 3: Update Help Text for Clarity

Revise the description of the --exe parameter in the help output to reflect its applicability to both local and remote operations. For example:

-  "  --exe PATH  Name of the sqlite3_rsync program on the remote side\n"
+  "  --exe PATH  Name of the sqlite3_rsync program (local and remote)\n"

Step 4: Test Local Replication with Custom --exe Values

After applying the code changes, verify the fix by running sqlite3_rsync with a custom --exe value and local databases. Use tools like strace (Linux) or dtruss (macOS) to trace system calls and confirm the correct executable name is invoked. Example test command:

./pihole-FTL sqlite3_rsync --exe "custom_rsync_wrapper" origin.db replica.db

Step 5: Address Edge Cases and Environment-Specific Quirks

• Embedded Binaries: If the sqlite3_rsync utility is part of a larger binary (e.g., pihole-FTL), ensure that the --exe parameter includes any necessary invocation prefixes (e.g., pihole-FTL sqlite3_rsync instead of just sqlite3_rsync).
• Spaces in Paths: Validate that the code handles spaces in executable paths correctly, using proper argument escaping in append_escaped_arg.
• Cross-Platform Consistency: Confirm that the fix behaves identically across operating systems, particularly where command-line parsing or process invocation differs (e.g., Windows vs. Unix-like systems).

By systematically addressing the code’s assumptions about argv[0], ensuring consistent initialization of zExe, and clarifying documentation, users can leverage the --exe parameter reliably in both local and remote replication scenarios.