fab-manager/doc/postgresql_readme.md

Detailed informations about PostgreSQL usage in Fab-manager

Run the PostgreSQL command line interface

You may want to access the psql command line tool to check the content of the database, or to run some maintenance routines. This can be achieved doing the following:

1. Enter into the PostgreSQL container

   docker exec -it fabmanager-postgres bash
   

2. Run the PostgreSQL administration command line interface, logged as the postgres user

   su postgres
   psql
   

Dumping the database

Use the following commands to dump the PostgreSQL database to an archive file

cd /apps/fabmanager/
docker-compose exec postgres bash
cd /var/lib/postgresql/data/
pg_dump -U postgres fabmanager_production > fabmanager_production_$(date -I).sql
tar cvzf fabmanager_production_$(date -I).tar.gz fabmanager_production_$(date -I).sql

If you're connected to your server thought SSH, you can download the resulting dump file using the following:

scp root@remote.server.fab:/apps/fabmanager/postgresql/fabmanager_production_$(date -I).tar.gz .

Restore the dump with the following:

tar xvf fabmanager_production_$(date -I).tar.gz
sudo cp fabmanager_production_$(date -I).sql .docker/postgresql/
rake db:drop
rake db:create
docker exec -it fabmanager-postgres bash
cd /var/lib/postgresql/data/
psql -U postgres -d fabmanager_production -f fabmanager_production_$(date -I).sql

PostgreSQL Limitations

• While setting up the database, we'll need to activate two PostgreSQL extensions: unaccent and trigram. This can only be achieved if the user, configured in config/database.yml, was granted the SUPERUSER role OR if these extensions were white-listed. So here's your choices, mainly depending on your security requirements:

  • Use the default PostgreSQL super-user (postgres) as the database user. This is the default behavior in Fab-manager.

  • Set your user as SUPERUSER; run the following command in psql (after replacing username with you user name):

    ALTER USER username WITH SUPERUSER;
    

  • Install and configure the PostgreSQL extension pgextwlist. Please follow the instructions detailed on the extension website to whitelist unaccent and trigram for the user configured in config/database.yml.

• If you intend to contribute to the project code, you will need to run the test suite with scripts/run-tests.sh. This also requires your user to have the SUPERUSER role. Please see the known issues section for more information about this.

Using another DBMS

Some users may want to use another DBMS than PostgreSQL. This is currently not supported, because of some PostgreSQL specific instructions that cannot be efficiently handled with the ActiveRecord ORM:

• app/services/members/list_service.rb@list is using ILIKE, now()::date and OFFSET.
• app/services/invoices_service.rb@list is using ILIKE and date_trunc()
• db/migrate/20160613093842_create_unaccent_function.rb is using unaccent and trigram modules and defines a PL/pgSQL function (f_unaccent())
• app/controllers/api/members_controllers.rb@search is using f_unaccent() (see above) and regexp_replace()
• db/migrate/20150604131525_add_meta_data_to_notifications.rb is using jsonb, a PostgreSQL 9.4+ datatype.
• db/migrate/20160915105234_add_transformation_to_o_auth2_mapping.rb is using jsonb, a PostgreSQL 9.4+ datatype.
• db/migrate/20181217103441_migrate_settings_value_to_history_values.rb is using SELECT DISTINCT ON.
• db/migrate/20190107111749_protect_accounting_periods.rb is using CREATE RULE and DROP RULE.
• db/migrate/20190522115230_migrate_user_to_invoicing_profile.rb is using CREATE RULE and DROP RULE.