Configuration of database access for applications based on GNUe Common
======================================================================

1. Prepare your database backend
--------------------------------

Make sure that your database server is running and accepting connections from
the machine you want to run the application on.  Also make sure that the users
and permissions are set up on the database server. If you want to create a new
database, in any case make sure that your current user is allowed to create new
users and new databases on the database server.

Please refer primarly to the documentation of your database server about how to
achieve and test this.  However, the files "hints.postgresql.txt",
"hints.mysql.txt" and "hints.firebird.txt" in gnue-common's documentation
directory contain some hints on how to set up the respective database servers
for use with GNU Enterprise.

Note that you do not yet create the actual database on the database server.


2. Set up your connections.conf
-------------------------------

The most important configuration file for GNU Enterprise is "connections.conf".
On Posix compatible systems (like GNU/Linux) you will find this file in the
"/etc/gnue" directory (for prepackaged versions) or in the "/usr/local/gnue/etc"
directory (if you installed from the source packages).  Alternatively, all GNU
Enterprise tools accept a "--connections" paramter that overrides the location
of the connections.conf file.

On the machine running GNU Enterprise, you must have an entry in the
connections.conf pointing to your database. In three tier configurations using
GNUe AppServer, the machine running the user interface must have an entry
pointing to the running appserver, while the machine on which GNUe AppServer
runs must have an entry pointing to the backend database.

Example for a correct connections.conf entry pointing to a PostgreSQL database:

  [gnue]
  comment = My Database
  provider = psycopg2
  host = localhost
  dbname = gnue
  username = frank
  password = secret

[gnue]: the name of the database connection.  You can define several
  connections to different databases in the same connections.conf file.  Please
  refer to the documentation of each GNUe tool to find out more about how to
  define which connection should be used.

comment: comment text without any special meaning

provider: can for example be "psycopg2" for PostgreSQL database servers using
  the Psycopg2 driver or "sqlite" if you use the SQLite embedded database.  See
  http://www.gnuenterprise.org/tools/common/databases/ for a complete list of
  supported providers.  Please note that depending on the provider chosen, the
  rest of the parameter list can vary.

host: hostname of the machine running the database server

dbname: name of the database

username: user name which GNU Enterprise should use to connect to the database.
  Some databases do not or not always require a username.  If no username is
  given, it defaults to "gnue".

password: password which GNU Enterprise should use to connect to the database.
  Some databases do not or not always require a password.
