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
- Installing PL/v8
- Install the PL/v8 Extensions on a Database
- Scalar function calls
- Set returing function calls
- Trigger function calls
- Inline statement calls
- Auto mapping between JS and database built-in types
- Database access via SPI including prepared statements and cursors
- Subtransaction
- Utility functions
- Window function API
- Typed array
- ES6 Language Features
- Runtime environment separation across users in the same session
- Start-up procedure
- Update procedure
- Dialects
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
callspg_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 passmake
thePG_CONFIG
variable to your 9.5 version ofpg_config
. This works formake
,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
theCUSTOM_CC
variable to change the complier. For example, to useg++
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