Veil generally requires no management. The exception to this is when you wish to reset shared variables. You may wish to do this because your underlying security definitions have changed, or because you have added new features. In this case, you may use veil_perform_reset() to re-initialise your shared variables. This function replaces the current set of shared variables with a new set in a transaction-safe manner. All current transactions will complete with the old set of variables in place. All subsequent transactions will see the new set.

The following functions comprise the Veil control functions API:

registered initialisation functions

A registered initialisation function is one which will be called from the standard veil veil_init(doing_reset bool) function. Such functions are responsible for defining and, usually, initialising shared variables.

Initialisation functions may be written in any language supported by PostgreSQL, and must conform to the following function prototype:

function init_function(doing_reset bool) returns bool

The doing_reset parameter will be set to true if we are completely resetting veil and redefining all of its variables. In this case, we must declare and, probably, initialise shared variables prior to any session initialisation actions. The parameter will be false, if the function is solely being called to initialise a new session. Check The Veil Demo Application for an example.

Initialisation functions are registered by inserting their name into the configuration table veil.veil_init_fns. The functions listed in this table are executed in order of the priority column. Eg, to register veil.init_roles() to execute before veil.init_role_privs(), we would use the following insert statement:

insert into veil.veil_init_fns
       (fn_name, priority)
values ('veil.init_roles', 1),
       ('veil.init_role_privs', 2);

veil_init(doing_reset bool)

function veil.veil_init(doing_reset bool) returns bool

This function, implemented by the C function veil_init(), is reponsible for initialising each veil session. The doing_reset parameter is true if we are to completely reset Veil, redefining all shared variables.

The builtin implementation of veil_init() will call each registered initialisation function (see registered initialisation functions) in turn.

If no initialisation functions are registered, veil_init() raises an exception.

As an alternative to registering initialisation functions, a Veil-based application may instead simply redefine veil.veil_init(), though this usage is deprecated.

veil_perform_reset()

function veil.veil_perform_reset() returns bool

This is used to reset Veil's shared variables. It causes veil_init(doing_reset bool) to be called. Implemented by C function veil_perform_reset().

version()

function veil.version() returns text

This function returns a string describing the installed version of veil. Implemented by C function veil_version().

Next: Building a Veil-based secure database