How to Create an PostgreSQL Extension

转自：https://severalnines.com/blog/creating-new-modules-using-postgresql-create-extension

Extensibility is one of the most powerful feature in PostgreSQL. You can add new functionality for a particular use case by using contrib module and install it using CREATE EXTENSION.

In this section, we are going to learn how to create a simple contrib module and how to use its functionality in PostgreSQL.

Extension Files

To be able to run the CREATE EXTENSION command in your database, your extension must need at least two files:

1. Control file
   The file format must be extension_name.control, which tells the basics about extension to PostgreSQL, and must be placed in the installation’s SHAREDIR/extension directory.
2. SQL script file
   The file in the format extension--version.sql contains the functions that you would like to add.

The file format of the control file in the extension is same as postgresql.conf file, namely a list of parameter_name = value assignments, one per line.

Example

Please check the below complete example of an SQL-only extension, create Oracle compatible NVL function in PostgreSQL. There are many cases but here we can consider only one case for example.

The SQL script file nvlfunc--1.0.sql looks like this...

Nvlfunc--1.0.sql file:

1 2 3 4 5 6 7

--complain if script is sourced in psql, rather than via CREATE EXTENSION echo Use "CREATE EXTENSION nvlfunc" to load this file. quit   CREATE OR REPLACE FUNCTION public.NVL(SMALLINT,SMALLINT) RETURNS SMALLINT AS $$ SELECT COALESCE($1,$2); $$ LANGUAGE SQL IMMUTABLE;

The control file nvlfunc looks like this...

Nvlfunc.conntrol file:

1 2 3 4 5

# nvlfunc extension comment = 'Oracle compatible nvl function' default_version = '1.0' module_pathname = '$libdir/nvlfunc' relocatable = false

While you hardly need a makefile to install these files into the correct directory, you could use a Makefile containing this:

Makefile:

1 2 3 4 5 6

EXTENSION = nvlfunc DATA = nvlfunc--1.0.sql   PG_CONFIG = pg_config PGXS := $(shell $(PG_CONFIG) --pgxs) include $(PGXS)

If you have implemented the function using ‘C’ language then you need to add the file in the makefile.

Installation

The command make install will install the control file and sql script file into the correct directory as reported by pg_config.

Once the files are installed, use the CREATE EXTENSION command to load the objects into any particular database in PostgreSQL.

Please check the following steps to install the nvlfunc extension and you can also add this file in your extension directory:

INSTALL.nvlfunc file:

1 2 3 4 5 6 7 8 9 10 11 12

This module is a PostgreSQL extension which provides the Oracle compatible nvl function feature. Use below command in source directory of nvlfunc to install the module. make install Then use the below command to create extension nvlfunc in database. CREATE EXTENSION nvlfunc; Use the below command to remove the nvlfunc extension from database. DROP EXTENSION nvlfunc; Use below command in source directory of nvlfunc to uninstall the module. make uninstall Note: This extension module requires PostgreSQL 9.1 or later because CREATE EXTENSION feature is available in PostgreSQL 9.1 and later version.

PostgreSQL extensions must be installed in your database before you can use their functionality. To install a particular extension, run the CREATE EXTENSION command from psql to load the packaged objects into the database.

Download the Whitepaper

Testing

Once you create the extension, it is recommended to create a test case for that extension so that when you are installing this module in a different PostgreSQL version, you can then check whether all the test cases are working as expected or not.

This is an optional step but you can create it. The test cases look like this:

sql/nvlfunc.sql file:

1	SELECT NVL(NULL::SMALLINT, 11::SMALLINT);

Then you can add expected output in another file. The expected output file looks like this:

expected/nvlfunc.out file:

1 2 3 4 5

SELECT NVL(NULL::SMALLINT, 11::SMALLINT);  nvl -----   11 (1 row)

This is just one example, that’s why only one test case is added. But when you are creating a new extension, you can add more test cases.

Nvlfunc extension directory structure:

1 2 3 4

# mkdir nvlfunc # cd nvlfunc # ls Makefile         nvlfunc.control    nvlfunc--1.0.sql    sql     expected    INSTALL.nvlfunc    README

Related resources

 ClusterControl for PostgreSQL

 Become a PostgreSQL DBA: Understanding the Architecture

 Tips & Tricks for Navigating the PostgreSQL Community

Pros

1. Easy to extend the PostgreSQL functionality
2. Very easy to create and install the extension
3. Easy to test for regressions on different versions of PostgreSQL

Cons

1. There is no special cons but test the feature you are adding in the extension before you use it.