Table extensions examples

docs/dev/explanations/extensions.md

@@ -76,26 +76,36 @@ To develop, follow the same [instruction as `diracx`](../tutorials/getting-start
 
 ## `gubbins-db`
 
-The `gubbins-db` package contains the extension for the DB.
+The `gubbins-db` package contains examples of an extension for the DB. What is in this example covers what can be done without incurring into risks.
+What is not specifically listed is not supported, and discouraged.
 
-### New DB
+### New SQL DB
 
-`lollygagDB` is a DB which is specific to `gubbins`, i.e. it does not modify or extend an existing `diracx` db
+`lollygagDB` is a DB which is specific to `gubbins`, i.e. it does not modify or extend an existing `diracx` db.
+This DB should not exist already in DiracX. Authors should choose a specific name that will not conflict with possible future databases developed in DiracX.
 
-### Extended DB
+### Extended SQL DB
 
-`GubbinsJobDB` illustrates how to extend an existing `diracx` DB, add new methods, modify methods, add a table.
+`GubbinsJobDB` illustrates how to extend an existing `diracx` SQL DB, add new methods, modify methods and add a table.
+If a new table is added, developers should choose a specific name for the table (e.g. including the installation name).
 
-A router test exists (`test_gubbins_job_manager.py`), even though no router is redefined. It is just to show that the correct DB is being loaded.
+Examples of what is not supported:
 
-!!! warning
+- Modifying an existing column
+- Add a column to a table
 
-    In the test dependency, you need to specify both the original DiracX `JobDB` as well as the extended one `GubbinsJobDB`. To avoid that inconvenience, reuse the same name (i.e. `JobDB` instead of `GubbinsJobDB`).
+The above use cases can be sorted by specifying "has-a" relationships: (e.g. a new table with a foreign key).
 
 ## `gubbins-routers`
 
 The `gubbins-routers` package contains the extension for the routers.
 
+A router test exists (`test_gubbins_job_manager.py`), even though no router is redefined. It is just to show that the correct DB is being loaded.
+
+!!! warning
+
+    In the test dependency, you need to specify both the original DiracX `JobDB` as well as the extended one `GubbinsJobDB`. To avoid that inconvenience, reuse the same name (i.e. `JobDB` instead of `GubbinsJobDB`).
+
 ### New router
 
 `lollygag` is a router which is specific to `gubbins`, i.e. it does not modify or extend an existing `diracx` routers. It uses the `lollygagDB`. It also makes use of gubbins' specific `properties` and `AccessPolicy`

extensions/gubbins/gubbins-db/src/gubbins/db/sql/jobs/schema.py

@@ -4,11 +4,12 @@
 from sqlalchemy.orm import Mapped, mapped_column
 
 
-# You need to inherit from the DeclarativeBase of the parent DB
+# Example of defining a new table
+# NOTE: You need to inherit from the DeclarativeBase of the parent DB
 class GubbinsInfo(JobDBBase):
     """An extra table with respect to Vanilla diracx JobDB"""
 
-    __tablename__ = "GubbinsJobs"
+    __tablename__ = "GubbinsInfo"
 
     job_id: Mapped[int] = mapped_column(
         "JobID", ForeignKey("Jobs.JobID", ondelete="CASCADE"), primary_key=True