PL/v8

PL/v8 is a trusted procedural language that is safe to use, fast to run and easy to develop, powered by V8 JavaScript Engine. The PL/v8 project is maintained at https://github.com/plv8/plv8.

Table of Contents

The documentation covers the following implemented features:

Requirements:

PL/v8 is tested with:

  • PG: version 9.2, 9.3, 9.4 and 9.5 (maybe older/newer are allowed)
  • V8: version 4.4 to 5.4
  • g++: version 4.8.2
  • clang++

Also all tools that PostgreSQL and V8 require to be built are required if you are building those from source.

Installing PL/v8

Build from source:

Determine the PL/v8 release you want to download and use it's version and path below.

$ wget https://github.com/plv8/plv8/archive/v2.0.0.tar.gz $ tar -xvzf v2.0.0.tar.gz $ cd plv8-2.0.0 $ make static

This will build PL/v8 for you linking to Google's v8 as a static library by downloading the v8 source at a specific version and building it along with PL/v8. The build will be for the highest PostgreSQL version you have installed on the system. You can alternatively run just make and it will build PL/v8 dynamically linking to Google's libv8 library on your system. There are some issues with this as several linux distros ship a very old version of libv8. The 3.x versions of v8 will work with the 1.4.x versions of PL/v8, but to build the later versions of PL/v8 you need a v8 minimum version of 4.4.63.31, but can also use v8 version 5.1.281.14. PGXN install will use the dynamically linked libv8 library.

If you would like to use make and your system does not have a new enough version of libv8 installed, see the .travis.yml file in the repo to see how our CI test servers build v8 natively.

Note: If you have multiple versions of PostgreSQL installed like 9.5 and 9.6, PL/v8 will only be built for PostgreSQL 9.6. This is because make static calls pg_config to get the version number, which will always be the latest version installed. If you need to build PL/v8 for PostgreSQL 9.5 while you have 9.6 installed pass make the PG_CONFIG variable to your 9.5 version of pg_config. This works for make, make static, make install. For example in Ubuntu:

$ make PG_CONFIG=/usr/lib/postgresql/9.5/bin/pg_config

Note: You may run into problems with your C++ complier version. You can pass make the CUSTOM_CC variable to change the complier. For example, to use g++ version 4.9:

$ make CUSTOM_CC g++-4.9

Note: In mingw64, you may have difficulty in building PL/v8. If so, try to make the following changes in Makefile. For more detail, please refer to https://github.com/plv8/plv8/issues/29

CUSTOM_CC = gcc SHLIB_LINK := $(SHLIB_LINK) -lv8 -Wl,-Bstatic -lstdc++ -Wl,-Bdynamic -lm

Installing the build:

After running make or make static the following files must be copied to the correct location for PostgreSQL to find them:

PL/v8 JavaScript Extension:

  • plv8.so
  • plv8.control
  • plv8--{plv8-build-version-here}.sql

The following files will also be built and can be optionally installed if you need the CoffeeScript or LiveScript versions:

CoffeeScript Extension:

  • plcoffee.control
  • plcoffee--{plv8-build-version-here}.sql

LiveScript Extension:

  • plls.control
  • plls--{plv8-build-version-here}.sql

Automatically Install the Build

You can install the build for your system by running:

$ make install

Note: You should do this a root/admin. sudo make install

Note: If you need to install PL/v8 for a different version of PostgreSQL, pass the PG_CONFIG variable. See above.

Test the Install

PL/v8 supports installcheck test. Make sure to set custom_variable_classes = 'plv8' in your postgresql.conf (before 9.2) and run:

$ make installcheck

Debian/Ubuntu 14.04 and 16.04:

You can install PL/v8 using apt-get, but it will be version v1.4.8 (As of 2016-12-16).

``` $ apt-get install postgresql-{your-postgresql-version-here}-plv8

e.g.

$ apt-get install postgresql-9.1-plv8

OR up to

$ apt-get install postgresql-9.6-plv8 ```

Redhat/CentOS:

TODO - PL/v8 supports Redhat/CentOS. A Pull Request for installation steps is greatly appreciated.

MacOS:

$ brew install plv8

Windows:

TODO - PL/v8 supports Windows. A Pull Request for installation steps is greatly appreciated

Install the PL/v8 Extensions on a Database:

Once the PL/v8 extensions have been added to the server, you should restart the PostgreSQL service. Then you can connect to the server and install the extensions on a database by running the following SQL queries on PostgreSQL version 9.1 or later:

CREATE EXTENSION plv8; CREATE EXTENSION plls; CREATE EXTENSION plcoffee;

Make sure to set custom_variable_classes = 'plv8' in your postgresql.conf file for PostgreSQL versions before 9.2.

In the versions prior to 9.1 run the following to create database objects:

$ psql -f plv8.sql

Testing PL/v8 on a database:

Below are some example queries to test if the extension is working:

DO $$ plv8.elog(WARNING, 'plv8.version = ' + plv8.version); // Will output the PL/v8 installed as a PostgreSQL `WARNING`. $$ LANGUAGE plv8;

As of 2.0.0, there is a function to determine which version of PL/v8 you have installed:

SELECT plv8_version();

JavaScript Example

``` CREATE OR REPLACE FUNCTION plv8_test(keys text[], vals text[]) RETURNS text AS $$ var o = {}; for(var i=0; i