GOLF(2gg)

💖 GOLF(2gg) — database-config-file 💖

okay bestie, welcome to GOLF(2gg) in the Development section — this is the database-config-file page, a.k.a. the Golf documentation for database stuff. buckle up, it's giving config-file slay ✨

---

✨ NAME ✨

database-config-file — Golf documentation (database) 🗄️

---

🌸 DESCRIPTION 🌸

okay so listen. a Golf application can use any number of databases, and each one of them gets specified by a database configuration file. that file is literally carrying the database name, the login, and all the connection settings and preferences. it's the main character of your DB setup, no cap 💅

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

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

in which case there are three database configuration files — db1, db2 and db3 — where db1 is MariaDB, db2 is PostgreSQL and db3 is SQLite. three girlies, three totally different personalities 🫶

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). yes, it's got a whole relocation arc ✨

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. mix and match, it's a whole vibe 🌈

an example of a 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 a 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 a lost connection is automatically re-established when needed. it's self-healing, it's iconic, it just works 🔥

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 — and if they're not defined, the value will be empty (yes, empty, be careful bestie 😭):

#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). keep those secrets out of the repo, periodt 🔐✨

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. them's the rules 💅

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". cute, right? 🙈

---

🌟 SEE ALSO 🌟

• Database

begin-transaction commit-transaction current-row database-config-file db-error mariadb-database postgresql-database rollback-transaction run-query sqlite-database — and see all documentation 🫶

---

💖 that's the whole page bestie, you ate it 💖 this was GOLF(2gg), version $VERSION, dated $DATE. go forth and configure those databases, queen 👑🌸