How to Fetch Different Kinds of Arguments in Apache AGE C-Language Functions

Creating a PostgreSQL extension in C, like Apache AGE, allows you to execute high-performance code directly in your database. One of the challenges is passing arguments to these C functions. Here's a simple guide to fetch different kinds of arguments in a C-language function of a PostgreSQL extension.

Before we start, make sure to include necessary PostgreSQL headers in your C file:

#include "postgres.h"
#include "fmgr.h"
#include "utils/builtins.h"

PostgreSQL provides the fmgr (Function Manager) module that includes macros for dealing with arguments.

Handling Scalar Arguments

For scalar arguments like integers or floats, use the PG_GETARG_ macros:

PG_FUNCTION_INFO_V1(add_integers);

Datum
add_integers(PG_FUNCTION_ARGS)
{
    int32 arg1 = PG_GETARG_INT32(0);  // Fetches the first argument
    int32 arg2 = PG_GETARG_INT32(1);  // Fetches the second argument

    PG_RETURN_INT32(arg1 + arg2);
}

Handling String Arguments

For text arguments, use the PG_GETARG_TEXT_P macro:

PG_FUNCTION_INFO_V1(echo_text);

Datum
echo_text(PG_FUNCTION_ARGS)
{
    text *arg1 = PG_GETARG_TEXT_P(0);
    char *cstr = text_to_cstring(arg1);

    PG_RETURN_TEXT_P(cstring_to_text(cstr));
}

Handling Array Arguments

For arrays, use the PG_GETARG_ARRAYTYPE_P macro:

PG_FUNCTION_INFO_V1(process_array);

Datum
process_array(PG_FUNCTION_ARGS)
{
    ArrayType *array = PG_GETARG_ARRAYTYPE_P(0);
    // Further processing...
}

Handling NULL Arguments

You can check if an argument is NULL using PG_ARGISNULL(index) macro:

PG_FUNCTION_INFO_V1(echo_or_default);

Datum
echo_or_default(PG_FUNCTION_ARGS)
{
    if (PG_ARGISNULL(0))
        PG_RETURN_TEXT_P(cstring_to_text("default"));
    else
    {
        text *arg1 = PG_GETARG_TEXT_P(0);
        char *cstr = text_to_cstring(arg1);

        PG_RETURN_TEXT_P(cstring_to_text(cstr));
    }
}

Concluding Remarks

This is a basic guide to fetching arguments in PostgreSQL C functions. Depending on the argument's type, you will need to use the appropriate PG_GETARG_ macros. Remember to consider NULL arguments as well. By mastering these techniques, you'll be able to harness the full power of PostgreSQL C-language functions.

Keep in mind that PostgreSQL's C API is vast and provides many more capabilities for dealing with complex data types, sets, and even triggering side effects on your database. Make sure to explore the official PostgreSQL documentation for a more comprehensive understanding.

Note: C-language functions can offer significant performance advantages but come with risks, especially around memory management. Be sure to thoroughly test any C functions you write for your PostgreSQL database.

---

I make these posts in order to guide people into the development of a new technology. If you find anything incorrect, I urge you to comment below so I can fix it. Thanks!

---

Check Apache AGE: https://age.apache.org/.

Overview — Apache AGE master documentation: https://age.apache.org/age-manual/master/intro/overview.html.

GitHub - apache/age: https://github.com/apache/age