feat: Setup metabase_read_only role

doc/how-to/how-to-grant-metabase-permissions.md

@@ -0,0 +1,54 @@
+# How to grant Metabase permissions
+
+## What is Metabase?
+[Metabase](https://www.metabase.com/) is an open source BI service which we self-host as part of PlanX. It allows teams to view and self-serve analytics dashboards related to their flows, applications, and users.
+
+Metabase is set up and running on both Staging and Production environments, but only the Production instance (with Production data) has dashboards maintained and curated for teams.
+
+## Context
+Metabase accesses our staging and production databases through the `metabase_read_only` role which has `SELECT` (read-only) access to a subset of tables and views. This ensures that sensitive user data cannot be inadvertently exposed via Metabase, and any new tables added to the PlanX database have to be explicitly exposed via this role.
+
+The permissions granted for the `metabase_read_only` role are applied via Hasura migrations. This ensures that we have a version-controlled history of this role, and it's access level is documented in code. This is not controlled via Pulumi (IaC) as this is not used for local development or test environments ("Pizzas"), which would necessitate a second method for these environments.
+
+## How is this role used?
+
+### Staging & Production
+The `metabase_read_only` role is granted to the `metabase_user` database user, which is manually set up on both staging and production with the following SQL -
+
+```sql
+CREATE USER metabase_user WITH PASSWORD `$PASSWORD`;
+GRANT metabase_read_only TO metabase_user;
+```
+
+The password for Staging and Production databases can be found the OSL 1Password account.
+
+The username and password for Metabase are not controlled via IaC - they are manually entered via the Metabase "Admin" dashboard (`Admin Setting > Databases > "staging" | "production" > Username / Password fields`).
+
+Please note - this is separate to the role used to read/write Metabase internal application data (such as dashboard and queries). This role is setup in IaC [here](https://github.com/theopensystemslab/planx-new/blob/main/infrastructure/application/index.ts#L100). For more information, please see [the Metabase docs](https://www.metabase.com/docs/latest/installation-and-operation/configuring-application-database).
+
+### Locally & Pizzas
+If you wish to run Metabase locally using the "analytics" Docker profile (`pnpm analytics` from project root), you will need to manually run the above SQL on your local database with a password of your choice. Alternatively, you can use the root DB username/password.
+
+The Metabase service does not run on Pizzas.
+
+## Metabase permissions
+Metabase also operates it's own permissions model, which allows more fine-grained control over tables. This allows "Administrator" users access to all tables granted to the Postgres `metabase_read_only` role, but other users can only access summary views.
+
+## Process
+The process for exposing a new table / view to Metabase is as follows - 
+
+### Tables
+Generally, we'd favour exposing views of data via Metabase. This means only certain columns can be exposed, and data can be formatted in a more user-friendly manner. 
+
+If you need to expose a new table (e.g. public data) access can be granted via a Hasura migration, e.g. - 
+
+```sql
+GRANT SELECT ON public.flows TO metabase_read_only;
+```
+
+### Views
+When adding a new view, you will need to grant the `metabase_read_only` role `SELECT` access the view. Access should be applied via Hasura migrations, e.g. - 
+
+```sql
+GRANT SELECT ON public.YOUR_NEW_VIEW TO metabase_read_only;
+```

hasura.planx.uk/migrations/1709565833346_run_sql_migration/down.sql

@@ -0,0 +1,15 @@
+-- Revoke select permissions from views used by Metabase
+REVOKE SELECT ON public.analytics_summary FROM metabase_read_only;
+REVOKE SELECT ON public.feedback_summary FROM metabase_read_only;
+REVOKE SELECT ON public.submission_services_summary FROM metabase_read_only;
+
+-- Revoke select permissions from tables used by Metabase
+REVOKE SELECT ON public.flows FROM metabase_read_only;
+REVOKE SELECT ON public.published_flows FROM metabase_read_only;
+REVOKE SELECT ON public.teams FROM metabase_read_only;
+
+-- Revoke usage on schema
+REVOKE USAGE ON SCHEMA public FROM metabase_read_only;
+
+-- Drop the role
+DROP ROLE IF EXISTS metabase_read_only;

hasura.planx.uk/migrations/1709565833346_run_sql_migration/up.sql

@@ -0,0 +1,15 @@
+-- Create the role
+CREATE ROLE metabase_read_only;
+
+-- Grant usage on schema
+GRANT USAGE ON SCHEMA public TO metabase_read_only;
+
+-- Grant select permissions on public tables used by Metabase (useful for joins)
+GRANT SELECT ON public.flows TO metabase_read_only;
+GRANT SELECT ON public.published_flows TO metabase_read_only;
+GRANT SELECT ON public.teams TO metabase_read_only;
+
+-- Grant select permissions on views used by Metabase
+GRANT SELECT ON public.analytics_summary TO metabase_read_only;
+GRANT SELECT ON public.feedback_summary TO metabase_read_only;
+GRANT SELECT ON public.submission_services_summary TO metabase_read_only;

infrastructure/application/index.ts

@@ -97,6 +97,10 @@ export = async () => {
     superuser: false,
   });
   const metabasePgPassword = config.requireSecret("metabasePgPassword");
+
+  // Setup role and database for internal Metabase application data, such as dashboards and queries
+  // This is separate to the postgres/public one used to hold PlanX application data
+  // Docs: https://www.metabase.com/docs/latest/installation-and-operation/configuring-application-database
   const role = new postgres.Role(
     "metabase",
     {