DESCRIPTION:
============

Cyclotis is a database enabling to translators to work at same time on the same document.
This is not a full computer-assisted-translation (CAT) tool,
but a resource to be plugged into your favorite CAT client interface.

This package contains the SQL code of the database, with a script to create it easily

INSTALLATION:
=============

You must install Postgresql database server, version 8.4 or more (9.2 or more is recommended for REST interface). No need to be in the same host.
All you need already installed is Perl, DBI and DBD:Pg
For database creation the script can use the standard command-line tools (createdb, pg_config) but it is not mandatory, it can use DBI instead.

Warning: if you use PostgreSQL < 13.0, initial database creation (but not creation of tables) require PostgreSQL account with administrator rights.
That means that you must run create-db or init-db as PostgreSQL admin account (postgres account or other one with admin rights), 
but all other commands can work with user rights.
This constraint disappears if you use PostgreSQL 13.0 or later.

If you make use of the REST API, all used databases (catalogs) will require a connection, so it is adviced to reduce amount of catalogs.
Direct access plugins can access several databases.

USAGE:
======

Do not make use of "psql < table.sql" or "createdb" : this does not pre-load extensions - use dbcreator.pl instead.

Documentation about dbcreator.pl is inside the script itself, in Pod format.
If you downloaded the archive from the web site, an html version is in the directory "doc"
(do not make use of documentation of the web site, it is not always up to date with what you just downloaded)
If "doc" if not present, as if you use a Git clone of the project, then you can generate it using "create-package.sh doc"
(other options: "create-package.sh tar" or "create-package zip" to create a publishable archive in given format)

Six database modes are provided. 
Any combination access mode + database mode is supported, but you may choose the database mode regarding the usage:
- The mode 'by_void' is ideal for direct access in case you do not use inheritance for personal tables. It takes less space in the Postgresql server.
- The mode 'by_id::noRules' is ideal for direct access in case you use in-depth inheritance for personal tables.
  It takes more space in the server but enables jointure with meta_info to know which table a result comes from, which by_void mode does not.
- The mode 'by_id::withRules' enables less memory usage in the HTTP server when you use the REST API.
  It takes profit from Postgres's constraint_exclusion, which may be set to 'on' to be efficient (not needed in by_void mode).
  Note that PostgreSQL 9.2 or later is recommanded in this case.
  For users of direct access, it also enables jointure with meta_info to know which table a result comes from, which by_void mode does not.
- The mode 'by_path::noLangs' is to be used in case you use REST API and want to use inheritance between personal tables.
  Like the previous one it is based on constraint_exclusion, but the identifier is a string containing inheritance hierarchy:
  it takes more space on disk but subparts of the string can be used to query parent tables, so the HTTP server requires less RAM.
- The mode 'by_path::withLangs' is to be used in case you use REST API and want to use inheritance by language 
  (i.e. insertion depends on source or target language, or both).
- The mode 'by_code' is an intermediate between 'by_id::withRules' and 'by_path', taking less space than the last one but enabling personal table inheritance.
  However, this is not a concrete mode, you will have to subclass it depending on the tree you want to build.
  Two modes 'by_code::theme' and 'by_code::lang' are provided as samples.

The mode must be decided when you create the database and cannot be changed after. To do this, please define CYCLOTIS_MODE environment variable.
There is no default value: some commands in dbcreator.pl are independant, but those who differ will not work at all if the variable is not defined.
Also please make sure that the variable reflects the database you are using : you can have different mode between databases (catalogs),
but using dbcreator on an already created database with incorrect value for CYCLOTIS_MODE can cause unexpected behaviour.

LICENSE:
========

Please read the file LICENSE for the very last version of conditions applied to this code.

