Index Next
1. Installation

1. Installation

A quick overview of the installation process can be found in the Daylight Installation Guide. This section is intended to give detailed installation instructions.

1.1 Installation of the Daylight Tar File

To install Daycart, the Daylight tar distribution must be unpacked. No other installation is required for Daycart. If one wishes to use other programs/tools within the Daylight distribution the relevant installation must be performed. Daylight is, by convention, unpacked into /usr/local/daylight/v495 and should be owned by the 'thor' or 'daylight' accounts. This location is defined as DY_ROOT. The Daylight distribution contains two directories that are relevant to the daycart install: 'pgcart', which has the installation SQL scripts and 'lib' which has the required shared object libraries.

1.2 Postgresql Installation

One can perform a generic Postgresql installation following the usual procedures. There are no specific configuration requirements of the Postgresql install, however there are two configuration settings which will make Daycart run more smoothly:

  • Use C locale when initializing the database. This is necessary for Postgresql to perform text sorting and hence is used for indexed search terms: "like", ">", ">=;", "<", "<=;".

    The locale is set during the initdb step with: initdb -D <database_directory> --locale=C

  • Set the "standard_conforming_strings" parameter to "on" in postgresql.conf. This parameter controls whether ordinary string literals treat backslashes ("\") literally, as specified in the SQL standard, or as escape characters, which was the historical usage.

    Prior to Postgres 9.1, the default setting was "off" which means that a backslash is treated as an escape character. Since the backslash is used in SMILES to indicate double-bond stereochemistry, it is preferred to disable the escaping of the backslash character and adopt the SQL standard behavior.

    Note that this parameter does not apply to programatic interfaces such as JDBC, which have their own string handling/escaping conventions.

1.3 Schema and Function Creation

In order to use Daycart functions, each database within an instance must have the dcischem schema defined. The schema must contain a number of tables which control the licensing and behavior of the Daycart functions. Each Daycart user must have select privilege on the tables. It is convenient to define a new database role which grants the privileges as a set. Connect to the desired Postgresql database as the root user (typically postgres). Execute the '$DY_ROOT/pgcart/create_pg_schema.sql' script within the session:

db=# \i create_pg_schema.sql

Next, insert the Daycart license in the dcischem.license table. Contact Daylight at license@daylight.com if you don't have a license.

NOTE: The license key is required in order to run the installation of the Postgresql function creation.

Daycart includes multiple versions of libpgcart.so in each release. One or more of the following files will be found in your Daylight distribution (depending on the operating system and version): 

  $DY_ROOT/lib/libpgcart.so.84        32-bit ddlib.so for Postgresql 8.4.x
  $DY_ROOT/lib/libpgcart.so.90        32-bit ddlib.so for Postgresql 9.0.x
  $DY_ROOT/lib64/libpgcart.so.84      64-bit ddlib.so for Postgresql 8.4.x
  $DY_ROOT/lib64/libpgcart.so.90      64-bit ddlib.so for Postgresql 9.0.x

Run the command 'pg_config --pkglibdir'. This prints the default library location within your postgresql installation. Move the appropriate file into this directory as libpgcart.so.

Execute the script 'create_pg_functions.sql' as the root user in the desired database: 

db=# \i create_pg_functions.sql

By default the create_pg_functions.sql script points to '$libdir/libpgcart.so' when defining the Daycart functions. The variable $libdir is specific to ones postgres installation and can be discovered by running 'pg_config --pkglibdir'. If one wishes to keep libpgcart.so in a different location, one must edit the create_pg_functions.sql file and change *all* references to $libdir/libpgcart.so to the desired path.

The only Postgresql-specific configuration needed is for handling of backslashes in psql.

1.4 Testing the Installation

Simple queries can be used to test the cartridge. 

db=# select getinfo('daycart_version');

 getinfo
---------
 4.95

db=# select testlicense('daycart');

 testlicense 
-------------
           1

db=# select smi2cansmi('NCC', 0);

 smi2cansmi 
------------
 CCN

If the above queries don't give the expected results, see the section on troubleshooting.

1.5 Installation Troubleshooting

The Postgresql cartridge installation is fairly straightforward. The most common problem people run into is permissions; a non-privileged user doesn't have access to the tables within the dcischem schema. When the user attempts to run a function, one gets the error: 

ERROR:  relation "dcischem.license" does not exist at character 67
QUERY:  SELECT expiration, key, product, organization, site, address
        from dcischem.license where expiration > current_date

In this case, verify that the schema dcischem exists within the current database and that the schema contains the license, options, and ptable tables. Furthermore, make sure that usage privileges have been granted on the schema to public (or to a named role) and that select privileges have been granted on the three tables to public (or to the named role). If using roles, verify that the current user has been granted to named role.

1.6 Verification

The subdirectory 'pgcart/TEST' includes a stand-alone script which tests the cartridge installation. The shell script 'test.sh' will execute the test.sql SQL script and compare the output to reference output file. Any discrepencies will be reported. The script 'test.sh' attempts to log in without specifying a userid/password with a default database. Depending on the local Postgresql configuration, one may need to edit the script and set the PG_HOME location, a username and database.

Note also that the script attepts to add data to the dcischem.options and dcischem.ptable tables in order to test their operation. If the user running test.sh does not have insert and delete privilege on these two tables then parts of the testing will fail. One will see the following output: 

psql:test.sql:15: ERROR:  permission denied for relation options
psql:test.sql:18: ERROR:  permission denied for relation options
psql:test.sql:109: ERROR:  permission denied for relation ptable
psql:test.sql:130: ERROR:  permission denied for relation ptable
67a68
> INSERT 0 1
74c75
<        0
---
>        1
83c84
<  TRUE
---
>  FALSE
89a91
> DELETE 1
479a482
> INSERT 0 1
509a513
> DELETE 1

If these are the only failures then the installation is certainly fine. Granting insert and delete privilege on the two tables will allow the tests to complete.

Note that the SQL script gives useful examples of using the cartridge functionality in each category.

1.7 De-Installation

In order to cleanly de-install the cartridge, one simply runs the clean_pg.sql script. The script removes all cartridge functions. The dcischem schema and its three tables (license, options, ptable) are preserved for convenience.

It is safe to repeatedly run the scripts create_pg_functions.sql and clean_pg.sql.

When one runs create_pg_schema.sql after clean_pg.sql, one will see warnings that the tables license, options, and ptable already exist, however these warnings don't impact the outcome of the cartridge re-installation.

After running clean_pg.sql , the database will be left in its original pre-cartridge state. One can then delete the license, options, and ptable tables and dcischem schema, if desired, to eliminate all remnants of the cartridge.