How to Debug Apache AGE Source Code Using Apache Netbeans IDE

In the previous post, I demonstrated how to configure Netbeans for debugging PostgreSQL and Apache AGE. Now, in continuation of that topic, I will explain how to set project preferences and perform the debugging process. So, if you have already configured the PostgreSQL and Apache AGE projects in Netbeans, you can follow the next steps.

First, we need to create a new database. In the terminal, choose the directory of your preference. Then, start a new PostgreSQL service with the following commands:

initdb agedb
pg_ctl -D path/to/agedb -l logfile start
createdb agedb

Let's now return to the Netbeans projects. Specifically for the AGE project, there's no need to make any alterations from the last tutorial. You can leave it as it was created previously. However, we need to configure some preferences in the IDE for PostgreSQL.

In your PostgreSQL project, right-click and choose Properties. A new window will pop up. Choose the category Debug to set up the command to debug the code. Fill Debug command with psql agedb. This will start the command line tool to work with Apache AGE. Next, fill Working dir with the path to psql. In the source code, the psql executable is located in /src/bin/psql. This is the path Netbeans will use to run the debug command.

❗ Troubleshooting Tip 1: Even if you don't intend to use the Run command, it's essential to set it up. This is a problem that I spent a couple of hours to figure out. Set the Run command as psql agedb and the Run directory the same as the Debug Working dir, with the path to psql. Otherwise, Netbeans will show the message below, and the IDE will not recognize psql as an executable:

Figure 1 - “File is not an executable” issue.

You can let the remaining fields as default, and now the setup is ready to Debug. Right-click your Netbeans PostgreSQL project and choose Debug. The psql CLI tool will start. Connect the database with the AGE extension with the following commands:

CREATE EXTENSION age;
LOAD 'age';
SET search_path = ag_catalog, "$user", public; 

The next step is to attach the debugger to the postgres process. Run select pg_backend_pid(); to find the process ID (pid). The terminal will return info similar to the following output:

pg_backend_pid 
----------------
          11587
(1 row)

Copy the number returned in the terminal and select Debug > Attach Debugger at the top toolbar. Paste the ID number in the Filter field. The system will return the postgres process info:

Figure 2 - Attach Debugger window.

For this tutorial, I left all the setups as default. The Debugger is Gdb Debugger, and the Host is localhost. I recommend not choosing a project because Netbeans will ask for the executable file, and you will face the same problem as Figure 2. So, select the postgres process and click OK.

❗ Troubleshoot Tip 2: You may face a debugger error when attaching the debugger to the postgres process, as illustrated by Figure 3.

Figure 3 - Ptrace “Operation not permitted” error.

The PostgreSQL Wiki says it may be due to Ubuntu introducing a patch to disallow the ptracing of non-child processes by non-root users. ⚠️ Warning: you can disable this restriction, but this is not recommended since this can cause vulnerabilities to the system. Do it at your own risk. I will update this post when I find a better solution for PostgreSQL. See the following thread to learn more: https://askubuntu.com/a/153970.

To temporarily disable the restriction, run:

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Note that it is necessary to run this command every time you start a new terminal session. While you can permanently allow it, this is not recommended. Edit /etc/sysctl.d/10-ptrace.conf and change the line:

kernel.yama.ptrace_scope = 1

to

kernel.yama.ptrace_scope = 0

Now, try to attach the postgres process again. If everything works, Netbeans will show this status:

Figure 4 - Netbeans Debug sessions.

To begin debugging, create a breakpoint on a line within the function you want to analyze. Afterward, call it via psql CLI. For instance, let's examine the create_graph() function, defined in age/src/backend/commands/graph_commands.c. The function header is Datum create_graph(PG_FUNCTION_ARGS). In Figure 5, I have added a breakpoint in the first function call:

Figure 5 - Breakpoint example.

In the CLI, call the create_graph() function using the following command:

SELECT * FROM create_graph('graph_name');

You can see that the Debug will stop at/close to the breakpoint:

Figure 6 - Debug stopped at a breakpoint at graph_commands.c file, line 69.

You can navigate through Debug buttons at the top (Step Over (F8), Step Into (F7), Step Out (Ctrl+F7), and Run to Cursor (F4)) to examine each line and see the variables at the Variables tab at the bottom:

Figure 7 - Debug “Step Over” navigation.

Figure 9 - Debug navigation buttons.

And when you are done with debugging the function, you can click Continue (F5) to proceed with the execution:

Figure 10 - Proceeding with program execution.

You can finish the Debugger session by clicking the red square button at the debug tools or pressing Shift+F5. Remember to run \q to quit the psql CLI.

And that’s it! This was a simple tutorial on how to Debug Apache AGE functions via Netbeans IDE. I hope you liked it and hope this can make the Debug process easier.

References

Ask Ubuntu. “What is the 'ptrace_scope' workaround for Wine programs and are there any risks?.” 2012. Available at https://askubuntu.com/q/146160. Accessed on 07/20/2023.

The PostgreSQL Wiki. Working with Eclipse. Available at https://wiki.postgresql.org/wiki/Working_with_Eclipse. Accessed on 07/20/2023.

Contribute to Apache AGE

Apache AGE website: https://age.apache.org/
Apache AGE Github: https://github.com/apache/age