Installation

Getting Veil

Veil can be downloaded as a gzipped tarball from http://pgfoundry.org/projects/veil/

Since version 9.1, git is no longer available from cvs on pgfoundry. Development has switched to using git. The primary git repository is git://github.com/marcmunro/veil.git

To checkout from git, create a suitable directory and do:

 git clone git://github.com/marcmunro/veil.git

Alternative repositories are also available:

 git clone git://bloodnok.com/veil

or

 git clone git@github.com:marcmunro/veil.git

Pre-requisites

You must have a copy of the Postgresql header files available in order to build Veil. For this, you may need to install the postgres developer packages for your OS, or even build postgres from source.

Building Veil

Veil is built using the postgresql extension building infastructure, PGXS. In order to be able to build using PGXS, the following command must return the location of the PGXS makefile:

$ pg_config --pgxs

You may need to modify your PATH variable to make pg_config usable, or ensure it is for the correct postgresql version.

To build the postgres extensions, simply run make with no target:

$ make

As part of figuring our the configuration, the makefile will attempt to work out which version of Postgres to build for. If it fails to figure this out, add PG_VERSION=<x.y> to the make command. eg:

$ make PG_VERSION="9.4"

To build the veil documentation (the documentation you are now reading) use:

$ make docs

Note that the build system deliberately avoids using make recursively. Search the Web for "Recursive Make Considered Harmful" for the reasons why. This makes the construction of the build system a little different from what you may be used to. This may or may not turn out to be a good thing. Feedback is welcomed.

Installing Veil

As the postgres, pgsql, or root user, run make install.

make install

Configuration

To configure Veil, the following lines should be added to your postgresql.conf:

shared_preload_libraries = '<path to shared library>/veil.so' 
#veil.dbs_in_cluster = 1
#veil.shared_hash_elems = 32
#veil.shmem_context_size = 16384

The three configuration options, commented out above, are:

dbs_in_cluster The number of databases, within the database cluster, that will use Veil. Each such database will be allocated 2 chunks of shared memory (of shmem_context_size), and a single LWLock. It defaults to 1.
shared_hash_elems This describes how large a hash table should be created for veil shared variables. It defaults to 32. If you have more than about 20 shared variables you may want to increase this to improve performance. This setting does not limit the number of variables that may be defined, it just limits how efficiently they may be accessed.
shmem_context_size This sets an upper limit on the amount of shared memory for a single Veil shared memory context (there will be two of these). It defaults to 16K. Increase this if you have many shared memory structures.

Regression Tests

Veil comes with a built-in regression test suite. Use make regress or make check (after installing and configuring Veil) to run this. You will need superuser access to Postgres in order to create the regression test database. The regression test assumes you will have a postgres superuser account named the same as your OS account. If pg_hba.conf disallows "trust"ed access locally, then you will need to provide a password for this account in your .pgpass file (see postgres documentation for details).

The regression tests are all contained within the regress directory and are run by the regress.sh shell script. Use the -h option to get fairly detailed help.

Debugging

If you encounter problems with Veil, you may want to try building with debug enabled. Define the variable VEIL_DEBUG on the make command line to add extra debug code to the executable:

$ make clean; make VEIL_DEBUG=1 all

This is a transient feature and not as pervasive as it could be. If you need help with debugging please contact the author.

Next: History and Compatibility