1.2 Postgresql Installation
1.3 Schema and Function Creation
1.4 Testing the Installation
1.5 Installation Troubleshooting
A quick overview of the installation process can be found in the Daylight Installation Guide. This section is intended to give detailed installation instructions.
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.
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:
db=# \i create_pg_schema.sql
Next, insert the Daycart license in the dcischem.license table. Contact Daylight at firstname.lastname@example.org 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.
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.
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.
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.
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.