The sandbox framework : 1. Architecture

To meet the requirements of a customer who wants that each user of his system has his own private database connected with several corporate databases, I build a framework with the Foreign Data Wrapper protocol of PostgreSQL.

This framework is a set of functions that will be described in several posts.


Each user has its own database called herafter the sandbox or simply the sdbx.

There are several databases on several servers that contain corporate data. Some databases have the same structure but not the same content.

The front end application is connected with the sdbx only.

The end user chooses the type of application he wants and the framework connects the necessary databases and, within those databases,  attachs the necessary tables.

All information about users (name and permissions) and databases (name and location) are stored in a database called kernel that is connected with the sdbx at the login.

Those tables are attached to the sdbx via the Foreign Data Wrapper protocol.


The framework is a set of five primitives that are called from the front_end applications.

Those functions are PL/pgSQL functions stored in the sdbx :

connect_kernel(host_name, user_name, password)

connect_database(database_name, user_name, password)

attach_table(database_name, from_table_name, to_table_name, 
                 from_schema_name, to_schema_name)

attach_schema(database_name, from_schema_name, to_schema_name)


All these functions return the boolean true if the job is done or false otherwise.

In case of error, all these functions write a record in a log table with the last SQL statement executed, the error message and a timestamp. This table log belongs to the sdbx.


The FDW protocol is used as follows :

create server fdw_server_name
 foreign data wrapper postgres_fdw
 options (host ‘host_address’, 
              port ‘port_number’, dbname ‘database_name’);

create user mapping for public server fdw_server_name
 options (user ‘user_name’, password ‘password’)

create foreign_table_name (
 col1 data_type1,
 col2 data_type2,
 col3 data_type3,
 server fdw_server_name
 options (schema_name ‘schema_name’, table_name ‘table_name’)

drop server if exists fdw_server_name cascade;

Those colored strings are variables sent by the framework that receives them from the front end application and those colored strings are parameters given by the view list_fdw_definitions described below.

All those functions are build dynamically by the framework

The create foreign table is dynamically generated as follows :

Each database has a view list_fdw_definitions that contains for all tables and views the current values of :
create foreign table statement

This view is mapped in the sdbx when the connect_database is issued with the name database_name_list_fdw_definitions.

The create foreign table has placeholders that are substituted by actual values by the framework :

The kernel

The kernel is connected to the sdbx at login time but only the management has write access to the data of the kernel.

At this stage, the kernel contains two tables :

• the view permission_matrix that gives for each user the list of databases he can connect and for each database, the IP host address.

• the table sdbx_tables_2_attach that gives for each type of application the tables that must be mapped in the sdbx and linked to the front end.


Each database name on the network is unique. The framework can be enhanced by defining the databases with the triplet (host_name, port_number, database_name) but it is a good practice to keep distinct names for distinct databases.

When a fdw server is dropped, all dependant objects are dropped. The sdbx is thus cleaned of fdw stuff.

Alter a column data type in all tables

We must change the timestamp format for all columns of type timestamp.

The format is like that :

2017-06-14 17:47:23.295343

and it must be like that :

2017-06-14 17:47:23

The SQL command to be done is :

alter table my_table 
   alter column my_timestamp_column type timestamp(0);

And we embed this command into a loop that takes relevant information from the catalog :

create or replace function public.alter_all_timestamps() 
 returns void as $$
  r       record;
  stmt    varchar;
  for r in 
        information_schema.columns as c
    inner join 
        information_schema.tables as t 
        c.table_name = t.table_name
        c.table_schema = 'public'
        c.data_type = 'timestamp without time zone'
        t.table_type = 'BASE TABLE'
        stmt = 'alter table ' 
                || quote_ident(r.table_name )
                || ' alter column '
                || quote_ident(r.column_name)
                || ' type timestamp(0)';
        execute stmt;

  end loop;

end $$ language 'plpgsql' volatile;

That’s simple !

If there are views on those tables that select a column of type timestamp, those views must be dropped before the run of the function and recreated after.


Calculated columns with a trigger


Some say that calculated columns is bad design because it does not follow the relational model. It is true but performance can be greatly enhanced. When a function is applied in a query on a indexed column, the query optimizer will not use the index. It is thus sometimes better to have an index on the calculated column because queries from the front end applications will run faster.

In this simple example, we have a table with 3 columns. The first and the second are given by the user and the third is calculated by a trigger. We add a condition : x * 0 = 0 * x = x (This fantasy comes from the requirements of a customer).  It is done with the case expression.

Some say that calculated columns is bad design because it does not follow the relational model. It is true but performance can be greatly enhanced.

The condition : x * 0 = 0 * x = x is implemented with a case construct.

drop table if exists tup;

create table tup (
     col1   numeric(10,2)
    ,col2   numeric(10,2)
    ,col3   numeric(10,2)

insert into tup(col1,col2) values
     (2.87      ,3.77)
    ,(4         ,5.11)
    ,(2.12      ,0)
    ,(0.0       ,3);

update tup
    set col3 =     (case col1 when 0 then 1 else col1 end)
                *  (case col2 when 0 then 1 else col2 end);

select * from tup;

will give

col1     col2   col3
2.87     3.77   10.82
4.00     5.11   20.44
2.12     0.00    2.12
0.00     3.00    3.00

Let now add the trigger and the trigger function :

create or replace function calculate_columns() returns trigger as $$

  new.col3 =   (case new.col1 when 0 then 1 else new.col1 end)
             * (case new.col2 when 0 then 1 else new.col2 end);

  return new;

end $$ language plpgsql;

create trigger calculated_columns  
    before insert or update 
    on tup
    for each row
    execute procedure calculate_columns();

Note that we do a before insert or update trigger and that we update the columns in the row new.

insert into tup(col1, col2) values
     (6.23      ,2)
    ,(0         ,55.11);

select * from tup;

will give :

col1     col2   col3
2.87     3.77   10.82
4.00     5.11   20.44
2.12     0.00    2.12
0.00     3.00    3.00
6.23     2.00   12.46
0.00    55.11   55.11

The deal is in the bag!

To list all the pk’s and fk’s

The system catalogs of PostgreSQL are very well designed. They are not easy to understand at first glance but they allow to write short and efficient queries.

As usual, if the data model is sound, the queries are simple and natural.

Just an example : the comma separated list of columns for composite keys is automatically created in this query :

     conrelid::regclass as table_name
    pg_constraint c
    pg_namespace n on n.oid = c.connamespace
    contype in ('f', 'p')
    n.nspname = 'public'
order by
   ,contype desc;

The output is like that :

"SLM_TYPE"           SLM_TYPE_pkey                   PRIMARY KEY ("SLM_TYPE_NR")
                                                        REFERENCES "CONTACTS"("CONTACT_NR") 
                                                        ON DELETE CASCADE

By the way, it is always better to use serials for pk’s and fk’s. But I am working with database I migrate from Access to PostgreSQL. I would like to write a script that will add serials for those pk’s and fk’s and that will transform the initial pk’s and fk’s to unique constraints. Not so easy…

To list all the indexes

When we create a pk in PostgreSQL, an index named table_name_pkey is automatically created.

The following script gives all indexes, those created by the pk’s and the others.

Don’t forget that PostgreSQL does not create automatically an index when you create a fk. You have to do it yourself !

By the way, this script works for composite indexes thanks to the handy function array_to_string that creates of comma separated list of the column names. It works because the two first columns in the select clause are given in the order by.

     t.relname as table_name
    ,i.relname as index_name
    ,array_to_string(array_agg(a.attname), ', ') as column_names
     pg_class      t
    ,pg_class      i
    ,pg_index      ix
    ,pg_attribute  a
    t.oid = ix.indrelid
    i.oid = ix.indexrelid
    a.attrelid = t.oid
    a.attnum = any(ix.indkey)
    t.relkind = 'r' -- takes regular tables
    t.relname not like 'pg_%' -- excludes system catalogs
group by
order by

How to safely delete records ?

To collect accurate data is expensive !

To structure data is very expensive !

To record accurate structured data is very very expensive !


Once data is recorded in a database, it is not a good idea to definitely delete it. It is better to archive the records we don’t want to see anymore in the database.

We will build a very simple framework for a soft delete with the PostgreSQL trigger functions. In a previous post, we developed an audit system that we will use again. We have just to modify the pre-delete trigger.

The components are :

  • a schema called ‘deleted’ having the same tables that the database
  • a trigger pre-delete on each table

and, inherited from the audit system :

  • an additional column on each table called audit_id
  • a table called audit_history

Let’s begin with the creation of the schema ‘deleted’ :

create or replace function public.create_schema_deleted() returns void as $$
 r	record;
 stmt	varchar;

 execute 'create schema deleted;'
 for r in
   quote_ident(table_name) as table_name
   table_schema = 'public'


   stmt :=    'create table deleted.' 
     || r.table_name 
     || ' (like public.' 
     || r.table_name 
     || ')';

   execute stmt;

  end loop;
  execute 'grant usage on schema deleted to generic user'
  execute 'grant insert on all tables in schema deleted to generic_user;'

end $$ language 'plpgsql' volatile;

select public.create_schema_deleted();

This schema contains all the table of your production database without indexes, without pk/fk constraints, without sequences and without triggers. The role generic_user is granted to actual users.

Just after the creation of the schema, the tables are empty.

Each table has a column audit_id. It is a big serial that is incremented automatically when we insert a record in the production database.

The tables in the schema ‘deleted’ have of course also this column.

We create now the trigger function that will be executed each time an user deletes a record in the production database :

create or replace function public.pre_delete() returns trigger as $$
 stmt 	varchar;

 insert into public.audit_history
  (table_name, operation, audit_id, user_name, audit_date)
  (TG_TABLE_NAME, TG_OP, old.audit_id, current_user, now())

  stmt :=    'insert into deleted.'
   || quote_ident(TG_TABLE_NAME)
   || ' select * from public.'
   || quote_ident(TG_TABLE_NAME)
   || ' where audit_id = $1;';

  execute stmt using old.audit_id;
  return old;

end; $$ language 'plpgsql'; 

and a trigger pre-delete for each table :

create or replace function public.create_pre_delete_triggers() 
   returns void as $$
 r	record;
 stmt	varchar;
 for r in 
    select table_name 
    from information_schema.tables 
    where table_schema = 'public'

    stmt :=    'create trigger ' 
     || quote_ident(r.table_name || '_pre_delete')
     || ' after insert on public.' 
     || quote_ident(r.table_name)
     || ' for each row execute procedure public.pre_delete();';

    execute stmt;

  end loop;

end; $$ language 'plpgsql'; 

select public.create_pre_delete_triggers();

If we want to find a deleted record, we have a look in the table audit_history that has the following structure :

 id_audit_history  bigserial unique 
,table_name        text 
,operation         text 
,audit_id          bigint 
,user_name         text 
,audit_date        timestamp

And we do a select in the schema ‘deleted’ for this table and for this audit_id.

That’s simple !

A simple audit system

Let’s suppose we want to audit all insert, update and delete committed on a database.

We create a table to store relevant data :

drop table if exists audit_history;
create table audit_history (
  id_audit_history       serial
 ,table_name             text
 ,operation              text
 ,audit_id               bigint
 ,user_name              text
 ,insertion_date         timestamp       default now()

drop sequence if exists audit_history_seq;
create sequence audit_history_seq;

We create two test tables with a pk constraints and one having a fk constraint to the other. Note that this fk constraint has the clause on delete cascade.

drop table if exists app_table_ref;
drop table if exists app_table;

create table app_table (
  pk             integer         primary key
 ,info           varchar
 ,audit_id       bigserial

create table app_table_ref (
  pk             integer         primary key
 ,info           varchar
 ,fk             integer references app_table(pk) on delete cascade
 ,audit_id       bigserial

Note the presence of the column audit_id, a bigserial that is not a pk.

We create now the trigger function, a generic fonction for the two triggers : after insert or update and before delete.

create or replace function populate_audit_history() 
   returns trigger as $$

  if (TG_OP = 'INSERT' or TG_OP = 'UPDATE') then

      insert into audit_history
        (table_name, operation, audit_id, user_name)
        (TG_TABLE_NAME, TG_OP, new.audit_id, current_user);

      return new;

     insert into audit_history
        (table_name, operation, audit_id, user_name)
        (TG_TABLE_NAME, TG_OP, old.audit_id, current_user);

     return old;

  end if;
$$ language 'plpgsql';

create or replace function create_audit_triggers() 
   returns void as $$
   r       record;
   stmt    varchar;
  for r in select table_name from information_schema.tables 
              where table_name like 'app_table%' loop

     stmt :=    'create trigger '
             || quote_ident(r.table_name || '_audit_after_iu')
             || ' after insert or update on '
             || quote_ident(r.table_name)
             || ' for each row 
                    execute procedure populate_audit_history();';

     execute stmt;
     stmt :=    'create trigger '
             || quote_ident(r.table_name || '_audit_before_d')
             || ' before delete on '
             || quote_ident(r.table_name)
             || ' for each row 
                    execute procedure populate_audit_history();';

     execute stmt;

   end loop;
$$ language 'plpgsql';

select create_audit_triggers();

Note the execute instruction that allows us to execute dynamic SQL statements.

We do now some transactions on those two tables :

insert into app_table values(23,'record 23');
insert into app_table values(56,'record 56');
insert into app_table values(71,'record 71');
insert into app_table values(82,'record 82');
insert into app_table values(85,'record 85');
insert into app_table values(91,'record 91');
insert into app_table values(94,'record 94');
insert into app_table values(97,'record 97');
insert into app_table values(99,'record 99');
update app_table set info = 'modified' where pk = 23;
update app_table set info = 'modified' where pk = 56;
update app_table set info = 'modified' where pk = 97;
delete from app_table where pk = 71;
insert into app_table values(101,'record 101');
insert into app_table values(121,'record 121');
insert into app_table values(167,'record 167');
update app_table set info = 'modified' where pk = 101;
delete from app_table where pk = 121;
insert into app_table_ref values(1, 'ref1', 23);
insert into app_table_ref values(2, 'ref2', 23);
insert into app_table_ref values(3, 'ref3', 82);
delete from app_table where pk = 23;

Here is the table audit_history :

1  | app_table     | INSERT |  1 | mchl | 2017-02-08 15:01:10.28164
2  | app_table     | INSERT |  2 | mchl | 2017-02-08 15:01:10.292839
3  | app_table     | INSERT |  3 | mchl | 2017-02-08 15:01:10.304088
4  | app_table     | INSERT |  4 | mchl | 2017-02-08 15:01:10.315051
5  | app_table     | INSERT |  5 | mchl | 2017-02-08 15:01:10.32618
6  | app_table     | INSERT |  6 | mchl | 2017-02-08 15:01:10.337284
7  | app_table     | INSERT |  7 | mchl | 2017-02-08 15:01:10.348366
8  | app_table     | INSERT |  8 | mchl | 2017-02-08 15:01:10.35954
9  | app_table     | INSERT |  9 | mchl | 2017-02-08 15:01:10.370595
10 | app_table     | UPDATE |  1 | mchl | 2017-02-08 15:01:10.381727
11 | app_table     | UPDATE |  2 | mchl | 2017-02-08 15:01:10.392824
12 | app_table     | UPDATE |  8 | mchl | 2017-02-08 15:01:10.403822
13 | app_table     | DELETE |  3 | mchl | 2017-02-08 15:01:10.414956
14 | app_table     | INSERT | 10 | mchl | 2017-02-08 15:01:10.4261
15 | app_table     | INSERT | 11 | mchl | 2017-02-08 15:01:10.437168
16 | app_table     | INSERT | 12 | mchl | 2017-02-08 15:01:10.448195
17 | app_table     | UPDATE | 10 | mchl | 2017-02-08 15:01:10.459344
18 | app_table     | DELETE | 11 | mchl | 2017-02-08 15:01:10.470463
19 | app_table_ref | INSERT |  1 | mchl | 2017-02-08 15:01:10.481536
20 | app_table_ref | INSERT |  2 | mchl | 2017-02-08 15:01:10.49259
21 | app_table_ref | INSERT |  3 | mchl | 2017-02-08 15:01:10.503579
22 | app_table     | DELETE |  1 | mchl | 2017-02-08 15:01:10.514913
23 | app_table_ref | DELETE |  1 | mchl | 2017-02-08 15:01:10.514913
24 | app_table_ref | DELETE |  2 | mchl | 2017-02-08 15:01:10.514913

And here the table app_table :

  56 | modified   |        2
  82 | record 82  |        4
  85 | record 85  |        5
  91 | record 91  |        6
  94 | record 94  |        7
  97 | modified   |        8
  99 | record 99  |        9
 101 | modified   |       10
 167 | record 167 |       12

and the table app_table_ref :

  3 | ref3 | 82 |        3

We note that the delete in app_table of the record having pk = 23 has deleted also the two records of app_table_ref having fk = 23.

This design is very handy because you can add auditing on an existing database by adding a to each table : 1/  a column serial (that is not a pk) and 2/  the two triggers (after the creation of the generic function).

The applications are not touched and the referential integrity of the database is preserved.

Having for each modifications, the name of the table and the value of the audit_id, we can find, for insert and update, the rows that have changed.