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.
Top comments (0)