Navigation :

INSTALL

INSTALL

The installation process is composed of 4 basic steps:

  • Step 1: Deploy the extension into the host server
  • Step 2: Load the extension in the PostgreSQL instance
  • Step 3: Create the extension inside the database
  • Step 4: Initialize the extension internal data

There are multiple ways to install the extension :

In the examples below, we load the extension (step2) using a parameter called session_preload_libraries but there are other ways to load it. See Load the extension for more details.

If you’re having any problem, check the Troubleshooting section.

Choose your version : Stable or Latest ?

This extension is available in two versions :

  • stable is recommended for production
  • latest is useful if you want to test new features

Install on RedHat / CentOS

This is the recommended way to install the stable extension This method works for RHEL/CentOS 7 and 8. If you’re running RHEL/CentOS 6, consider upgrading or read the Install With PGXN section.

Step 0: Add the PostgreSQL Official RPM Repo to your system. It should be something like:

sudo yum install https://.../pgdg-redhat-repo-latest.noarch.rpm

Step 1: Deploy

sudo yum install postgresql_anonymizer_14

(Replace 14 with the major version of your PostgreSQL instance.)

Step 2: Load the extension.

ALTER DATABASE foo SET session_preload_libraries = 'anon';

(If you already loading extensions that way, just add anon the current list)

Step 3: Create the extension and load the anonymization data

CREATE EXTENSION anon CASCADE;

Step 4: Initialize the extension

SELECT anon.init();

All new connections to the database can now use the extension.

Install With PGXN :

This method will install the stable extension

Step 1: Deploy the extension into the host server with:

sudo apt install pgxnclient postgresql-server-dev-12
sudo pgxn install postgresql_anonymizer

(Replace 12 with the major version of your PostgreSQL instance.)

Step 2: Load the extension.

ALTER DATABASE foo SET session_preload_libraries = 'anon';

(If you already loading extensions that way, just add anon the current list)

Step 3: Create the extension

CREATE EXTENSION anon CASCADE;

Step 4: Initialize the extension

SELECT anon.init();

All new connections to the database can now use the extension.

Additional notes:

  • PGXN can also be installed with pip install pgxn
  • If you have several versions of PostgreSQL installed on your system, you may have to point to the right version with the --pg_config parameter. See Issue #93 for more details.
  • Check out the pgxn install documentation for more information.

Install From source

This is the recommended way to install the latest extension

Step 0: First you need to install the postgresql development libraries. On most distributions, this is available through a package called postgresql-devel or postgresql-server-dev.

Step 1: Download the source from the official repository on Gitlab, either the archive of the latest release, or the latest version from the master branch:

git clone https://gitlab.com/dalibo/postgresql_anonymizer.git

Step 2: Build the project like any other PostgreSQL extension:

make extension
sudo make install

NOTE: If you have multiple versions of PostgreSQL on the server, you may need to specify which version is your target by defining the PG_CONFIG env variable like this:

make extension PG_CONFIG=/usr/lib/postgresql/14/bin/pg_config
sudo make install PG_CONFIG=/usr/lib/postgresql/14/bin/pg_config

Step 3: Load the extension:

ALTER DATABASE foo SET session_preload_libraries = 'anon';

(If some extensions are already loaded that way, just add a comma and anon to the current list.)

Step 4: Create the extension:

CREATE EXTENSION anon CASCADE;

Step 5: Initialize the extension:

SELECT anon.init();

All new connections to the database can now use the extension.

Install with Docker

If you can’t (or don’t want to) install the PostgreSQL Anonymizer extension directly inside your instance, then you can use the docker image :

docker pull registry.gitlab.com/dalibo/postgresql_anonymizer:stable

The image is available with 2 two tags:

  • latest (default) contains the current developments
  • stable is the based on the previous release

You can run the docker image like the regular postgres docker image.

For example:

Launch a postgres docker container

docker run -d -e POSTGRES_PASSWORD=x -p 6543:5432 registry.gitlab.com/dalibo/postgresql_anonymizer

then connect:

export PGPASSWORD=x
psql --host=localhost --port=6543 --user=postgres

The extension is already created and initialized, you can use it directly:

# SELECT anon.partial_email('daamien@gmail.com');
     partial_email
-----------------------
 da******@gm******.com
(1 row)

Note: The docker image is based on the latest PostgreSQL version and we do not plan to provide a docker image for each version of PostgreSQL. However you can build your own image based on the version you need like this:

PG_MAJOR_VERSION=11 make docker_image

Install as a “Black Box”

You can also treat the docker image as an “anonymizing black box” by using a specific entrypoint script called /anon.sh. You pass the original data and the masking rules to the /anon.sh script and it will return a anonymized dump.

Here’s an example in 4 steps:

Step 1: Dump your original data (for instance dump.sql)

pg_dump --format=plain [...] my_db > dump.sql

Note this method only works with plain sql format (-Fp). You cannot use the custom format (-Fc) and the directory format (-Fd) here.

If you want to maintain the owners and grants, you need export them with pg_dumpall --roles-only like this:

(pg_dumpall -Fp [...] --roles-only && pg_dump -Fp [...] my_db ) > dump.sql

Step 2: Write your masking rules in a separate file (for instance rules.sql)

SELECT pg_catalog.set_config('search_path', 'public', false);

CREATE EXTENSION anon CASCADE;
SELECT anon.init();

SECURITY LABEL FOR anon ON COLUMN people.lastname
IS 'MASKED WITH FUNCTION anon.fake_last_name()';

-- etc.

Step 3: Pass the dump and the rules through the docker image and receive an anonymized dump !

IMG=registry.gitlab.com/dalibo/postgresql_anonymizer
ANON="docker run --rm -i $IMG /anon.sh"
cat dump.sql rules.sql | $ANON > anon_dump.sql

(this last step is written on 3 lines for clarity)

NB: You can also gather step 1 and step 3 in a single command:

(pg_dumpall --roles-only && pg_dump my_db) | cat - rules.sql | $ANON > anon_dump.sql

Install on MacOS

WE DO NOT PROVIDE COMMUNITY SUPPORT FOR THIS EXTENSION ON MACOS SYSTEMS.

However it should be possible to build the extension with the following lines:

export C_INCLUDE_PATH="$(xcrun --show-sdk-path)/usr/include"
make extension
make install

Install on Windows

WE DO NOT PROVIDE COMMUNITY SUPPORT FOR THIS EXTENSION ON WINDOWS.

However it is possible to compile it using Visual Studio and the build.bat file.

We provide Windows binaries and install files as part of our commercial support.

Install in the cloud

WARNING In previous versions, this extension could be installed on various Database As A Service platforms (such as Amazon RDS). Starting with version 0.9, this is not possible anymore. We do not support the former standalone method. If privacy and anonymity are a concern to you, we encourage you to contact the customer services of these platforms and ask them if they plan to add this extension to their catalog.

At the time we are writing this (February 2022), a few cloud operators embed PostgreSQL Anonymizer in their offering. Here’s a non-exhaustive list:

Addendum: Alternative ways to load the extension

Here’s some additional notes about how you can load the extension:

1- Load only for one database

You can load the extension exclusively into a specific database like this:

ALTER DATABASE mydatabase SET session_preload_libraries='anon'

Then quit your current session and open a new one.

It has several benefits:

  • First, it will be dumped by pg_dump with the-C option, so the database dump will be self efficient.

  • Second, it is propagated to a standby instance by streaming replication. Which means you can use the anonymization functions on a read-only clone of the database (provided the extension is installed on the standby instance)

2- Load for the instance

You can load the extension with the shared_preload_libraries parameter.

ALTER SYSTEM SET shared_preload_libraries = 'anon'"

Then restart the PostgreSQL instance.

3- Load on the fly

For a one-time usage, You can the LOAD command

LOAD '/usr/lib/postgresql/12/lib/anon.so';

You can read the Shared Library Preloading section of the PostgreSQL documentation for more details.

Addendum: Troubleshooting

If you are having difficulties, you may have missed a step during the installation processes. Here’s a quick checklist to help you:

Check that the extension is present

First, let’s see if the extension was correctly deployed:

ls $(pg_config --sharedir)/extension/anon
ls $(pg_config --pkglibdir)/anon.so

If you get an error, the extension is probably not present on host server. Go back to step 1.

Check that the extension is loaded

Now connect to your database and look at the configuration with:

SHOW local_preload_libraries;
SHOW session_preload_libraries;
SHOW shared_preload_libraries;

If you don’t see anon in any of these parameters, go back to step 2.

Check that the extension is created

Again connect to your database and type:

SELECT * FROM pg_extension WHERE extname= 'anon';

If the result is empty, the extension is not declared in your database. Go back to step 3.

Check that the extension is initialized

Finally, look at the state of the extension:

SELECT anon.is_initialized();

If the result is not t, the extension data is not present. Go back to step 4.

Uninstall

Step 1: Remove all rules

SELECT anon.remove_masks_for_all_columns();
SELECT anon.remove_masks_for_all_roles();

THIS IS NOT MANDATORY ! It is possible to keep the masking rules inside the database schema even if the anon extension is removed !

Step 2: Drop the extension

DROP EXTENSION anon CASCADE;

Step 3: Unload the extension

ALTER DATABASE foo RESET session_preload_libraries;

Step 4: Uninstall the extension

For Redhat / CentOS / Rocky:

sudo yum remove postgresql_anonymizer_14

Replace 14 by the version of your postgresql instance.