pgzstd

Introduction

pgzstd is a PostgreSQL extension that provides functions for compressing and uncompressing Zstandard frames, with support for custom dictionaries.

Prerequisites

• PostgreSQL headers, libraries and PGXS build infrastructure
• pg_config must be in your PATH
• Zstandard

Building

Run make to build the extension.

Installation

Run make install as root (e.g. with sudo) to install the extension.

Debian package

The repository also contains the files for building a Debian package, which can be done by running pg_buildext updatecontrol followed by dpkg-buildpackage. I distribute pre-built versions for stable amd64 Debian using the apt.postgresql.org repository in my personal APT repository. Run apt-get install postgresql-PGVERSION-zstd as root after setting up the repository.

Usage

Run CREATE EXTENSION zstd to install the extension in the current database. Three functions are provided:

Function	Return Type
zstd_compress(data bytea [, dictionary bytea [, level integer ]])	bytea
zstd_decompress(data bytea [, dictionary bytea ])	bytea
zstd_length(data bytea)	integer

zstd_compress compresses the provided data and returns a Zstandard frame. A preset dictionary may also be provided. The default compression level may also be overriden, valid values range from 1 (best speed) to 22 (best compression). The default level is 3.

If you want to override the compression level without using a dictionary, set dictionary to NULL.

zstd_decompress decompresses the provided Zstandard frame in data and returns the uncompressed data. A preset dictionary, matching the dictionary used to compress the data, may also be provided.

zstd_length returns the decompressed length of the provided Zstandard frame. If ZSTD_getFrameContentSize() is available it returns NULL if the length is unknown. If unavailable, it isn't possible to distinguish the error, unknown decompressed length and zero decompressed length cases.

Example

gpe=# CREATE EXTENSION zstd;
CREATE EXTENSION
gpe=# SELECT zstd_compress('hello hello hello hello', 'hello hello', 3);
            zstd_compress
--------------------------------------
 \x28b52ffd2017450000000200291c6c1420
(1 row)

gpe=# SELECT convert_from(zstd_decompress('\x28b52ffd2017450000000200291c6c1420', 'hello hello'), 'utf-8');
      convert_from
-------------------------
 hello hello hello hello
(1 row)

gpe=# SELECT zstd_length('\x28b52ffd2017450000000200291c6c1420');
 zstd_length
-------------
          23
(1 row)

gpe=#

License

This project is available under the terms of the ISC license, which is similar to the 2-clause BSD license. See the LICENSE file for the copyright information and licensing terms.