What Is plv8?
V8 is a JavaScript engine written by Google. plv8, sometimes written as "PL/v8", is a Procedural Language wrapper around V8 that lets you write PostgreSQL stored procedures in JavaScript.
Why Do We Need It?
xTuple has been busy the past few years: We've written an ERP client application that runs in browsers and a REST API, as well as continuing work on our desktop client application. The web client, REST API, and many extensions to our desktop client are written in JavaScript. We can use existing code as we add cross-client compatibility and new features to one or the other of these clients - but we need a consistent database platform to do this. This platform includes plv8.
Installing plv8
If you're already running xTuple's mobile-web client or e-Commerce solutions, the hard part is already done - plv8 is already installed and you've been using it this whole time. The same is true if you set up your database server with the xtuple-admin-utility.
People who are upgrading to xTuple ERP version 4.9.0 from older, non-mobilized xTuple ERP instances will need to install plv8 on their server before they can complete the upgrade to 4.9.0. Do-it-yourselfers can build plv8 from source. Alternatively, xTuple has bundled up versions for Mac, Linux, and Windows servers. See below for information about how to download a plv8 bundle for your operating system.
Note that you only need plv8 on your database server. It's part of the server infrastructure. You don't need to change your client machines.
On All Platforms
Make sure the postgresql.conf file in your database server's data directory contains the following lines if you're running PostgreSQL 9.1 on Mac or Linux (NOTE: PostgreSQL 9.1 is not currently supported on Windows):
custom_variable_classes = 'plv8'
plv8.start_proc = 'xt.js_init'
If you are running PostgreSQL 9.2.0 and later, only include the following line:
plv8.start_proc = 'xt.js_init'
You can put those lines anywhere in the postgresql.conf file you want but it's safest to put them at the end. If there's already a custom_variable_classes line with something between the single-quotes, add ,plv8 to the line inside the quotes. You can check if plv8.start_proc is there already by querying the database server in psql or pgAdmin:
psql> show plv8.start_proc;
PLEASE NOTE: After following the steps described below for your operating system, you will need to connect to each database you plan to update and issue the following, which tells the database to allow use of plv8:
psql dbname> create extension if not exists plv8;
TIP: If you apply the above command to your template1 database, then any new databases you create from template1 will automatically inherit the plv8 extension.
Mac Servers
Perform the following steps on your Mac server:
- Download our Mac plv8 bundle from
https://xtuple-plv8.s3.amazonaws.com/mac/xtuple_plv8.tgz - Copy this to the server Desktop
- Find the folder where PostgreSQL is installed. This should have sub-folders named bin, lib, shared, etc. Write down the full directory path, which looks something like /usr/local/postgres/9.2.4 or /Library/PostgreSQL/9.3.
- Open a Terminal window on your Mac
- Type the following ($ is the shell prompt - don't type that part):
$ cd Desktop
$ tar xf xtuple_plv8.tgz # if "xtuple_plv8.tgz" doesn't exist, try "xtuple_plv8.tar"
$ cd xtuple_plv8
$ sudo ./install_plv8.sh
- Enter your password when install_plv8.sh asks
- Enter the full path to the PostgreSQL installation directory when install_plv8.sh asks. If you make a mistake, it'll just ask again. Type Control-C to quit if you can't remember the full path.
install_plv8.sh will run for another second or two and you'll get a shell prompt back.
Now create the extension as described above. When you upgrade to xTuple ERP 4.9.0, the upgrade script should detect that plv8 can be used and the upgrade should go smoothly.
Windows Servers (using MSVC)
Perform the following steps on your Windows server:
- Install the appropriate 64bit or 32bit version of Microsoft Visual C++ 2015 runtime
- Download our Windows plv8 bundle
- Extract this archive to the server Desktop
- Find the folder where PostgreSQL is installed. This should have sub-folders named bin, lib, shared, etc. Write down the full directory path, which looks something like C:\Program Files\PostgreSQL\9.3 for 64bit or C:\Program Files (x86)\PostgreSQL\9.3 for 32bit.
- Open an Administrator command prompt on your Windows Server.
- Typically, Start > All Programs > Accessories > Right click on command prompt and "Run as Administrator"
- Alternatively, search for "Command Prompt", when it appears in the search results right click and "Run as Administrator"
- Type the following (> is the shell prompt - don't type that part):
> cd %HOMEPATH%\Desktop\xtuple_plv8
> install_plv8.bat
- Choose what version of PostgreSQL that you are running
- Enter the full path to the PostgreSQL installation directory when install_plv8.bat asks. If you make a mistake, it'll just ask again. Type Control-C to quit if you can't remember the full path.
install_plv8.bat will run for another second or two and you'll get a shell prompt back.
Now create the extension as described above. When you upgrade to xTuple ERP 4.9.0, the upgrade script should detect that plv8 can be used and the upgrade should go smoothly.
Linux Servers
Perform the following steps on your Linux server:
-
Download our Linux PL/v8 bundle
-
Open a Terminal window on your Linux server
-
Install additional dependencies
Ubuntu:
- Type the following ($ is the shell prompt - don't type that part):
$ sudo apt-get install libc++1
- Find the folder where PostgreSQL is installed. This should have sub-folders named bin and lib. Write down the full directory path, which looks something like /usr/lib/postgresql/9.6 or /Library/PostgreSQL/9.6.
$ pg_config --pkglibdir
- Un-tar file and install PLv8
$ cd directory-where-you-downloaded-file
$ tar xf xtuple_plv8.tgz # if "xtuple_plv8.tgz" doesn't exist, try "xtuple_plv8.tar"
$ cd xtuple_plv8
$ sudo ./install_plv8.sh
- Enter your password when install_plv8.sh asks
- Enter the full path to the PostgreSQL installation directory when install_plv8.sh asks as noted above. e.g. /usr/lib/postgresql/9.6 If you make a mistake, it'll just ask again. Type Ctrl+C to quit if you can't remember the full path.
install_plv8.sh will run for another second or two and you'll get a shell prompt back.
Now create the extension as described above.
Check your PLV8 Version
DO $$
plv8.elog(WARNING, 'plv8.version = ' + plv8.version); // Will output the PL/v8 installed as a PostgreSQL `WARNING`.
$$ LANGUAGE plv8;