Quick Start Guide (for developers) - ProofDrivenQuerying/pdq GitHub Wiki

This guide explains how to set-up your device in order to have a fully-functional development environment for PDQ.

Building PDQ and passing all tests requires the following products correctly installed and configured on your device:

• Java 11 or newer
• Apache Maven
• PostgreSQL needed for full functionality of unit and integration tests

We refer the users to the guides of the manufacturers for the specific instructions.

Using the functionalities provided by GitHub, clone or download the sources of the project from the master branch.

For example, from the command line,

$ git clone https://github.com/ProofDrivenQuerying/pdq

More information at https://help.github.com.

We will refer to the location of this pdq directory as $PDQ_HOME in the remainder of this guide.

At this point you can test that your Java and Maven are working correctly: from $PDQ_HOME run

$ mvn compile

This will compile all components of PDQ and, if you have Java and Maven installed correctly, you will see information finishing with BUILD SUCCESSFUL printed to the console. Not all of the unit tests will pass yet, so we will move on to configuring the databases.

You can use your favourite IDE and your preferred Git client.

Here we report some basic information about Maven and Git, and provide some details about setting up Eclipse.

Two databases are relevant to PDQ.

The first one is the pdq database that can be used to store the results of PDQ's reasoning process. The set-up of this database is described in the user start guide.

There is an additional database that might be relevant for developers, the tpch database. This is a test database and is used to test some core PDQ functionality as well as in regression tests.

It can be created following these instructions (after the ones of the pdq database) in a shell (Win32 console, Terminal (macOS), Linux console, ...):

1. Run createuser -U postgres --pwprompt --superuser admin to create a new user (or "role") named admin with "superuser" privileges (and type admin as password)

2. Run createdb --owner=admin -U postgres tpch to create a new database named tpch

3. Download and extract the following files: pdq-tpch-test-data.zip

4. Change all the paths in tpch-build-db.sql specifying the full path of the pdq-tpch-test-data folder extracted in the previous point

5. Run psql -U admin -W tpch to connect to the tpch DB

6. Run \i path/to/tpch-build-db.sql (with path/to being the path of the pdq-tpch-test-data folder extracted before), to populate the DB

7. Create the three views used for some PDQ testing:

   CREATE VIEW region_nation AS SELECT n.n_nationkey as nation_key, n_name as nation_name, r.r_regionkey as region_key, r_name as region_name FROM nation as n, region as r WHERE n.n_regionkey = r.r_regionkey;
   

   CREATE VIEW order_customer AS SELECT c.c_name as cname, c.c_address as caddress, c.c_nationkey as cnation, c.c_acctbal as cactbal, o.o_orderpriority as opriority, o.o_clerk as oclerk, p.p_name as pname, p.p_brand as pbrand, p.p_type as ptype, l.l_extendedprice as lextendedprice, l.l_discount as ldiscount, l.l_tax as ltax, l.l_returnflag as lflag FROM customer as c, orders as o, lineitem as l, part as p WHERE o.o_orderkey = l.l_orderkey AND o.o_custkey = c.c_custkey AND l.l_partkey = p.p_partkey;
   

   CREATE VIEW order_supplier AS SELECT s.s_name as sname, s.s_address as saddress, s.s_nationkey as snation, s.s_acctbal as sactbal, o.o_orderpriority as opriority, o.o_clerk as oclerk, p.p_name as pname, p.p_brand as pbrand, p.p_type as ptype, l.l_extendedprice as lextendedprice, l.l_discount as ldiscount, l.l_tax as ltax, l.l_returnflag as lflag FROM supplier as s, orders as o, lineitem as l, part as p WHERE o.o_orderkey = l.l_orderkey AND l.l_partkey = p.p_partkey AND l.l_suppkey = s.s_suppkey;
   

8. Run \d+ to check if the previous two points worked as expected.
   This should print a list of relations with 17 rows, 8 of Type table, 6 of Type sequence, and 3 of Type view, all with admin as Owner. It should be similar to the following one:

   Schema	Name	Type	Owner	Size	Description
   public	customer	table	admin	29 MB
   public	customer_c_custkey_seq	sequence	admin	8192 bytes
   public	lineitem	table	admin	950 MB
   public	nation	table	admin	8192 bytes
   public	nation_n_nationkey_seq	sequence	admin	8192 bytes
   public	order_customer	view	admin	0 bytes
   public	order_supplier	view	admin	0 bytes
   public	orders	table	admin	216 MB
   public	orders_o_orderkey_seq	sequence	admin	8192 bytes
   public	part	table	admin	32 MB
   public	part_p_partkey_seq	sequence	admin	8192 bytes
   public	partsupp	table	admin	143 MB
   public	region	table	admin	8192 bytes
   public	region_nation	view	admin	0 bytes
   public	region_r_regionkey_seq	sequence	admin	8192 bytes
   public	supplier	table	admin	1848 kB
   public	supplier_s_suppkey_seq	sequence	admin	8192 bytes

9. Run ALTER ROLE admin WITH NOSUPERUSER; to remove "superuser" privileges of the admin role

10. Run \du to confirm

11. Run \q to logout

To install the project, run

mvn install

If there are problems because some tests fail, run

mvn install -DskipTests

To execute the Test Suite, run

mvn test

Or, to run the tests of individual sub-projects, run

mvn test -f [sub-project-name]

where [sub-project-name] is one of {common, reasoning, cost, planner, runtime, datasources}

External dependencies are managed by Maven automatically. The following is a list of external dependencies used by PDQ, which you should ensure are on the CLASSPATH:

The following table lists dependencies by PDQ module:

PDQ uses log4j for logging. By default, little information will be written to logs, but this is configurable by editing the relevant log4j2.xml files which can be found in

<component>/main/src/resources/log4j2.xml

for each <component> of common, planner, cost, reasoning, regression, runtime and gui.

These files contain a line:

<Logger name="uk.ac.ox.cs.pdq" level="WARN">

where level can be set to one of ALL, DEBUG, INFO, WARN, ERROR, FATAL, or OFF, depending on the output level you prefer.

Log files are written to

<component>/log/pdq.log

1. master is the official, most stable version.

• Java https://www.java.com
• Apache Maven https://maven.apache.org
• PostgreSQL https://www.postgresql.org
• Master branch of PDQ https://github.com/ProofDrivenQuerying/pdq
• GitHub Help https://help.github.com
• Roles of Maven, Eclipse and Git in PDQ https://github.com/ProofDrivenQuerying/pdq/wiki/Roles-of-Maven,-Eclipse-and-Git-in-PDQ
• Resolving conflicts after git merge with Eclipse https://github.com/ProofDrivenQuerying/pdq/wiki/Resolving-conficts-after-git-merge-with-Eclipse