Ubuntu Manpage: database-config-file - Golf documentation (database)

NAME

       database-config-file - Golf documentation (database)

DESCRIPTION

       Golf  application  can use any number of databases, with each specified by a database configuration file.
       This file provides database name, login and connection settings and preferences.

       When making a Golf application, you specify a database vendor and the  database  configuration  file  for
       each database your application uses (see gg), for instance:

           gg ... --db="mariadb:db1 postgres:db2 sqlite:db3"  ...

       in  which  case  there are three database configuration files (db1, db2 and db3), with db1 being MariaDB,
       db2 being PostgreSQL and db3 being SQLite database.

       You must create a database configuration file for each database your application uses, and this file must
       be placed with your source code. Such file will be copied to locations specified  and  used  by  Golf  to
       connect to database(s) (see directories).

       Each  such  file  contains  connection  information  and authentication to a database, which Golf uses to
       login. The names of these configuration files are used  in  queries.  There  is  no  limit  on  how  many
       databases  can  be  used  in  your  application  and those from different vendors can be used in the same
       application.

       An example of database configuration file (in this case MariaDB):

           [client]
           user=mydbuser
           password=somepwd
           database=mydbname
           protocol=TCP
           host=127.0.0.1
           port=3306

       USING IN YOUR QUERIES

       Database statements that perform queries (such as run-query) must specify the database configuration file
       used, unless your application uses only a single database. Such configuration  is  given  by  "@<database
       config file>" (for instance in run-query or begin-transaction). For example, in:

           run-query @mydb="select name from employees"
           ...
           end-query

       the  query  is  performed  on a database specified by the configuration file "mydb", as in (assuming it's
       PostgreSQL database):

           gg ... --db="postgres:mydb"  ...

       You do not need to manually connect to the database; when your application uses it for the first time,  a
       connection is automatically established, and lost connection is automatically re-established when needed.

       If a database is the only one used by your application, you can omit it, as in:

           run-query ="select name from employees"
           ...
           end-query

       CONNECTION SETTINGS

       The contents of a configuration file depends on the database used:

           • MariaDB: see mariadb-database

           • Postgres: see postgresql-database

           • SQLite: see sqlite-database

       SUBSTITUTING ENVIRONMENT VARIABLES

       You  can  use environment variables in database configuration files by means of substitution, in the form
       of "${VAR_NAME}". For example in file "mydb":

           [client]
           user=${DB_USER}
           password=${DB_PWD}
           database=${DB_NAME}
           protocol=TCP
           host=127.0.0.1
           port=${DB_PORT}

       Here, environment variables DB_USER, DB_PWD, DB_NAME and DB_PORT are used. They must be  defined  in  the
       shell environment prior to calling gg to make your application (if not defined the value will be empty):

           #Define environment variables for a configuration file
           export DB_USER="my_user"
           export DB_PWD="my_password"
           export DB_NAME="my_database"
           export DB_PORT="3307"

           #Make application using the above database configuration file with the environment variables specified
           gg -q --db=mariadb:mydb

       which results in file /var/lib/gg/<app name>/app/db/mydb:

           [client]
           user=my_user
           password=my_password
           database=my_database
           protocol=TCP
           host=127.0.0.1
           port=3307

       Besides  making  application deployment easier, this also adds to its security as the information such as
       above (including the database password) does not need to be a part of source code and  reside  in  source
       code control system (such as git).

       Your  environment variables can have any names, except that they cannot start with an underscore ("_") or
       be prefixed by "GG_" or "GG_", because those variable names are reserved by Golf.

       Note that if your data actually has a dollar sign and is a part of the configuration file, then  you  can
       create a variable for it:

           export DOLLAR_SIGN='$'

       and in the configuration file:

           ..
           database=my${DOLLAR_SIGN}database
           ..

       In this case the database name is "my$database".

NAME

DESCRIPTION

SEE ALSO