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 Renaming a Category if some of them changed names.)

   Run the program gen-index to create the index file (see 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 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 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 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 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.