Merge pull request #170 from opengisch/specific-roles

implement specific roles

Author: 3nids

docs/docs/cli/role.md

@@ -1,5 +1,7 @@
-usage: pum role [-h] {create,grant,revoke,drop}
+usage: pum role [-h] [--suffix SUFFIX] [--no-create-generic] {create,grant,revoke,drop}
 ### positional arguments:
 - `{create,grant,revoke,drop}`: Action to perform
 ### options:
 - `-h, --help`: show this help message and exit
+- `--suffix SUFFIX`: Create DB-specific roles by appending this suffix to each role name (e.g. 'lausanne' creates 'role_lausanne')
+- `--no-create-generic`: When using --suffix, skip creating the generic (base) roles and granting inheritance

docs/docs/roles.md

@@ -52,14 +52,48 @@ roles:
 
 - The `RoleManager` class can be initialized with a list of roles (as dicts or `Role` objects).
 - It checks that inherited roles exist and builds a mapping of role names to `Role` objects.
-- The `create` method can be used to create roles and grant permissions in the database.
+- The `create_roles` method creates roles and optionally grants permissions in the database.
 - Permissions are enforced by granting the specified actions on the listed schemas to the role.
 
 **PermissionType Enum:**
 
 - `read`: Grants `USAGE` and `SELECT` privileges.
 - `write`: Grants `INSERT`, `UPDATE`, and `DELETE` privileges.
 
+## DB-Specific Roles
+
+When you have several database instances of the same module in a single PostgreSQL cluster, the roles defined in the configuration would be shared across all databases. To isolate permissions per database, you can create **DB-specific roles** by providing a `suffix`.
+
+For example, with a role `tww_user` and suffix `lausanne`:
+
+1. A specific role `tww_user_lausanne` is created and granted the configured permissions.
+2. The generic role `tww_user` is also created (unless `create_generic=False` / `--no-create-generic`).
+3. The generic role is granted membership of the specific role, so that `tww_user` inherits `tww_user_lausanne`'s permissions.
+
+This way, users assigned to `tww_user` automatically get access to the Lausanne database, and you can repeat the process for other databases (e.g. `tww_user_zurich`).
+
+### CLI Usage
+
+```bash
+# Create specific roles with suffix, plus generic roles with inheritance
+pum -p mydb role create --suffix lausanne
+
+# Create only the specific roles (no generic roles)
+pum -p mydb role create --suffix lausanne --no-create-generic
+```
+
+### Python API
+
+```python
+role_manager.create_roles(
+    connection=conn,
+    suffix="lausanne",         # creates <role>_lausanne
+    create_generic=True,       # also create the base roles (default)
+    grant=True,                # grant configured permissions
+    commit=True,
+)
+```
+
 ## Summary
 
 - Define roles and permissions in your config YAML under the `roles` key.

pum/changelog.py

@@ -20,6 +20,8 @@
 class Changelog:
     """This class represent a changelog directory.
     The directory name is the version of the changelog.
+
+    .. versionadded:: 1.0.0
     """
 
     def __init__(self, dir):

pum/cli.py

@@ -238,6 +238,18 @@ def formatter_class(prog):
     parser_role.add_argument(
         "action", choices=["create", "grant", "revoke", "drop"], help="Action to perform"
     )
+    parser_role.add_argument(
+        "--suffix",
+        help="Create DB-specific roles by appending this suffix to each role name (e.g. 'lausanne' creates 'role_lausanne')",
+        type=str,
+        default=None,
+    )
+    parser_role.add_argument(
+        "--no-create-generic",
+        help="When using --suffix, skip creating the generic (base) roles and granting inheritance",
+        action="store_true",
+        default=False,
+    )
 
     # Parser for the "check" command
     parser_checker = subparsers.add_parser(
@@ -545,7 +557,13 @@ def cli() -> int:  # noqa: PLR0912
                 exit_code = 1
             else:
                 if args.action == "create":
-                    config.role_manager().create_roles(connection=conn)
+                    config.role_manager().create_roles(
+                        connection=conn,
+                        suffix=args.suffix,
+                        create_generic=not args.no_create_generic,
+                        grant=True,
+                        commit=True,
+                    )
                 elif args.action == "grant":
                     config.role_manager().grant_permissions(connection=conn)
                 elif args.action == "revoke":

pum/dumper.py

@@ -14,6 +14,11 @@
 
 
 class DumpFormat(Enum):
+    """Enumeration of supported dump formats.
+
+    .. versionadded:: 1.0.0
+    """
+
     CUSTOM = "custom"
     PLAIN = "plain"
 
@@ -26,7 +31,10 @@ def to_pg_dump_flag(self):
 
 
 class Dumper:
-    """This class is used to dump and restore a Postgres database."""
+    """This class is used to dump and restore a Postgres database.
+
+    .. versionadded:: 1.0.0
+    """
 
     def __init__(self, pg_connection: str, dump_path: str):
         """Initialize the Dumper.

pum/exceptions.py

@@ -1,60 +1,96 @@
 # Base exception for all PUM errors
 class PumException(Exception):
-    """Base class for all exceptions raised by PUM."""
+    """Base class for all exceptions raised by PUM.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 class PumDependencyError(PumException):
-    """Exception when dependency are not resolved"""
+    """Exception when dependency are not resolved.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 # --- Configuration and Validation Errors ---
 
 
 class PumConfigError(PumException):
-    """Exception raised for errors in the PUM configuration."""
+    """Exception raised for errors in the PUM configuration.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 class PumInvalidChangelog(PumException):
-    """Exception raised for invalid changelog."""
+    """Exception raised for invalid changelog.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 # --- Schema Migration Errors ---
 class PumSchemaMigrationError(PumException):
-    """Exception raised for errors related to schema migrations."""
+    """Exception raised for errors related to schema migrations.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 class PumSchemaMigrationNoBaselineError(PumSchemaMigrationError):
-    """Exception raised when no baseline version is found in the migration table."""
+    """Exception raised when no baseline version is found in the migration table.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 # --- Hook Errors ---
 
 
 class PumHookError(PumException):
-    """Exception raised for errors by an invalid hook."""
+    """Exception raised for errors by an invalid hook.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 # --- Changelog/SQL Errors ---
 
 
 class PumSqlError(PumException):
-    """Exception raised for SQL-related errors in PUM."""
+    """Exception raised for SQL-related errors in PUM.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 # --- Dump/Restore Errors (for dumper.py, if needed) ---
 
 
 class PgDumpCommandError(PumException):
-    """Exception raised for invalid pg_dump command."""
+    """Exception raised for invalid pg_dump command.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 class PgDumpFailed(PumException):
-    """Exception raised when pg_dump fails."""
+    """Exception raised when pg_dump fails.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 class PgRestoreCommandError(PumException):
-    """Exception raised for invalid pg_restore command."""
+    """Exception raised for invalid pg_restore command.
+
+    .. versionadded:: 1.0.0
+    """
 
 
 class PgRestoreFailed(PumException):
-    """Exception raised when pg_restore fails."""
+    """Exception raised when pg_restore fails.
+
+    .. versionadded:: 1.0.0
+    """

pum/feedback.py

@@ -11,6 +11,8 @@ class Feedback(abc.ABC):
 
     This class provides methods for progress reporting and cancellation handling.
     Subclasses should implement the abstract methods to provide custom feedback mechanisms.
+
+    .. versionadded:: 1.3.0
     """
 
     def __init__(self) -> None:
@@ -89,6 +91,8 @@ class LogFeedback(Feedback):
 
     This is the default feedback implementation that simply logs messages
     without any UI interaction.
+
+    .. versionadded:: 1.3.0
     """
 
     def report_progress(self, message: str, current: int = 0, total: int = 0) -> None:
@@ -106,6 +110,8 @@ class SilentFeedback(Feedback):
     """Feedback implementation that does nothing.
 
     This can be used when no feedback is desired.
+
+    .. versionadded:: 1.3.0
     """
 
     def report_progress(self, message: str, current: int = 0, total: int = 0) -> None:

pum/hook.py

@@ -19,6 +19,8 @@ class HookBase(abc.ABC):
     This class defines the interface for application hooks that can be implemented in Python.
     It requires the implementation of the `run_hook` method, which will be called during the migration process.
     It can call the execute method to run SQL statements with the provided connection and parameters.
+
+    .. versionadded:: 1.0.0
     """
 
     def __init__(self) -> None:
@@ -69,7 +71,10 @@ def execute(
 
 class HookHandler:
     """Handler for application hooks.
-    This class manages the execution of application hooks, which can be either SQL files or Python functions."""
+    This class manages the execution of application hooks, which can be either SQL files or Python functions.
+
+    .. versionadded:: 1.0.0
+    """
 
     def __init__(
         self,

pum/parameter.py

@@ -12,6 +12,7 @@ class ParameterType(Enum):
         DECIMAL (str): Represents a decimal parameter type.
         PATH (str): Represents a path parameter type.
 
+    .. versionadded:: 1.0.0
     """
 
     BOOLEAN = "boolean"
@@ -26,7 +27,10 @@ def __str__(self) -> str:
 
 
 class ParameterDefinition:
-    """A class to define a migration parameter."""
+    """A class to define a migration parameter.
+
+    .. versionadded:: 1.0.0
+    """
 
     def __init__(
         self,

pum/pum_config.py

@@ -100,7 +100,10 @@ def _exception_chain_text(exc: BaseException) -> str:
 
 
 class PumConfig:
-    """A class to hold configuration settings."""
+    """A class to hold configuration settings.
+
+    .. versionadded:: 1.0.0
+    """
 
     def __init__(
         self,