Welcome everyone to the tutorial Apache AGE source-code adding new functions guide

Introduction

Apache AGE, or simply AGE, is a graph extension for PostgreSQL that enables graph querying and processing capabilities, allowing you to create and manipulate graph data easily.

One of the critical functionalities of AGE is the ability to extend Postgres to add new features and functions. In this tutorial, I'll be demonstrating how to add new functions to the AGE source code by creating a sample "Hello, World!" function in the C language.

Preparing the Environment

Before we get started, make sure that you have the dependencies required for compiling the AGE source code. You can find them in the README.md file in the source code repository.

Creating a New Function

1- Create a new file named hello_world.c in the src/backend/commands/ directory of the AGE source code.
2- In the hello_world.c file, add the following code that defines the hello_world() function:

 #include "postgres.h"
 #include "fmgr.h"

 PG_FUNCTION_INFO_V1(hello_world);

 Datum
 hello_world(PG_FUNCTION_ARGS)
 {
     elog(INFO, "Hello, World!");
     static char *result = "Hello, World!";
     PG_RETURN_TEXT_P(cstring_to_text(result));

     PG_RETURN_VOID();
 }

This code defines a new function named hello_world() that writes "Hello, World!" to the PostgreSQL server's log.
3- Add the following lines to the Makefile in the src/backend/commands/ directory to include the hello_world.c file in the compilation process:
Makefile path is on the top directory of the cloned repository

#add the folloinwg line to the OBJS 
src/backend/commands/hello_world.o 

4- Add the signature to the age--1.2.0.sql at the end of the file

CREATE FUNCTION ag_catalog.hello_world()
RETURNS void
LANGUAGE c
AS 'MODULE_PATHNAME';

5- Run the make command in the top-level directory of the AGE source code to build the source code.

sudo make clean PG_CONFIG=/usr/local/pgsql/bin/pg_config
sudo make PG_CONFIG=/usr/local/pgsql/bin/pg_config
sudo make install PG_CONFIG=/usr/local/pgsql/bin/pg_config

6- Start the PostgreSQL server by running the pg_ctl command with the start argument:

pg_ctl -D /path/to/data/directory start

7- Connect to the PostgreSQL server using the psql command-line tool:

psql -d mydatabase

8- Call the hello_world() function using the following SQL command:

select * from ag_catalog.hello_world();

Congratulations! You have successfully added a new function to the AGE source code. You can now build upon this example and create more complex functions that can manipulate graph data.

You can drop the current extension to reload it to the postgres server through i.e. Make a fresh load to the modified age extension

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

After getting everything finished you need to make sure of having your regression tests added, you can check how to create your own regression tests there through the following blog also:

As well as making sure you have not affected any of the current functionality of AGE through running their regression tests: https://dev.to/rrrokhtar/how-to-add-new-regression-tests-on-age-source-code-1mki

This part was suggested by @humzakt that is a good to be added part after having your function installed, thanks to him.

make clean PG_CONFIG=$HOME/pg_14/bin/pg_config 

make PG_CONFIG=$HOME/pg_14/bin/pg_config 

make install PG_CONFIG=$HOME/pg_14/bin/pg_config 

make installcheck PG_CONFIG=$HOME/pg_14/bin/pg_config 

Conclusion

In this tutorial, you learned how to add new functions to the Apache AGE source code using the C language. By following the steps mentioned above, you can extend the features and functionality of AGE as per your requirements. With AGE, you can leverage the full power of PostgreSQL to manage and process graph data efficiently.

References & Resources

• https://github.com/apache/age
• https://age.apache.org/
• Sample PR: https://github.com/apache/age/pull/807