How to Debug Apache AGE Source Code Using Apache Netbeans IDE
Tags: apacheage, development, c, netbeans
Published: 2023-07-22 01:57:43

In the [previous post](https://dev.to/carlasanches/how-to-configure-apache-age-and-postgresql-for-debugging-in-apache-netbeans-ide-2i84), 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:

```bash
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.

<aside>
❗ 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:
</aside>

<figure>
  <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9it3ozufv6y2r4lqwl80.png"
  alt="Figure 1 - “File is not an executable” issue.">
  <figcaption>Figure 1 - “File is not an executable” issue.</figcaption>
</figure>

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:

```sql
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:

```sql
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>
  <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gtpogm9y62p92jp61lrl.png"
  alt="Figure 2 - Attach Debugger window.">
  <figcaption>Figure 2 - Attach Debugger window.</figcaption>
</figure>

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**.

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

<figure>
  <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zkfdbwgdoyhir92f55ln.png"
  alt="Figure 3 - Ptrace “Operation not permitted” error.">
  <figcaption>Figure 3 - Ptrace “Operation not permitted” error.</figcaption>
</figure>

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:

```bash
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:

```bash
kernel.yama.ptrace_scope = 1
```

to

```bash
kernel.yama.ptrace_scope = 0
```

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

<figure>
  <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y07ql919dsw8quvzzg8l.png"
  alt="Figure 4 - Netbeans Debug sessions.">
  <figcaption>Figure 4 - Netbeans Debug sessions.</figcaption>
</figure>

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>
  <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rswkd5kk58cyly1jepjf.png"
  alt="Figure 5 - Breakpoint example.">
  <figcaption>Figure 5 - Breakpoint example.</figcaption>
</figure>

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

```sql
SELECT * FROM create_graph('graph_name');
```

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

<figure>
  <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6xhoo33iijsm3uf65hwy.png"
  alt="Figure 6 - Debug stopped at a breakpoint at graph_commands.c file, line 69.">
  <figcaption>Figure 6 - Debug stopped at a breakpoint at graph_commands.c file, line 69.</figcaption>
</figure>

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>
  <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ioc92avuuannrfzge46i.gif"
  alt="Figure 7 - Debug “Step Over” navigation.">
  <figcaption>Figure 7 - Debug “Step Over” navigation.</figcaption>
</figure>

<figure>
  <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mgw44lo06azs1yd062tq.png"
  alt="Figure 9 - Debug navigation buttons.">
  <figcaption>Figure 9 - Debug navigation buttons.</figcaption>
</figure>

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

<figure>
  <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hbn2ylqu2qohkxg0l6et.gif"
  alt="Figure 10 - Proceeding with program execution.">
  <figcaption>Figure 10 - Proceeding with program execution.</figcaption>
</figure>

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