3.1.1 How do I add a new database?

A: (GNATS 3.1xx) (Please consider upgrading to GNATS 4.0 or greater.)

1. Create the base directory for the new database, say ‘/usr/local/gnats/db2’, and make sure it is owned by the GNATS user.
2. In there, create subdirectories ‘gnats-adm’, ‘gnats-adm/locks’, and ‘gnats-queue’, and make sure they is owned by the GNATS user.
3. Now you need to populate the new ‘gnats-adm’ directory. The easiest way is to copy all files from ‘gnats-db/gnats-adm’ to ‘/usr/local/gnats/db2/gnats-adm’, and edit them to reflect the needs of your new database. Again, make sure they are owned by the gnats user.

   Note that there must be a category named pending. It is used when no category is given in a report, and when a report names an invalid category.

   Also note that each database needs its own mail address for submissions (see also step 8 below), and that you must enter it in the file ‘config’.

4. As the GNATS user, run ‘mkcat --directory=/usr/local/gnats/db2’ to create the directories for the categories. Remove the files ‘current’ and ‘index’, if they exist.
5. If the new database is split off of another one, move or copy the existing reports to their new location. This is easiest if the categories have the same names as in the original database. (See How do I rename a category? if some of them changed names.)

   Run the program gen-index to create the index file (see (gnats)gen-index section ‘Regenerating the index’ in Keeping Track).

   Find the greatest report number and put it (or any larger number) into ‘/usr/local/gnats/db2/gnats-adm/current’.

   Caution: E-mail updates to the PRs you moved to the new database may still arrive at the old database. You may want to contact everybody who knows about these PRs, asking them to use the mail address of the new database when sending a follow-up.

6. Now add a line for the new database to ‘gnats-db.conf’, like this:

   /usr/local/gnats/db2:GreatNewDB

   Gnatsd reads it on startup (and as it is started by inetd, this means it becomes effective with the next connection to gnatsd). Gnatsweb (see Gnatsweb) learns the database list from gnatsd, so it will offer you the new database "GreatNewDB" when it is invoked next time.

   If you do not know where ‘gnats-db.conf’ lives, run:

   ‘strings /where/ever/gnatsd | grep gnats-db.conf’

7. Don’t forget to setup a cron job to run through the additional ‘gnats-queue’. Note that you need to specify the database directory to ‘queue-pr’, i.e.,

   ‘/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -r’

   or, if you prefer the long options,

   ‘/usr/local/lib/gnats/queue-pr --directory=/usr/local/gnats/db2 --run’

8. Don’t forget to create mail aliases for your new database (see (gnats)Aliases section ‘Setting up mail aliases’ in Keeping Track). Take care that the aliases have the right database, e.g.,

   GreatNewDB-bugs: "|/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -q" GreatNewDB-query: "|/usr/local/lib/gnats/mail-query -d /usr/local/gnats/db2"

   If you do not want to allow querying the database by mail, omit the ‘GreatNewDB-query’ alias.

   You usually need the cooperation of a system administrator for this step (if you are not a system administrator yourself, of course).

   Make sure that ‘/usr/local/gnats/db2/gnats-adm/config’ gives the correct mail addresses for GNATS_ADDR (this must be different for each database) and for GNATS_ADMIN (this is probably the same for all databases).

   GNATS_ADDR="GreatNewDB-bugs@bugs.example.com" GNATS_ADMIN="gnats-admin@bugs.example.com"

   If your GNATS sits behind a firewall and needs to exchange mails with the outside world, see also Outgoing mail bounces.

A: (GNATS 4.x) With version 4, this has become much easier (see (gnats)mkdb section ‘Adding another database’ in Keeping Track):

1. Add a line for the new database to ‘databases’, like this:

   GreatNewDB:Our great tools:/usr/local/gnats/db2

   Then, as the GNATS user, run ‘mkdb GreatNewDB’ to create the database. Make sure that the directory (in our example, ‘/usr/local/gnats/db2’) can be created by the GNATS user.

   (Note that there must be a database named default. It is used as a fallback by some tools if no database is specified. You need not use it actively, but you should have run ‘mkdb default’.)

   Gnatsd reads the file ‘databases’ on startup (and as it is started by inetd, this means it becomes effective with the next connection to gnatsd). Gnatsweb (see Gnatsweb) learns the database list from gnatsd, so it will offer you the new database "GreatNewDB" when it is invoked next time.

   If you do not know where ‘databases’ lives, run:

   ‘strings /where/ever/gnatsd | grep databases’

2. Now, as the GNATS user, edit the files in directory ‘/usr/local/gnats/db2/gnats-adm’ to reflect the needs of your new database.
3. Depending on the settings in the ‘dbconfig’ file of the new database, you need not run mkcat anymore in order to create new category directories in your database—GNATS 4 creates them automatically when they are missing. See (gnats)dbconfig file section ‘The dbconfig file’ in Keeping Track, for details.
4. Don’t forget to setup a cron job to run through the additional ‘gnats-queue’. Note that you need to specify the database to ‘queue-pr’, i.e.,

   ‘/usr/local/libexec/gnats/queue-pr -d GreatNewDB -r’

   or, if you prefer the long options,

   ‘/usr/local/libexec/gnats/queue-pr --database=GreatNewDB --run’

5. Don’t forget to create mail aliases for your new database (see (gnats)Aliases section ‘Setting up mail aliases’ in Keeping Track). Take care that the aliases have the right database, e.g.,

   GreatNewDB-bugs: "|/usr/local/libexec/gnats/queue-pr -d GreatNewDB -q" GreatNewDB-query: "|/usr/local/libexec/gnats/mail-query -d GreatNewDB"

   If you are updating from GNATS 3.1xx, note that the ‘-d’ option has changed its meaning: it does not give the directory of the database, but its name. (In case you prefer the long form of the option, it is now ‘--database’ instead of ‘--directory’.)

   If your GNATS sits behind a firewall and needs to exchange mails with the outside world, see also Outgoing mail bounces.

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.