docs: def upgrade_database(
          alembic_config_filename: str,
          alembic_base_dir: str = None,
          starting_revision: str = None,
          destination_revision: str = "head",
          version_table: str = DEFAULT_ALEMBIC_VERSION_TABLE,
          as_sql: bool = False) -> None:
      """
      Use Alembic to upgrade our database.
  
      See http://alembic.readthedocs.org/en/latest/api/runtime.html
      but also, in particular, ``site-packages/alembic/command.py``
  
      Arguments:
          alembic_config_filename:
              config filename
  
          alembic_base_dir:
              directory to start in, so relative paths in the config file work
  
          starting_revision:
              revision to start at (typically ``None`` to ask the database)
  
          destination_revision:
              revision to aim for (typically ``"head"`` to migrate to the latest
              structure)
  
          version_table: table name for Alembic versions
  
          as_sql:
              run in "offline" mode: print the migration SQL, rather than
              modifying the database. See
              http://alembic.zzzcomputing.com/en/latest/offline.html
  
      """
  
      if alembic_base_dir is None:
          alembic_base_dir = os.path.dirname(alembic_config_filename)
      os.chdir(alembic_base_dir)  # so the directory in the config file works
      config = Config(alembic_config_filename)
      script = ScriptDirectory.from_config(config)
  
      # noinspection PyUnusedLocal,PyProtectedMember
      def upgrade(rev, context):
          return script._upgrade_revs(destination_revision, rev)
  
      log.info("Upgrading database to revision {!r} using Alembic",
               destination_revision)
  
      with EnvironmentContext(config,
                              script,
                              fn=upgrade,
                              as_sql=as_sql,
                              starting_rev=starting_revision,
                              destination_rev=destination_revision,
                              tag=None,
                              version_table=version_table):
          script.run_env()
  
      log.info("Database upgrade completed")