Veil can be downloaded as a gzipped tarball from http://pgfoundry.org/projects/veil/
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.
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=&le.path>.
Build the veil shared library, and possibly documents, using make or make all.
$ tar xvzf veil-<VERSION>tar.gz
. . .
$ ./configure
. . .
$ make all
As the postgres, pgsql, or root user, run 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 $pglibdir, and the sql script in $pgsharedir, both as identified by configure.
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.
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).
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.
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:
- 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.
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.
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 Tue Mar 11 10:20:09 2008 for Veil by
1.5.4