Update-davical-database

Purpose
The update-davical-database program exists to update the database schema, functions and fixed data when programming changes make it necessary to change the database structure. In the past this program was called 'update-rscds-database', and that program continues to exist, simply providing a different default for the database name.

Running the Program
Normally the program will be in:

/usr/share/davical/dba/update-davical-database

If you have a configuration file previously set up you should not need any command-line options. Otherwise you may want to specify the user to connect to the database as, like:

/usr/share/davical/dba/update-davical-database --dbuser=davical_dba

On ubuntu (which uses ident authentiction), you need to log in as user postgres, and then run the script as follows, and this even if you've got a "working" davical set-up (with presuably a config file somewhere):

/usr/share/davical/dba/update-davical-database --dbuser=postgres

To get the program help page, use:

/usr/share/davical/dba/update-davical-database --help

A configuration file is strongly recommended if you use password authentication for the davical_dba user, since otherwise you will be prompted many times for the password when the program runs.

Normal Output of the Program
The database is version 8.4 currently at revision 1.2.7. Applying patch 1.2.8.sql ... succeeded. Successfully applied 1 patches. Supported locales updated. Updated view: dav_principal.sql applied. CalDAV functions updated. RRULE functions updated. Database permissions updated.

Update Problems
If you see something different from this then it hasn't worked correctly. Possibly you see some kind of permissions problem on the tables. One such problem is described here: Issues/Wrong table owner.

If there are problems with the database patches in the update, your database structure will not have been changed. In this case DAViCal should still work fine if you roll the code back to the previous code version and run the update-davical-database from that version, to reset the functions, views and so forth to their previous values.

Check it's not an issue like the one above, and if so then try and provide the full output of the database update when run with the --debug option, in any bug report you may choose to file.

Configuration
The  program will look for a configuration file called   which should be located in the same directory as your DAViCal configuration files - usually   or.

Configuration Settings
The database username for connecting with sufficient rights to create tables, functions and granting access to other users, e.g.: admin_db_user: davical_dba

The password. Leading and trailling spaces are stripped, so don't do that. E.g.: admin_db_pass: very, very 5ecret

The hostname/IP. Not needed if using unix sockets to a local server. Some examples would be: admin_db_host: 2401:170:20:17::1024:0 admin_db_host: 172.17.217.2 admin_db_host: dbserver.davical.net

The database name, e.g.: admin_db_name: davical

The database port. Not needed if it is the default '5432', e.g.: admin_db_port: 5432

The name of the database user the web application uses to connect, e.g.: app_db_user: davical_app

Example for current versions
If you installed DAViCal from 0.9.4 or later, the defaults for update-davical-database will usually be OK. A base administration.yml file would look like this: ## admin_db_user: davical_dba ## ## ## admin_db_name: davical ## ## app_db_user: davical_app
 * 1) The database username for connecting with sufficient rights to create
 * 2) tables, functions and granting access to other users.
 * 1) The password.  Leading and trailling spaces are stripped, so don't do that
 * 2) admin_db_pass: very, very 5ecret
 * 1) The hostname/IP.  Not needed if using unix sockets to a local server.
 * 2) admin_db_host: 2401:170:20:17::1024:0
 * 3) admin_db_host: 172.17.217.2
 * 4) admin_db_host: dbserver.davical.net
 * 1) The database name
 * 1) The database port.  Not needed if it is the default '5432'
 * 2) admin_db_port: 5432
 * 1) The name of the database user the web application uses to connect

Command-line Options
update-davical-database [options] Options are: --debug          Turn on debugging --dbname name    The database to dig into --dbuser name    Connect to the database as this user. --dbport 5432    Connect to the database on this port. --dbhost name    Connect to the database on this host. --appuser name   The username which the application uses for it's database connection. --nopatch        Don't try and apply any patches --revoke name    Revoke permissions from this user

The program will apply any patches to the database which have not yet been applied, run any desired data patch scripts and set the correct minimum permissions for the web application user.

Options on the command-line will override any values set in the configuration file.

Securing Database Passwords
Rather than providing a password in the configuration file or on the command-line, where it could potentially be viewed by other users of your system, it is recommended that you use a .pgpass file in your home directory to hold the database password. This file must be mode 600 to work.

A .pgpass file should contain lines of the following format:

hostname:port:database:username:password

So, for DAViCal typically this will be something like:

*:*:davical:davical_dba:very, very 5ecret secure.db.server.net:5433:davical_dba:3xtr3m31y 5ecr3t parswurd

And of course, as mentioned above, it must be in your home directory, mode 600.

Older Versions
If you installed DAViCal prior to 0.9.4 some things are likely to be a little different, such as the name of the database. Here are a couple of examples for setup for those older versions.

Example for 0.9.2 and prior
If you installed DAViCal at version 0.9.2 or earlier then the database is most likely called 'rscds' and the web application will connect to the database as the 'general' database user. A base administration.yml file would look like this: ## admin_db_user: postgres ## ## ## admin_db_name: rscds ## ## app_db_user: general
 * 1) The database username for connecting with sufficient rights to create
 * 2) tables, functions and granting access to other users.
 * 1) The password.  Leading and trailling spaces are stripped, so don't do that
 * 2) admin_db_pass: very, very 5ecret
 * 1) The hostname/IP.  Not needed if using unix sockets to a local server.
 * 2) admin_db_host: 2401:170:20:17::1024:0
 * 3) admin_db_host: 172.17.217.2
 * 4) admin_db_host: dbserver.davical.net
 * 1) The database name
 * 1) The database port.  Not needed if it is the default '5432'
 * 2) admin_db_port: 5432
 * 1) The name of the database user the web application uses to connect

Example for 0.9.3 installations
If you installed DAViCal from version 0.9.3, the database will probably be named 'davical' and the web application will connect to the database as the 'general' database user. A base administration.yml file would look like this: ## admin_db_user: postgres ## ## ## admin_db_name: davical ## ## app_db_user: general
 * 1) The database username for connecting with sufficient rights to create
 * 2) tables, functions and granting access to other users.
 * 1) The password.  Leading and trailling spaces are stripped, so don't do that
 * 2) admin_db_pass: very, very 5ecret
 * 1) The hostname/IP.  Not needed if using unix sockets to a local server.
 * 2) admin_db_host: 2401:170:20:17::1024:0
 * 3) admin_db_host: 172.17.217.2
 * 4) admin_db_host: dbserver.davical.net
 * 1) The database name
 * 1) The database port.  Not needed if it is the default '5432'
 * 2) admin_db_port: 5432
 * 1) The name of the database user the web application uses to connect