Installation and Configuration

Installation

Getting Veil

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

The latest development version can also be retrieved from the cvs repository using the following commands. When prompted for a password for anonymous, simply press the Enter key.

cvs -d :pserver:anonymous@cvs.pgfoundry.org:/cvsroot/veil login
cvs -d :pserver:anonymous@cvs.pgfoundry.org:/cvsroot/veil checkout veil

Pre-requisites

You must have a copy of the Postgresql header files available in order to build Veil. This will probably mean that you need a full Postgres source tree available.

Building Veil

Unpack the tarball. Configure Veil for your platform using configure. Use the --help option to configure for more information. You will probably have to manually specify the path for your postgresql source tree using --with-pgincludedir=<path>.

Build the veil shared library, and possibly documents, using make or make all.

$ tar xvzf veil-<VERSION>tar.gz
. . .
$ ./configure
. . .
$ make all

Installing Veil

As the postgres, pgsql, or root user, run make install.
make install
If you are running Veil version 0.9.2 or greater against Postgres version 8.2 or greater, you should update postgresql.conf to define shared_preload_libraries to reference the installed version of veil.so Running "make install" will prompt you to do this. For more information on Veil's cooperation with Postgres see Configuration.

Two files are installed by the install target, the veil.so shared library, and the veil_interface.sql SQL script which creates the veil functions using the shared library. Docs may also be installed depending upon the options you specified to configure.

The shared library itself is installed in $pgpkglibdir, and the sql script in $pgsharedir, both as identified by configure.

Build Notes

The Veil makefile tries to be helpful. Use "make help" or "make list" for a list of the targets that make knows how to build.

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.

Regression Tests

Veil comes with a built-in regression test suite. Use "make regress" 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.

The Veil regression tests automatically use the veil_trial.so shared library if appropriate (based upon veil and postgres versions and whether veil.so is configured as a shared_preload_library (Configuration).

Demo Database

As with the regression tests, you will need to be a privileged database user to be able to create the demo database. For more on installing the demo database see Installing the Veil demo.

Configuration

From version 0.9.2 of Veil and version 8.2 of Postgres, Veil cooperates with Postgres over its shared memory usage. A non-cooperating version of Veil is also built (Trial Version), which may be used to try out Veil if you are in a situation where you cannot modify postgresql.conf or restart the Postgres server.

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

shared_preload_libraries = '<path to shared library>/veil.so' 

custom_variable_classes = 'veil'

#veil.dbs_in_cluster = 1
#veil.shared_hash_elems = 32
#veil.shmem_context_size = 16384

The three configuration options, commented out above, are:

Trial Version

From version 0.9.2 of Veil and version 8.2 of Postgres the veil.so shared library cooperates with the Postgres server over the reservation and allocation of shared memory. This requires that the postgresql.conf file be modified as described in (Configuration) and that postgres be stopped and restarted.

A trial version of the veil shared library, veil_trial.so is automatically created when veil is built. This version of the shared library does not require modifications to postgresql.conf and does not require the database to be restarted. Note that the veil regression tests will be run in this mode if postgres has not been configured for Veil.

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 new feature and not yet fully formed but is worth trying if Veil appears to be misbehaving. If any of the debug code encounters a problem, ERRORs will be raised.

Next: History and Compatibility


Generated on Fri Mar 12 08:38:47 2010 for Veil by  doxygen 1.5.6