Merge branch 'schema-updates' into add-trial-runner-id-column

mlos_bench/mlos_bench/storage/sql/schema.py

@@ -12,6 +12,9 @@
 ``repr`` or ``str`` (e.g., via ``print()``) on this object.
 The ``mlos_bench`` CLI will do this automatically if the logging level is set to
 ``DEBUG``.
+
+Also see the `mlos_bench CLI usage <../../../../../mlos_bench.run.usage.html>`__ for
+details on how to invoke only the schema creation/update routines.
 """
 
 import logging
@@ -100,6 +103,9 @@ def __init__(self, engine: Engine | None):
             Column("git_commit", String(40), nullable=False),
             PrimaryKeyConstraint("exp_id"),
         )
+        """Table storing
+        :py:mod:`~mlos_bench.storage.base_experiment_data.ExperimentData` info.
+        """
 
         self.objectives = Table(
             "objectives",
@@ -115,6 +121,9 @@ def __init__(self, engine: Engine | None):
             PrimaryKeyConstraint("exp_id", "optimization_target"),
             ForeignKeyConstraint(["exp_id"], [self.experiment.c.exp_id]),
         )
+        """Table storing :py:mod:`~mlos_bench.storage.base_storage.Storage.Experiment`
+        optimization objectives info.
+        """
 
         # A workaround for SQLAlchemy issue with autoincrement in DuckDB:
         if engine and engine.dialect.name == "duckdb":
@@ -142,6 +151,10 @@ def __init__(self, engine: Engine | None):
             col_config_id,
             Column("config_hash", String(64), nullable=False, unique=True),
         )
+        """Table storing
+        :py:mod:`~mlos_bench.storage.base_tunable_config_data.TunableConfigData`
+        info.
+        """
 
         self.trial = Table(
             "trial",
@@ -157,6 +170,9 @@ def __init__(self, engine: Engine | None):
             ForeignKeyConstraint(["exp_id"], [self.experiment.c.exp_id]),
             ForeignKeyConstraint(["config_id"], [self.config.c.config_id]),
         )
+        """Table storing :py:mod:`~mlos_bench.storage.base_trial_data.TrialData`
+        info.
+        """
 
         # Values of the tunable parameters of the experiment,
         # fixed for a particular trial config.
@@ -169,6 +185,10 @@ def __init__(self, engine: Engine | None):
             PrimaryKeyConstraint("config_id", "param_id"),
             ForeignKeyConstraint(["config_id"], [self.config.c.config_id]),
         )
+        """Table storing
+        :py:mod:`~mlos_bench.storage.base_tunable_config_data.TunableConfigData`
+        info.
+        """
 
         # Values of additional non-tunable parameters of the trial,
         # e.g., scheduled execution time, VM name / location, number of repeats, etc.
@@ -185,6 +205,9 @@ def __init__(self, engine: Engine | None):
                 [self.trial.c.exp_id, self.trial.c.trial_id],
             ),
         )
+        """Table storing :py:mod:`~mlos_bench.storage.base_trial_data.TrialData`
+        metadata info.
+        """
 
         self.trial_status = Table(
             "trial_status",
@@ -199,6 +222,9 @@ def __init__(self, engine: Engine | None):
                 [self.trial.c.exp_id, self.trial.c.trial_id],
             ),
         )
+        """Table storing :py:mod:`~mlos_bench.storage.base_trial_data.TrialData` status
+        info.
+        """
 
         self.trial_result = Table(
             "trial_result",
@@ -213,6 +239,9 @@ def __init__(self, engine: Engine | None):
                 [self.trial.c.exp_id, self.trial.c.trial_id],
             ),
         )
+        """Table storing :py:mod:`~mlos_bench.storage.base_trial_data.TrialData` result
+        info.
+        """
 
         self.trial_telemetry = Table(
             "trial_telemetry",
@@ -228,6 +257,9 @@ def __init__(self, engine: Engine | None):
                 [self.trial.c.exp_id, self.trial.c.trial_id],
             ),
         )
+        """Table storing :py:mod:`~mlos_bench.storage.base_trial_data.TrialData`
+        telemetry info.
+        """
 
         _LOG.debug("Schema: %s", self._meta)
 
@@ -244,7 +276,14 @@ def create(self) -> "DbSchema":
         return self
 
     def update(self) -> "DbSchema":
-        """Updates the DB schema to the latest version."""
+        """
+        Updates the DB schema to the latest version.
+
+        Notes
+        -----
+        Also see the `mlos_bench CLI usage <../../../../../mlos_bench.run.usage.html>`__
+        for details on how to invoke only the schema creation/update routines.
+        """
         assert self._engine
         alembic_cfg = config.Config(
             path_join(str(files("mlos_bench.storage.sql")), "alembic.ini", abs_path=True)