refactor: move set_version to DBMigrations

The only table that has been added since DB version 6 (the earliest supported version), is the versions table in DB version 101.
This commit removes the "create all tables" statement, and instead creates the versions table in the 101 migration.
See 12e074b71d.

docs/contributing.md

@@ -117,7 +117,7 @@ Licensing is now accomplished using the [REUSE](https://reuse.software/spec-3.3/
 !!! tip "PR Scope"
     If you're unsure where to stop the scope of your PR, ask yourself: _"If I broke this up, could any parts of it still be used by the project in the meantime?"_
 
-### :material-check-circle: Workflow Checks
+### Workflow Checks
 
 When pushing your code, several automated [workflows](https://github.com/TagStudioDev/TagStudio/tree/main/.github/workflows) will check it against predefined tests and style checks. It's _highly recommended_ that you run these checks locally beforehand to avoid having to fight back-and-forth with the workflow checks inside your pull requests. These checks currently include:
 
@@ -126,7 +126,7 @@ When pushing your code, several automated [workflows](https://github.com/TagStud
 - [Pytest](developing.md#pytest) tests
 - REUSE [license compliance](#licenses)
 
-## :material-timer-play: Runtime Requirements
+### Runtime Requirements
 
 Code must function on all of the supported operating systems and versions:
 
@@ -134,8 +134,18 @@ Code must function on all of the supported operating systems and versions:
 - macOS 14.0+
 - Common Linux distributions and versions
 
-Final submitted code must **_NOT:_**
+## :material-file-document: Documentation Guidelines
 
-- Contain superfluous or unnecessary logging statements
-- Cause unreasonable slowdowns to the program outside of a progress-indicated task
-- Cause undesirable visual glitches or artifacts on screen
+Documentation contributions include anything inside of the `docs/` folder as well as the `README.md`. Documentation inside the `docs/` folder is built and hosted on our static documentation site, [docs.tagstud.io](https://docs.tagstud.io/).
+
+- Use "[dash-case / kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case)" for file and folder names
+- Follow the folder structure pattern
+- Don't add images or other media with excessively large file sizes
+- Provide alt text for embedded media
+- Use "[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case)" for title capitalization
+
+## :material-translate: Translation Guidelines
+
+Translations are performed on the TagStudio [Weblate project](https://hosted.weblate.org/projects/tagstudio/).
+
+_Translation guidelines coming soon._

docs/developing.md

@@ -214,7 +214,7 @@ From there, Git will automatically run through the hooks during commit actions!
 
 You can automatically enter this development shell, and keep your user shell, with a tool like [direnv](https://direnv.net/). Some reference `.envrc` files are provided in the repository at [`contrib`](https://github.com/TagStudioDev/TagStudio/tree/main/contrib).
 
-Two currently available are for [Nix](#nix-nixos) and [uv](#installing-with-uv), to use one:
+Two currently available are for [Nix](#nixos) and [uv](#installing-with-uv), to use one:
 
 ```sh
 ln -s .envrc-$variant .envrc

docs/style.md

@@ -6,207 +6,116 @@ icon: material/sign-text
 <!-- SPDX-FileCopyrightText: (c) TagStudio Contributors -->
 <!-- SPDX-License-Identifier: GPL-3.0-only -->
 
-<!-- prettier-ignore -->
-!!! abstract "Prerequisite Reading"
-    This guide assumes you've read the [Developing](developing.md) and [Contributing](contributing.md) pages first.
-
 # :material-sign-text: Style Guide
 
-## :material-script-text: General Principles
+## Formatting
 
-- Write **clear**, **concise**, and **modular** code.
-- If the purpose of a peice of code is not obvious, a **short comment** should help explain it.
-- Remember to follow the rest of the [contribution guidelines](contributing.md)!
+Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older code may not be adhering to all of these guidelines, in which case _"do as I say, not as I do"..._
 
----
+- Do your best to write clear, concise, and modular code.
+    - This should include making methods private by default (e.g. `__method()`)
+    - Methods should only be protected (e.g. `_method()`) or public (e.g. `method()`) when needed and warranted
+- Keep a maximum column width of no more than **100** characters.
+- Code comments should be used to help describe sections of code that can't speak for themselves.
+- Use [Google style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) docstrings for any classes and functions you add.
+    - If you're modifying an existing function that does _not_ have docstrings, you don't _have_ to add docstrings to it... but it would be pretty cool if you did ;)
+- Imports should be ordered alphabetically.
+- Lists of values should be ordered using their [natural sort order](https://en.wikipedia.org/wiki/Natural_sort_order).
+    - Some files have their methods ordered alphabetically as well (i.e. [`thumb_renderer`](https://github.com/TagStudioDev/TagStudio/blob/main/src/tagstudio/qt/widgets/thumb_renderer.py)). If you're working in a file and notice this, please try and keep to the pattern.
+- When writing text for window titles or form titles, use "[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case)" capitalization. Your IDE may have a command to format this for you automatically, although some may incorrectly capitalize short prepositions. In a pinch you can use a website such as [capitalizemytitle.com](https://capitalizemytitle.com/) to check.
+- If it wasn't mentioned above, then stick to [**PEP-8**](https://peps.python.org/pep-0008/)!
 
-## :material-text-box-check: Formatting
+### Modules & Implementations
 
-Linting in Python files is mostly taken care of by [ruff](developing.md#ruff) and is based on the rules declared in `pyproject.toml` and `.editorconfig`.
+- **Do not** modify legacy library code in the `src/core/library/json/` directory
+- Avoid direct calls to `os`
+    - Use `Pathlib` library instead of `os.path`
+    - Use `platform.system()` instead of `os.name` and `sys.platform`
+- Don't prepend local imports with `tagstudio`, stick to `src`
+- Use the `logger` system instead of `print` statements
+- Avoid nested f-strings
+- Use HTML-like tags inside Qt widgets over stylesheets where possible
+
+Final submitted code must **_NOT:_**
+
+- Contain superfluous or unnecessary logging statements
+- Cause unreasonable slowdowns to the program outside of a progress-indicated task
+- Cause undesirable visual glitches or artifacts on screen
+
+### Formatter Configs
 
 TagStudio provides an [EditorConfig](https://editorconfig.org/#example-file) file ([`.editorconfig`](https://github.com/TagStudioDev/TagStudio/blob/main/.editorconfig)) along with a [Prettier](https://prettier.io/) config file ([`.prettierrc.toml`](https://github.com/TagStudioDev/TagStudio/blob/main/.prettierrc.toml)) for formatting files other than .py files (Markdown, JSON, YAML, HTML, CSS, etc.). If editing these types of files it's recommended that you use a formatter that supports EditorConfig or has its settings matched to the EditorConfig and Prettier configs. Lastly, please pay attention to the `prettier-ignore` flags in present in some files if you are not using Prettier, as formatting these sections will break formatting used elsewhere such as the [MkDocs site](https://docs.tagstud.io/).
 
-### :material-code-braces-box: Syntax Guidelines
+## Qt
 
-- Python files should always follow the [**PEP 8**]() style guide conventions, unless specifically allowed otherwise.
-    - The most notable exception in our project is the line length limit of **100** characters, which is enforced via ruff.
-    - Internal Qt methods also use `camelCase` instead of `snake_case`, so overrides of those are commonly seen in the codebase.
-- Classes and attributes considered to be "[private](https://docs.python.org/3/tutorial/classes.html#private-variables)" should be prepended with a **single underscore** (e.g. `_internal_method()`).
-    - If _functionally necessary_, an attribute name may be prepended with a double underscore to trigger "[name mangling](https://docs.python.org/3/reference/expressions.html#private-name-mangling)" (e.g. `__mangled_method()`).
-- Classes and methods should contain [Google style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) docstrings _(this style is enforced via ruff)_.
-- Lists and JSON keys should be ordered by their [natural sort order](https://en.wikipedia.org/wiki/Natural_sort_order) unless otherwise specified or readily indicated.
-- Some files have some or all of their attributes sorted. Please respect any established patterns like these in files you modify.
+As of writing this section, the QT part of the code base is quite unstructured and the View and Controller parts are completely intermixed[^1]. This makes maintenance, fixes and general understanding of the code base quite challenging, because the interesting parts you are looking for are entangled in a bunch of repetitive UI setup code. To address this we are aiming to more strictly separate the view and controller aspects of the QT frontend.
 
----
+The general structure of the QT code base should look like this:
 
-## :material-filter-cog: Modules & Systems
-
-### :fontawesome-brands-python: Python Modules
-
-- Use `Pathlib` library instead of `os.path`
-- Use `platform.system()` instead of `os.name` or `sys.platform`
-- Avoid nested f-strings
-
-### :material-tag: TagStudio Systems
-
-- Translation keys can be accessed via bracket notation (e.g. `Translations["translation_key"]`) or with the `Translations.format()` method when a value needs to be passed to a placeholder in the translation.
-- Avoid passing around the `QtDriver` class where possible. Instead, pass only the necessary components such as the `Library` and `GlobalSettings` instances.
-- Use HTML-like tags inside strings over explicit stylesheets where possible. The `Style` class provides several handy methods for formatting text with these.
-- Use the `format` method in the stylesheets class to format text headers.
-
----
-
-## :material-folder-file: Project Layout
-
-### :material-engine: Core <small>Backend</small>
-
-Code that is integral to the core functionality of TagStudio and is UI-independent belongs under the `core/` directory. It's possible that some code that serves the UI can go here, as long as its purpose is to serve _any_ UI and is independent from Qt (e.g. file preview rendering).
-
-```yaml title="Core Backend Directory Example"
-core/
-│
-├── library/ # The TagStudio library system
-│   │
-│   ├── alchemy/ # Current SQLite backend w/ SQLAlchemy ORM
-│   │
-│   ├── json/ # Read-only legacy JSON library system, kept for migrations
-│   │
-│   ├── query_lang/ # The query parser
-│   │
-│   │   # Library files that do not involve the SQLAlchemy ORM
-│   │   # NOTE: Future Non-SQLAlchemy library files will be placed here
-│   ├── refresh.py
-│   └── ...
-│
-└── utils/ # Utility classes and functions for the core
+```
+qt
+├── controllers
+│   ├── widgets
+│   │   └── preview_panel_controller.py
+│   └── main_window_controller.py
+├── views
+│   ├── widgets
+│   │   └── preview_panel_view.py
+│   └── main_window_view.py
+├── ts_qt.py
+└── mixed.py
 ```
 
-<!-- prettier-ignore -->
-!!! danger "Read-Only Legacy Code"
-    **Do not modify** legacy library code in the `src/core/library/json/` directory!
+In this structure there are the `views` and `controllers` sub-directories. They have the exact same structure and for every `<component>_view.py` there is a `<component>_controller.py` at the same location in the other subdirectory and vice versa.
 
----
+Typically the classes should look like this:
 
-### :material-button-cursor: App UI <small>Frontend</small>
+```py
+# my_cool_widget_view.py
+class MyCoolWidgetView(QWidget):
+    def __init__(self):
+        super().__init__()
+        self.__button = QPushButton()
+        self.__color_dropdown = QComboBox()
+        # ...
+        self.__connect_callbacks()
 
-The application UI code is stored in the `qt/` directory, and contains all code specific to the Qt frontend. Qt widgets are built using an [MVC](https://www.geeksforgeeks.org/software-engineering/mvc-framework-introduction/) pattern, which is described in-depth below:
+    def __connect_callbacks(self):
+        self.__button.clicked.connect(self._button_click_callback)
+        self.__color_dropdown.currentIndexChanged.connect(
+            lambda idx: self._color_dropdown_callback(self.__color_dropdown.itemData(idx))
+        )
 
-#### MVC Pattern
-
-- **Models** are usually just objects from the [library](#core-backend).
-    - The **controller** interacts with these, the _view_ does **not**.
-- **Views** are Qt layout classes that **_only_** contain the **layout** and **styling** for one or more widgets.
-    - Class names are appended with `View`, and filenames appended with `_view`.
-    - Not to be used standalone, but as the layouts for one or more controllers.
-    - Some logic is acceptable in these classes if it serves to modularize the layout and allows controllers to influence how the layout is initialized.
-    - **Reusable Layouts**
-        - If a layout class is **_not meant_** to act as a view but instead be a generic layout, it belongs in the `views/layouts/` directory and the file should be appended with `_layout`.
-    - **Styling Classes**
-        - If a class is purely a source of reusable styling, it belongs in the `views/styles/` directory.
-
-- **Controllers** are complete widgets or base classes for complete widgets.
-    - Controller files simply take on the name of the final widget they create.
-        - This also creates naming parity with other widgets that simply extend existing Qt widgets with additional logic.
-
-```yaml title="Qt Frontend Directory Example"
-qt/
-│
-├── controllers/ # Widgets implementing views or extending other widgets
-│   ├── tag_suggest_box.py # Extends from `suggest_box.py`
-│   ├── suggest_box.py # Implements `suggest_box_view.py`
-│   ├── main_window.py
-│   └── ...
-│
-├── mixed/ # Files yet to be refactored into controllers and views
-│
-├── views/ # Everything related to widget layouts and appearances
-│   │
-│   ├── layouts/ # Layouts meant to be reused on their own inside other layouts
-│   │   ├── flow_layout.py
-│   │   └── ...
-│   │
-│   ├── styles/ # Classes specific for styling
-│   │   ├── palette.py
-│   │   ├── stylesheets.py
-│   │   └── ...
-│   │
-│   │   # Views (layouts) that get implemented by controllers (widgets)
-│   ├── main_window_view.py
-│   ├── suggest_box_view.py
-│   └── ...
-│
-│   # Frontend classes that aren't related to widgets, like managers
-├── resource_manager.py
-├── cache_manager.py
-├── ts_qt.py # Qt Driver
-└── ...
+    def _button_click_callback(self):
+        raise NotImplementedError()
 ```
 
-<!-- prettier-ignore -->
-!!! warning "Pre-MVC UI Code"
-    **Do not add** new files to the `qt/mixed/` directory! These files have yet to to be refactored per the current MVC style guidelines and the directory will be **removed** once those migrations have concluded.
+```py
+# my_cool_widget_controller.py
+class MyCoolWidget(MyCoolWidgetView):
+    def __init__(self):
+        super().__init__()
 
-Observe the following key aspects of the example below:
+    def _button_click_callback(self):
+        print("Button was clicked!")
 
-- The **view** extends from a Qt layout class, and the **controller** simply extends from QWidget.
-- The **controller** is just called `MyCoolWidget` instead of `MyCoolWidgetController` as it will be directly used by other code.
-- The **view's** widgets that are intended to be controlled by the controller are **public**, while the **controller's** methods are largely **private**.
+    def _color_dropdown_callback(self, color: Color):
+        print(f"The selected color is now: {color}")
+```
+
+Observe the following key aspects of this example:
+
+- The Controller is just called `MyCoolWidget` instead of `MyCoolWidgetController` as it will be directly used by other code
+- The UI elements are in private variables
+    - This enforces that the controller shouldn't directly access UI elements
+    - Instead the view should provide a protected API (e.g. `_get_color()`) for things like setting/getting the value of a dropdown, etc.
+    - Instead of `_get_color()` there could also be a `_color` method marked with `@property`
+- The callback methods are already defined as protected methods with NotImplementedErrors
+    - Defines the interface the callbacks
+    - Enforces that UI events be handled
 
 <!-- prettier-ignore -->
-!!! example "MVC-Separated Widget Example"
+!!! tip
+    A good (non-exhaustive) rule of thumb is: If it requires a non-UI import, then it doesn't belong in the `*_view.py` file.
 
-    ```py title="views/my_cool_widget_view.py"
-    class MyCoolWidgetView(QVBoxLayout):
-        def __init__(self):
-            super().__init__()
-            self.button = QPushButton()
-            self.color_dropdown = QComboBox()
-
-            self.addWidget(self.button)
-            self.addWidget(self.color_dropdown)
-    ```
-
-    ```py title="controllers/my_cool_widget.py"
-    class MyCoolWidget(QWidget):
-        def __init__(self):
-            super().__init__()
-            self.setLayout(MyCoolWidgetView())
-            self._connect_callbacks()
-
-        def _connect_callbacks(self):
-            self.layout().button.clicked.connect(self._button_click_callback)
-            self.layout().color_dropdown.currentIndexChanged.connect(
-            lambda idx: self._color_dropdown_callback(self.color_dropdown.itemData(idx)))
-
-        def _button_click_callback(self):
-            print("Button was clicked!")
-
-        def _color_dropdown_callback(self, color: Color):
-            print(f"The selected color is now: {color}")
-    ```
-
-<!-- prettier-ignore -->
-!!! tip "Tip for Logic Placement"
-    A good rule of thumb is: If there's **conditional logic** after a widget has been created, it should probably go in a **controller**.
-
----
-
-## :material-file-document: Documentation
-
-Documentation contributions include anything inside the `docs/` folder as well as the `README.md`. Documentation inside the `docs/` folder is built and hosted on our static documentation site, [docs.tagstud.io](https://docs.tagstud.io/). Some files such as the `CHANGELOG.md`, `CONTRIBUTING.md`, and `STYLE.md` are symlinked in the repo root from the `docs/` folder.
-
-- Use "[dash-case / kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case)" for file and folder names
-- Follow the folder structure pattern
-- Don't add images or other media with excessively large file sizes
-- Provide alt text for embedded media
-- Use "[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case)" for title capitalization
-
----
-
-## :material-translate: Translations
-
-Translations are performed on the TagStudio [Weblate project](https://hosted.weblate.org/projects/tagstudio/).
-
-- Do not change text inside placeholders
-- Do not change the style tags inside translations
-- Use the glossary for term definitions
+[^1]: For an explanation of the Model-View-Controller (MVC) Model, checkout this article: [MVC Framework Introduction](https://www.geeksforgeeks.org/mvc-framework-introduction/).

src/tagstudio/core/library/alchemy/constants.py

@@ -4,6 +4,11 @@
 
 from sqlalchemy import text
 
+from tagstudio.core.library.alchemy.fields import (
+    DatetimeFieldTemplate,
+    TextFieldTemplate,
+)
+
 SQL_FILENAME: str = "ts_library.sqlite"
 JSON_FILENAME: str = "ts_library.json"
 
@@ -32,3 +37,15 @@ WITH RECURSIVE ChildTags AS (
 )
 SELECT tag_id FROM ChildTags;
 """)
+
+
+DEFAULT_FIELD_TEMPLATES = (
+    TextFieldTemplate(name="Title"),
+    TextFieldTemplate(name="Author"),
+    TextFieldTemplate(name="Artist"),
+    TextFieldTemplate(name="URL"),
+    TextFieldTemplate(name="Description", is_multiline=True),
+    TextFieldTemplate(name="Notes", is_multiline=True),
+    TextFieldTemplate(name="Comments", is_multiline=True),
+    DatetimeFieldTemplate(name="Date"),
+)

src/tagstudio/core/library/alchemy/db.py

@@ -6,12 +6,9 @@ from pathlib import Path
 from typing import override
 
 import structlog
-from sqlalchemy import Dialect, Engine, String, TypeDecorator, create_engine, text
-from sqlalchemy.exc import OperationalError
+from sqlalchemy import Dialect, String, TypeDecorator
 from sqlalchemy.orm import DeclarativeBase
 
-from tagstudio.core.constants import RESERVED_TAG_END
-
 logger = structlog.getLogger(__name__)
 
 
@@ -34,38 +31,3 @@ class PathType(TypeDecorator):
 
 class Base(DeclarativeBase):
     type_annotation_map = {Path: PathType}
-
-
-def make_engine(connection_string: str) -> Engine:
-    return create_engine(connection_string)
-
-
-def make_tables(engine: Engine) -> None:
-    logger.info("[Library] Creating DB tables...")
-    with engine.connect() as conn:
-        # TODO: this should instead be migrations that create the exact tables that were added in
-        # the respective DB versions
-        Base.metadata.create_all(conn)
-        conn.commit()
-
-        # TODO: this needs to be a migration
-        # tag IDs < 1000 are reserved
-        # create tag and delete it to bump the autoincrement sequence
-        # TODO - find a better way
-        # is this the better way?
-        result = conn.execute(text("SELECT SEQ FROM sqlite_sequence WHERE name='tags'"))
-        autoincrement_val = result.scalar()
-        if not autoincrement_val or autoincrement_val <= RESERVED_TAG_END:
-            try:
-                conn.execute(
-                    text(
-                        "INSERT INTO tags "
-                        "(id, name, color_namespace, color_slug, is_category, is_hidden) VALUES "
-                        f"({RESERVED_TAG_END}, 'temp', NULL, NULL, false, false)"
-                    )
-                )
-                conn.execute(text(f"DELETE FROM tags WHERE id = {RESERVED_TAG_END}"))
-                conn.commit()
-            except OperationalError as e:
-                logger.error("Could not initialize built-in tags", error=e)
-                conn.rollback()

src/tagstudio/core/library/alchemy/library.py

@@ -2,11 +2,6 @@
 # SPDX-License-Identifier: GPL-3.0-only
 
 
-# NOTE: This file contains necessary use of deprecated first-party code until that
-# code is removed in a future version (prefs).
-# pyright: reportDeprecated=false
-
-
 import re
 import shutil
 import sys
@@ -21,7 +16,6 @@ from typing import TYPE_CHECKING
 
 import sqlalchemy
 import structlog
-import ujson
 from humanfriendly import format_timespan  # pyright: ignore[reportUnknownVariableType]
 from sqlalchemy import (
     URL,
@@ -44,7 +38,7 @@ from sqlalchemy import (
     update,
 )
 from sqlalchemy.dialects import sqlite
-from sqlalchemy.exc import IntegrityError
+from sqlalchemy.exc import IntegrityError, OperationalError
 from sqlalchemy.orm import (
     InstanceState,
     Session,
@@ -72,16 +66,13 @@ from tagstudio.core.library.alchemy.constants import (
     DB_VERSION,
     DB_VERSION_CURRENT_KEY,
     DB_VERSION_INITIAL_KEY,
+    DEFAULT_FIELD_TEMPLATES,
     JSON_FILENAME,
     SQL_FILENAME,
     TAG_CHILDREN_QUERY,
 )
-from tagstudio.core.library.alchemy.db import make_tables
-from tagstudio.core.library.alchemy.enums import (
-    MAX_SQL_VARIABLES,
-    BrowsingState,
-    SortingModeEnum,
-)
+from tagstudio.core.library.alchemy.db import Base as ModelBase
+from tagstudio.core.library.alchemy.enums import MAX_SQL_VARIABLES, BrowsingState, SortingModeEnum
 from tagstudio.core.library.alchemy.fields import (
     LEGACY_FIELD_MAP,
     BaseField,
@@ -92,6 +83,7 @@ from tagstudio.core.library.alchemy.fields import (
     TextFieldTemplate,
 )
 from tagstudio.core.library.alchemy.joins import TagEntry, TagParent
+from tagstudio.core.library.alchemy.migrations import DBMigrations, MigrationError
 from tagstudio.core.library.alchemy.models import (
     Entry,
     Namespace,
@@ -104,7 +96,6 @@ from tagstudio.core.library.alchemy.visitors import SQLBoolExpressionBuilder
 from tagstudio.core.library.ignore import migrate_ext_list
 from tagstudio.core.library.json.library import Library as JsonLibrary
 from tagstudio.core.utils.types import unwrap
-from tagstudio.qt.translations import Translations
 
 if TYPE_CHECKING:
     from sqlalchemy import Select
@@ -170,20 +161,6 @@ def get_default_tags() -> tuple[Tag, ...]:
     return archive_tag, favorite_tag, meta_tag
 
 
-def get_default_field_templates() -> tuple[BaseFieldTemplate, ...]:
-    """Return the default field templates for a new TagStudio library."""
-    title = TextFieldTemplate(name="Title")
-    author = TextFieldTemplate(name="Author")
-    artist = TextFieldTemplate(name="Artist")
-    url = TextFieldTemplate(name="URL")
-    description = TextFieldTemplate(name="Description", is_multiline=True)
-    notes = TextFieldTemplate(name="Notes", is_multiline=True)
-    comments = TextFieldTemplate(name="Comments", is_multiline=True)
-    date = DatetimeFieldTemplate(name="Date")
-
-    return title, author, artist, url, description, notes, comments, date
-
-
 # The difference in the number of default JSON tags vs default tags in the current version.
 DEFAULT_TAG_DIFF: int = len(get_default_tags()) - len([TAG_ARCHIVED, TAG_FAVORITE])
 
@@ -431,21 +408,41 @@ class Library:
         self, library_dir: Path, in_memory: bool, sql_filename: str = SQL_FILENAME
     ) -> LibraryStatus:
         self.engine = self.__get_engine(library_dir, in_memory, sql_filename)
-        loaded_db_version: int = 0
 
         logger.info(
             "[Library] Opening SQLite Library",
             library_dir=library_dir,
         )
 
-        logger.info(f"[Library] Library DB version: {loaded_db_version}")
-        make_tables(self.engine)
+        logger.info("[Library] Creating DB tables...")
+        with self.engine.connect() as conn:
+            ModelBase.metadata.create_all(conn)
+            conn.commit()
+
+            # TODO - find a better way
+            # is this the better way?
+            # Could we perhaps update the row we are reading from here?
+            result = conn.execute(text("SELECT SEQ FROM sqlite_sequence WHERE name='tags'"))
+            autoincrement_val = result.scalar()
+            if not autoincrement_val or autoincrement_val <= RESERVED_TAG_END:
+                try:
+                    conn.execute(
+                        text(
+                            "INSERT INTO tags "
+                            "(id, name, color_namespace, color_slug, is_category, is_hidden) "
+                            f"VALUES ({RESERVED_TAG_END}, 'temp', NULL, NULL, false, false)"
+                        )
+                    )
+                    conn.execute(text(f"DELETE FROM tags WHERE id = {RESERVED_TAG_END}"))
+                    conn.commit()
+                except OperationalError as e:
+                    logger.error("Could not initialize built-in tags", error=e)
+                    conn.rollback()
 
         with Session(self.engine) as session:
             # Add default tag color namespaces.
             namespaces = default_color_groups.namespaces()
 
-            # TODO: are all of these commits necessary?
             session.add_all(namespaces)
             session.flush()
 
@@ -465,7 +462,7 @@ class Library:
             session.flush()
 
             # Add default field templates
-            for template in get_default_field_templates():
+            for template in DEFAULT_FIELD_TEMPLATES:
                 session.add(template)
             session.flush()
 
@@ -506,414 +503,25 @@ class Library:
     def open_sqlite_library(
         self, library_dir: Path, in_memory: bool, sql_filename: str = SQL_FILENAME
     ) -> LibraryStatus:
+        logger.info("[Library] Opening SQLite Library", library_dir=library_dir)
+
         self.engine = self.__get_engine(library_dir, in_memory, sql_filename)
-        loaded_db_version: int = 0
-        initial_db_version: int = DB_VERSION
 
-        logger.info(
-            "[Library] Opening SQLite Library",
-            library_dir=library_dir,
-        )
+        try:
+            migrations = DBMigrations(library_dir, self.engine)
 
-        # Don't check DB version when creating new library
-        loaded_db_version = self.get_version(DB_VERSION_CURRENT_KEY)
-        initial_db_version = self.get_version(DB_VERSION_INITIAL_KEY)
+            # save backup if patches will be applied
+            if migrations.required:
+                Library.save_library_backup_to_disk(library_dir)
 
-        # ======================== Library Database Version Checking =======================
-        # DB_VERSION 6 is the first supported SQLite DB version.
-        # If the DB_VERSION is >= 100, that means it's a compound major + minor version.
-        #   - Dividing by 100 and flooring gives the major (breaking changes) version.
-        #   - If a DB has major version higher than the current program, don't load it.
-        #   - If only the minor version is higher, it's still allowed to load.
-        if loaded_db_version < 6 or (
-            loaded_db_version >= 100 and loaded_db_version // 100 > DB_VERSION // 100
-        ):
-            mismatch_text = Translations["status.library_version_mismatch"]
-            found_text = Translations["status.library_version_found"]
-            expected_text = Translations["status.library_version_expected"]
-            return LibraryStatus(
-                success=False,
-                message=(
-                    f"{mismatch_text}\n"
-                    f"{found_text} v{loaded_db_version}, "
-                    f"{expected_text} v{DB_VERSION}"
-                ),
-            )
-
-        logger.info(f"[Library] Library DB version: {loaded_db_version}")
-        # TODO: this is very sketchy; blindly creating all tables the newest DB version should have
-        # without considering what version the DB is currently on and then doing all of the
-        # migrations after that seems like it could cause problems in some scenarios.
-        # instead only have this on creation and create new tables as part of migrations
-        # Note: this actually produces an error and fails to initialise built-in tags when opening
-        # a library that doesn't yet have the is_hidden property on the tags table
-        make_tables(self.engine)
-
-        # save backup if patches will be applied
-        if loaded_db_version < DB_VERSION:
-            self.library_dir = library_dir
-            self.save_library_backup_to_disk()
-            self.library_dir = None
-
-        # migrate DB step by step from one version to the next
-        # (migration_method, db_version, initial_db_version)
-        migrations = [
-            (self.__apply_db7_migration, 7, None),  # changes: value_type, tags
-            (self.__apply_db8_migration, 8, None),  # changes: tag_colors
-            (self.__apply_db9_migration, 9, None),  # changes: entries
-            (self.__apply_db100_migration, 100, None),  # changes: tag_parents
-            (self.__apply_db101_migration, 101, None),  # changes: versions
-            (self.__apply_db102_migration, 102, None),  # changes: tag_parents
-            (self.__apply_db103_migration, 103, None),  # changes: tags
-            (self.__apply_db104_migration, 104, None),  # changes: deletes preferences
-            (self.__apply_db200_migration, 200, None),  # changes: field tables
-            (self.__apply_db201_migration, 201, 200),  # changes: field tables
-            (self.__apply_db202_migration, 202, None),  # changes: tag_parents
-            (self.__apply_db300_migration, 300, None),  # changes: deletes folders
-        ]
-        for migration, v, iv in migrations:
-            if loaded_db_version < v and (iv is None or initial_db_version < iv):
-                logger.info(f"[Library][Migration][{v}] Starting DB Migration")
-                with Session(self.engine) as session:
-                    # any error causes transaction to rollback
-                    migration(session, library_dir)
-                    loaded_db_version = v
-                    self.set_version(session, DB_VERSION_CURRENT_KEY, v)
-                    session.commit()
-                logger.info(f"[Library][Migration][{v}] Completed DB Migration")
-
-        assert loaded_db_version >= DB_VERSION, (
-            "Ran all migrations, but the DB is still not on the newest version"
-        )
-        logger.info(f"[Library] Library migrated to DB version {DB_VERSION}")
+            migrations.run()
+        except MigrationError as e:
+            return LibraryStatus(success=False, message=e.args[0])
 
         # everything is fine, set the library path
         self.library_dir = library_dir
         return LibraryStatus(success=True, library_path=library_dir)
 
-    def __apply_db7_migration(self, session: Session, _library_dir: Path):
-        """Migrate DB from DB_VERSION 6 to 7."""
-        logger.info("[Library][Migration][7] Applying patches to DB_VERSION: 6 library...")
-        # Repair tags that may have a disambiguation_id pointing towards a deleted tag.
-        # TODO: combine into single sql statement
-        all_tag_ids = session.scalars(text("SELECT DISTINCT id FROM tags")).all()
-        disam_stmt = (
-            update(Tag)
-            .where(Tag.disambiguation_id.not_in(all_tag_ids))
-            .values(disambiguation_id=None)
-        )
-        session.execute(disam_stmt)
-        session.flush()
-
-    def __apply_db8_migration(self, session: Session, library_dir: Path):
-        """Migrate DB from DB_VERSION 7 to 8."""
-        # Add the missing color_border column to the TagColorGroups table.
-        session.execute(
-            text("ALTER TABLE tag_colors ADD COLUMN color_border BOOLEAN DEFAULT FALSE NOT NULL")
-        )
-        session.flush()
-        logger.info("[Library][Migration][8] Added color_border column to tag_colors table")
-
-        # collect new default tag colors
-        tag_colors: list[TagColorGroup] = [
-            color
-            for color in default_color_groups.shades()
-            if color.slug in ["burgundy", "dark-teal", "dark_lavender"]
-        ]
-
-        # Add any new default colors introduced in DB_VERSION 8
-        for color in tag_colors:
-            session.add(color)
-        session.flush()
-        logger.info(
-            "[Library][Migration][8] Migrated tag colors to DB_VERSION 8+",
-            color_name=tag_colors,
-        )
-
-        # Update Neon colors to use the the color_border property
-        for color in default_color_groups.neon():
-            neon_stmt = (
-                update(TagColorGroup)
-                .where(
-                    and_(
-                        TagColorGroup.namespace == color.namespace,
-                        TagColorGroup.slug == color.slug,
-                    )
-                )
-                .values(
-                    slug=color.slug,
-                    namespace=color.namespace,
-                    name=color.name,
-                    primary=color.primary,
-                    secondary=color.secondary,
-                    color_border=color.color_border,
-                )
-            )
-            session.execute(neon_stmt)
-        session.flush()
-
-    def __apply_db9_migration(self, session: Session, library_dir: Path):
-        """Migrate DB from DB_VERSION 8 to 9."""
-        # Apply database schema changes
-        add_filename_column = text(
-            "ALTER TABLE entries ADD COLUMN filename TEXT NOT NULL DEFAULT ''"
-        )
-        session.execute(add_filename_column)
-        session.flush()
-        logger.info("[Library][Migration][9] Added filename column to entries table")
-
-        # Populate the new filename column.
-        for entry in self.__all_entries(session):
-            entry.filename = entry.path.name
-            session.merge(entry)
-        session.flush()
-        logger.info("[Library][Migration][9] Populated filename column in entries table")
-
-    def __apply_db100_migration(self, session: Session, library_dir: Path):
-        """Migrate DB to DB_VERSION 100."""
-        # Repair parent-child tag relationships that are the wrong way around.
-        stmt = update(TagParent).values(
-            parent_id=TagParent.child_id,
-            child_id=TagParent.parent_id,
-        )
-        session.execute(stmt)
-        session.flush()
-        logger.info("[Library][Migration][100] Refactored TagParent table")
-
-    def __apply_db101_migration(self, session: Session, library_dir: Path):
-        """Migrate DB to DB_VERSION 101."""
-        # Ensure version rows are present
-        session.add(Version(key=DB_VERSION_INITIAL_KEY, value=100))
-        session.flush()
-
-    def __apply_db102_migration(self, session: Session, library_dir: Path):
-        """Migrate DB to DB_VERSION 102."""
-        # delete TagParents with a dangling parent reference
-        stmt = delete(TagParent).where(TagParent.parent_id.not_in(select(Tag.id).distinct()))
-        session.execute(stmt)
-        session.flush()
-        logger.info("[Library][Migration][102] Verified TagParent table data")
-
-    def __apply_db103_migration(self, session: Session, library_dir: Path):
-        """Migrate DB from DB_VERSION 102 to 103."""
-        # add the new hidden column for tags
-        session.execute(text("ALTER TABLE tags ADD COLUMN is_hidden BOOLEAN NOT NULL DEFAULT 0"))
-        session.flush()
-        logger.info("[Library][Migration][103] Added is_hidden column to tags table")
-
-        # mark the "Archived" tag as hidden
-        session.query(Tag).filter(Tag.id == TAG_ARCHIVED).update({"is_hidden": True})
-        session.flush()
-        logger.info("[Library][Migration][103] Updated archived tag to be hidden")
-
-    def __apply_db104_migration(self, session: Session, library_dir: Path):
-        """Migrate DB from DB_VERSION 103 to 104."""
-        # Convert file extension list to ts_ignore file, if a .ts_ignore file does not exist
-        self.__migrate_sql_to_ts_ignore(session, library_dir)
-        session.execute(text("DROP TABLE preferences"))
-        session.flush()
-
-    def __migrate_sql_to_ts_ignore(self, session: Session, library_dir: Path):
-        # Do not continue if existing '.ts_ignore' file is found
-        ts_ignore = library_dir / TS_FOLDER_NAME / IGNORE_NAME
-        if Path(ts_ignore).exists():
-            return
-
-        # Load legacy extension data
-        extensions: list[str] = ujson.loads(
-            unwrap(
-                session.scalar(text("SELECT value FROM preferences WHERE key = 'EXTENSION_LIST'"))
-            )
-        )
-        is_exclude_list: bool = unwrap(
-            session.scalar(text("SELECT value FROM preferences WHERE key = 'IS_EXCLUDE_LIST'"))
-        )
-
-        with open(ts_ignore, "w") as f:
-            f.write(migrate_ext_list(extensions, is_exclude_list))
-
-    def __apply_db200_migration(self, session: Session, library_dir: Path):
-        """Migrate DB to DB_VERSION 200."""
-        # Drop unused 'boolean_fields' and 'value_type' tables
-        logger.info("[Library][Migration][200] Dropping boolean_fields and value_type tables...")
-        session.execute(text("DROP TABLE boolean_fields"))
-        session.execute(text("DROP TABLE value_type"))
-
-        # Add 'name' column to text_fields and datetime_fields tables
-        logger.info("[Library][Migration][200] Adding name columns to field tables...")
-        stmt = text('ALTER TABLE text_fields ADD COLUMN name VARCHAR DEFAULT ""')
-        session.execute(stmt)
-        stmt = text('ALTER TABLE datetime_fields ADD COLUMN name VARCHAR DEFAULT ""')
-        session.execute(stmt)
-
-        # Drop unnecessary 'position' columns
-        logger.info("[Library][Migration][200] Dropping position columns to field tables...")
-        session.execute(text("ALTER TABLE datetime_fields DROP COLUMN position"))
-        session.execute(text("ALTER TABLE text_fields DROP COLUMN position"))
-
-        # Add 'is_multiline' column to text_fields table
-        logger.info("[Library][Migration][200] Adding is_multiline column to text_fields...")
-        stmt = text("ALTER TABLE text_fields ADD COLUMN is_multiline BOOLEAN NOT NULL DEFAULT 0")
-        session.execute(stmt)
-        session.flush()
-
-        # Move values from old `type_key` columns into new `name` columns
-        logger.info("[Library][Migration][200] Moving values from type_key columns to name...")
-        session.execute(text("UPDATE text_fields SET name = type_key"))
-        session.execute(text("UPDATE datetime_fields SET name = type_key"))
-        session.flush()
-
-        # Change `name` values to title case
-        logger.info("[Library][Migration][200] Normalizing TextField names...")
-        for text_field in session.execute(select(TextField)).scalars():
-            # NOTE: The only exception to the "Title Case" conversion is the "URL" field.
-            text_field.name = text_field.name.title().replace("Url", "URL").replace("_", " ")
-        logger.info("[Library][Migration][200] Normalizing DatetimeField names...")
-        for datetime_field in session.execute(select(DatetimeField)).scalars():
-            datetime_field.name = datetime_field.name.title().replace("_", " ")
-        session.flush()
-
-        # Add correct `is_multiline` values to text_fields table
-        logger.info("[Library][Migration][200] Updating is_multiline for legacy TEXT_BOXes...")
-        text_boxes = [
-            x.get("name") for x in LEGACY_FIELD_MAP.values() if x.get("is_multiline") is True
-        ]
-        update_stmt = (
-            update(TextField).where(TextField.name.in_(text_boxes)).values(is_multiline=True)
-        )
-        session.execute(update_stmt)
-        session.flush()
-
-        # Repair legacy "Description" fields to use is_multiline = True
-        logger.info("[Library][Migration][200] Repairing legacy Description fields...")
-        desc_stmt = (
-            update(TextField)
-            .where(TextField.name == "Description" and TextField.is_multiline == False)  # noqa: E712
-            .values(is_multiline=True)
-        )
-        session.execute(desc_stmt)
-
-        # Repair legacy "Comments" fields to use is_multiline = True
-        logger.info("[Library][Migration][200] Repairing legacy Comment fields...")
-        comm_stmt = (
-            update(TextField)
-            .where(TextField.name == "Comments" and TextField.is_multiline == False)  # noqa: E712
-            .values(is_multiline=True)
-        )
-        session.execute(comm_stmt)
-
-        # Add default field templates
-        logger.info("[Library][Migration][200] Adding default field templates...")
-        for template in get_default_field_templates():
-            session.add(template)
-        session.flush()
-
-        # DB indices for improved performance
-        session.execute(
-            text("CREATE INDEX IF NOT EXISTS idx_tags_name_shorthand ON tags (name, shorthand)")
-        )
-        session.execute(
-            text("CREATE INDEX IF NOT EXISTS idx_tag_parents_child_id ON tag_parents (child_id)")
-        )
-        session.execute(
-            text("CREATE INDEX IF NOT EXISTS idx_tag_entries_entry_id ON tag_entries (entry_id)")
-        )
-
-    def __apply_db201_migration(self, session: Session, library_dir: Path):
-        """Migrate DB to DB_VERSION 201."""
-        create_text_fields_table = text("""
-        CREATE TABLE text_fields_new (
-            id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
-            name VARCHAR NOT NULL,
-            entry_id INTEGER NOT NULL,
-            value VARCHAR,
-            is_multiline BOOLEAN NOT NULL,
-            FOREIGN KEY(entry_id) REFERENCES entries (id)
-        )
-        """)
-        create_datetime_fields_table = text("""
-        CREATE TABLE datetime_fields_new (
-            id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
-            name VARCHAR NOT NULL,
-            entry_id INTEGER NOT NULL,
-            value VARCHAR,
-            FOREIGN KEY(entry_id) REFERENCES entries (id)
-        )
-        """)
-
-        logger.info("[Library][Migration][201] Dropping type_key from text_fields table...")
-        session.execute(create_text_fields_table)
-        session.flush()
-        session.execute(
-            text("""
-                INSERT INTO text_fields_new (id, name, entry_id, value, is_multiline)
-                SELECT id, name, entry_id, value, is_multiline
-                FROM text_fields
-            """)
-        )
-        session.execute(text("DROP TABLE text_fields"))
-        session.execute(text("ALTER TABLE text_fields_new RENAME TO text_fields"))
-
-        logger.info("[Library][Migration][201] Dropping type_key from datetime_fields table...")
-        session.execute(create_datetime_fields_table)
-        session.flush()
-        session.execute(
-            text("""
-                INSERT INTO datetime_fields_new (id, name, entry_id, value)
-                SELECT id, name, entry_id, value
-                FROM datetime_fields
-            """)
-        )
-        session.execute(text("DROP TABLE datetime_fields"))
-        session.execute(text("ALTER TABLE datetime_fields_new RENAME TO datetime_fields"))
-
-        session.flush()
-
-    def __apply_db202_migration(self, session: Session, library_dir: Path):
-        """Migrate DB to DB_VERSION 202."""
-        stmt = delete(TagParent).where(TagParent.child_id.not_in(select(Tag.id).distinct()))
-        session.execute(stmt)
-        session.flush()
-        logger.info("[Library][Migration][202] Verified TagParent table data")
-
-    def __apply_db300_migration(self, session: Session, library_dir: Path):
-        ## remove folder_id column from entries table
-        # create new table in the desired scheme (without folder_id column)
-        session.execute(
-            text("""
-        CREATE TABLE entries_new (
-            id INTEGER NOT NULL,
-            path VARCHAR NOT NULL,
-            suffix VARCHAR NOT NULL,
-            date_created DATETIME,
-            date_modified DATETIME,
-            date_added DATETIME,
-            filename TEXT NOT NULL DEFAULT '',
-            PRIMARY KEY (id),
-            UNIQUE (path)
-        )
-        """)
-        )
-        session.flush()
-        # transfer data to new table
-        session.execute(
-            text("""
-            INSERT INTO entries_new (id, path, suffix, date_created, date_modified, date_added,
-                                     filename)
-            SELECT id, path, suffix, date_created, date_modified, date_added, filename
-            FROM entries
-        """)
-        )
-        # delete old table
-        session.execute(text("DROP TABLE entries"))
-        # rename new table to old table
-        session.execute(text("ALTER TABLE entries_new RENAME TO entries"))
-        session.flush()
-
-        ## drop table "folders"
-        session.execute(text("DROP TABLE folders"))
-        session.flush()
-
     @property
     def field_templates(self) -> Sequence[BaseFieldTemplate]:
         with Session(self.engine) as session:
@@ -1061,7 +669,8 @@ class Library:
         with Session(self.engine) as session:
             return unwrap(session.scalar(select(func.count(Entry.id))))
 
-    def __all_entries(self, session: Session, with_joins: bool = False) -> Iterator[Entry]:
+    @staticmethod
+    def _all_entries(session: Session, with_joins: bool = False) -> Iterator[Entry]:
         """Load entries without joins."""
         stmt = select(Entry)
         if with_joins:
@@ -1090,7 +699,7 @@ class Library:
     def all_entries(self, with_joins: bool = False) -> Iterator[Entry]:
         """Load entries without joins."""
         with Session(self.engine) as session:
-            return self.__all_entries(session, with_joins)
+            return Library._all_entries(session, with_joins)
 
     @property
     def tags(self) -> list[Tag]:
@@ -1838,16 +1447,17 @@ class Library:
                 session.rollback()
                 return None
 
-    def save_library_backup_to_disk(self) -> Path:
-        assert isinstance(self.library_dir, Path)
-        makedirs(str(self.library_dir / TS_FOLDER_NAME / BACKUP_FOLDER_NAME), exist_ok=True)
+    @staticmethod
+    def save_library_backup_to_disk(library_dir: Path) -> Path:
+        assert isinstance(library_dir, Path)
+        makedirs(str(library_dir / TS_FOLDER_NAME / BACKUP_FOLDER_NAME), exist_ok=True)
 
         filename = f"ts_library_backup_{datetime.now(UTC).strftime('%Y_%m_%d_%H%M%S')}.sqlite"
 
-        target_path = self.library_dir / TS_FOLDER_NAME / BACKUP_FOLDER_NAME / filename
+        target_path = library_dir / TS_FOLDER_NAME / BACKUP_FOLDER_NAME / filename
 
         shutil.copy2(
-            self.library_dir / TS_FOLDER_NAME / SQL_FILENAME,
+            library_dir / TS_FOLDER_NAME / SQL_FILENAME,
             target_path,
         )
 
@@ -2139,8 +1749,12 @@ class Library:
         Args:
             key(str): The key for the name of the version type to set.
         """
-        with Session(self.engine) as session:
-            engine = sqlalchemy.inspect(self.engine)
+        return Library._get_version(self.engine, key)
+
+    @staticmethod
+    def _get_version(engine, key: str) -> int:
+        with Session(engine) as session:
+            engine = sqlalchemy.inspect(engine)
             try:
                 # "Version" table added in DB_VERSION 101
                 if engine and engine.has_table("versions"):
@@ -2160,17 +1774,6 @@ class Library:
             except Exception:
                 return 0
 
-    def set_version(self, session: Session, key: str, value: int) -> None:
-        """Set a version value to the DB.
-
-        Args:
-            session(Session): The SQLAlchemy DB Session to use.
-            key(str): The key for the name of the version type to set.
-            value(int): The version value to set.
-        """
-        # Insert if key has no value yet, otherwise update the value
-        session.merge(Version(key=key, value=value))
-
     def mirror_entry_fields(self, entries: list[Entry]) -> None:
         """Mirror fields among multiple Entry items."""
         all_fields: set[BaseField] = set()

src/tagstudio/core/library/alchemy/migrations.py

@@ -0,0 +1,551 @@
+# SPDX-FileCopyrightText: (c) TagStudio Contributors
+# SPDX-License-Identifier: MIT
+
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import override
+
+import structlog
+import ujson
+from sqlalchemy import Engine, and_, delete, select, text, update
+from sqlalchemy.orm import Session
+
+from tagstudio.core.constants import IGNORE_NAME, TAG_ARCHIVED, TS_FOLDER_NAME
+from tagstudio.core.library.alchemy import default_color_groups
+from tagstudio.core.library.alchemy.constants import (
+    DB_VERSION,
+    DB_VERSION_CURRENT_KEY,
+    DB_VERSION_INITIAL_KEY,
+    DEFAULT_FIELD_TEMPLATES,
+)
+from tagstudio.core.library.alchemy.fields import LEGACY_FIELD_MAP, DatetimeField, TextField
+from tagstudio.core.library.alchemy.joins import TagParent
+from tagstudio.core.library.alchemy.models import Tag, TagColorGroup, Version
+from tagstudio.core.library.ignore import migrate_ext_list
+from tagstudio.core.utils.types import unwrap
+from tagstudio.qt.translations import Translations
+
+logger = structlog.get_logger(__name__)
+
+
+class MigrationError(Exception):
+    pass
+
+
+class DBMigration:
+    version: int = None  # pyright: ignore[reportAssignmentType]
+    initial_version: int | None = None
+
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log: Callable[[str], str]):
+        raise NotImplementedError
+
+
+class DBMigrations:
+    def __init__(self, library_dir: Path, engine: Engine) -> None:
+        from tagstudio.core.library.alchemy.library import Library
+
+        self.library_dir = library_dir
+        self.engine = engine
+
+        # Don't check DB version when creating new library
+        self.loaded_db_version = Library._get_version(engine, DB_VERSION_CURRENT_KEY)
+        self.initial_db_version = Library._get_version(engine, DB_VERSION_INITIAL_KEY)
+
+        # ======================== Library Database Version Checking =======================
+        # DB_VERSION 6 is the first supported SQLite DB version.
+        # If the DB_VERSION is >= 100, that means it's a compound major + minor version.
+        #   - Dividing by 100 and flooring gives the major (breaking changes) version.
+        #   - If a DB has major version higher than the current program, don't load it.
+        #   - If only the minor version is higher, it's still allowed to load.
+        if self.loaded_db_version < 6 or (
+            self.loaded_db_version >= 100 and self.loaded_db_version // 100 > DB_VERSION // 100
+        ):
+            mismatch_text = Translations["status.library_version_mismatch"]
+            found_text = Translations["status.library_version_found"]
+            expected_text = Translations["status.library_version_expected"]
+            raise MigrationError(
+                f"{mismatch_text}\n"
+                f"{found_text} v{self.loaded_db_version}, "
+                f"{expected_text} v{DB_VERSION}"
+            )
+
+        logger.info(
+            f"[Library][Migration] Starting with library DB version: {self.loaded_db_version}"
+        )
+
+    @property
+    def required(self) -> bool:
+        return self.loaded_db_version < DB_VERSION
+
+    def run(self):
+
+        # migrate DB step by step from one version to the next
+        # (migration_method, db_version, initial_db_version)
+        migrations: list[type[DBMigration]] = [
+            MigrationTo7,  # changes: value_type, tags
+            MigrationTo8,  # changes: tag_colors
+            MigrationTo9,  # changes: entries
+            MigrationTo100,  # changes: tag_parents
+            MigrationTo101,  # changes: versions
+            MigrationTo102,  # changes: tag_parents
+            MigrationTo103,  # changes: tags
+            MigrationTo104,  # changes: deletes preferences
+            MigrationTo200,  # changes: field tables
+            MigrationTo201,  # changes: field tables
+            MigrationTo202,  # changes: tag_parents
+            MigrationTo300,  # changes: deletes folders
+        ]
+        with Session(self.engine) as session:
+            for migration in migrations:
+                if self.loaded_db_version < migration.version and (
+                    migration.initial_version is None
+                    or self.initial_db_version < migration.initial_version
+                ):
+                    logger.info(f"[Library][Migration][{migration.version}] Starting DB Migration")
+                    # any error causes transaction to rollback
+                    migration.run(
+                        session,
+                        self.library_dir,
+                        lambda msg, v=migration.version: f"[Library][Migration][{v}] {msg}",
+                    )
+                    self.loaded_db_version = migration.version
+                    try:
+                        self.__set_version(session, DB_VERSION_CURRENT_KEY, migration.version)
+                    except Exception as e:
+                        logger.info(
+                            f"[Library][Migration][{migration.version}] "
+                            "Couldn't update version, continuing without commit",
+                            error=e,
+                        )
+                        session.flush()
+                    else:
+                        session.commit()
+                logger.info(f"[Library][Migration][{migration.version}] Completed DB Migration")
+
+        assert self.loaded_db_version >= DB_VERSION, (
+            "Ran all migrations, but the DB is still not on the newest version"
+        )
+        logger.info(f"[Library][Migration] Library migrated to DB version {DB_VERSION}")
+
+    def __set_version(self, session: Session, key: str, value: int) -> None:
+        """Set a version value to the DB.
+
+        Args:
+            session(Session): The SQLAlchemy DB Session to use.
+            key(str): The key for the name of the version type to set.
+            value(int): The version value to set.
+        """
+        # Insert if key has no value yet, otherwise update the value
+        session.merge(Version(key=key, value=value))
+
+
+class MigrationTo7(DBMigration):
+    version = 7
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB from DB_VERSION 6 to 7."""
+        logger.info(fmt_log("Applying patches to DB_VERSION: 6 library..."))
+        # Repair tags that may have a disambiguation_id pointing towards a deleted tag.
+        # TODO: combine into single sql statement
+        all_tag_ids = session.scalars(text("SELECT DISTINCT id FROM tags")).all()
+        disam_stmt = (
+            update(Tag)
+            .where(Tag.disambiguation_id.not_in(all_tag_ids))
+            .values(disambiguation_id=None)
+        )
+        session.execute(disam_stmt)
+        session.flush()
+
+
+class MigrationTo8(DBMigration):
+    version = 8
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB from DB_VERSION 7 to 8."""
+        # Add the missing color_border column to the TagColorGroups table.
+        session.execute(
+            text("ALTER TABLE tag_colors ADD COLUMN color_border BOOLEAN DEFAULT FALSE NOT NULL")
+        )
+        session.flush()
+        logger.info(fmt_log("Added color_border column to tag_colors table"))
+
+        # collect new default tag colors
+        tag_colors: list[TagColorGroup] = [
+            color
+            for color in default_color_groups.shades()
+            if color.slug in ["burgundy", "dark-teal", "dark_lavender"]
+        ]
+
+        # Add any new default colors introduced in DB_VERSION 8
+        for color in tag_colors:
+            session.add(color)
+        session.flush()
+        logger.info(
+            fmt_log("Migrated tag colors to DB_VERSION 8+"),
+            color_name=tag_colors,
+        )
+
+        # Update Neon colors to use the the color_border property
+        for color in default_color_groups.neon():
+            neon_stmt = (
+                update(TagColorGroup)
+                .where(
+                    and_(
+                        TagColorGroup.namespace == color.namespace,
+                        TagColorGroup.slug == color.slug,
+                    )
+                )
+                .values(
+                    slug=color.slug,
+                    namespace=color.namespace,
+                    name=color.name,
+                    primary=color.primary,
+                    secondary=color.secondary,
+                    color_border=color.color_border,
+                )
+            )
+            session.execute(neon_stmt)
+        session.flush()
+
+
+class MigrationTo9(DBMigration):
+    version = 9
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB from DB_VERSION 8 to 9."""
+        # Apply database schema changes
+        add_filename_column = text(
+            "ALTER TABLE entries ADD COLUMN filename TEXT NOT NULL DEFAULT ''"
+        )
+        session.execute(add_filename_column)
+        session.flush()
+        logger.info(fmt_log("Added filename column to entries table"))
+
+        # Populate the new filename column.
+        from tagstudio.core.library.alchemy.library import Library
+
+        for entry in Library._all_entries(session):
+            entry.filename = entry.path.name
+            session.merge(entry)
+        session.flush()
+        logger.info(fmt_log("Populated filename column in entries table"))
+
+
+class MigrationTo100(DBMigration):
+    version = 100
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB to DB_VERSION 100."""
+        # Repair parent-child tag relationships that are the wrong way around.
+        stmt = update(TagParent).values(
+            parent_id=TagParent.child_id,
+            child_id=TagParent.parent_id,
+        )
+        session.execute(stmt)
+        session.flush()
+        logger.info(fmt_log("Refactored TagParent table"))
+
+
+class MigrationTo101(DBMigration):
+    version = 101
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB to DB_VERSION 101."""
+        # Create versions table
+        session.execute(
+            text("""
+        CREATE TABLE versions (
+            "key" VARCHAR NOT NULL PRIMARY KEY,
+            value INTEGER NOT NULL
+        )
+        """)
+        )
+        session.flush()
+        # Ensure version rows are present
+        session.add(Version(key=DB_VERSION_INITIAL_KEY, value=100))
+        session.flush()
+        logger.info(fmt_log("Created versions table"))
+
+
+class MigrationTo102(DBMigration):
+    version = 102
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB to DB_VERSION 102."""
+        # delete TagParents with a dangling parent reference
+        stmt = delete(TagParent).where(TagParent.parent_id.not_in(select(Tag.id).distinct()))
+        session.execute(stmt)
+        session.flush()
+        logger.info(fmt_log("Verified TagParent table data"))
+
+
+class MigrationTo103(DBMigration):
+    version = 103
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB from DB_VERSION 102 to 103."""
+        # add the new hidden column for tags
+        session.execute(text("ALTER TABLE tags ADD COLUMN is_hidden BOOLEAN NOT NULL DEFAULT 0"))
+        session.flush()
+        logger.info(fmt_log("Added is_hidden column to tags table"))
+
+        # mark the "Archived" tag as hidden
+        session.query(Tag).filter(Tag.id == TAG_ARCHIVED).update({"is_hidden": True})
+        session.flush()
+        logger.info(fmt_log("Updated archived tag to be hidden"))
+
+
+class MigrationTo104(DBMigration):
+    version = 104
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB from DB_VERSION 103 to 104."""
+        # Convert file extension list to ts_ignore file, if a .ts_ignore file does not exist
+        cls.__migrate_sql_to_ts_ignore(session, library_dir)
+        session.execute(text("DROP TABLE preferences"))
+        session.flush()
+
+    @classmethod
+    def __migrate_sql_to_ts_ignore(cls, session: Session, library_dir: Path):
+        # Do not continue if existing '.ts_ignore' file is found
+        ts_ignore = library_dir / TS_FOLDER_NAME / IGNORE_NAME
+        if Path(ts_ignore).exists():
+            return
+
+        # Load legacy extension data
+        extensions: list[str] = ujson.loads(
+            unwrap(
+                session.scalar(text("SELECT value FROM preferences WHERE key = 'EXTENSION_LIST'"))
+            )
+        )
+        is_exclude_list: bool = unwrap(
+            session.scalar(text("SELECT value FROM preferences WHERE key = 'IS_EXCLUDE_LIST'"))
+        )
+
+        with open(ts_ignore, "w") as f:
+            f.write(migrate_ext_list(extensions, is_exclude_list))
+
+
+class MigrationTo200(DBMigration):
+    version = 200
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB to DB_VERSION 200."""
+        # Drop unused 'boolean_fields' and 'value_type' tables
+        logger.info(fmt_log("Dropping boolean_fields and value_type tables..."))
+        session.execute(text("DROP TABLE boolean_fields"))
+        session.execute(text("DROP TABLE value_type"))
+
+        # Add 'name' column to text_fields and datetime_fields tables
+        logger.info(fmt_log("Adding name columns to field tables..."))
+        stmt = text('ALTER TABLE text_fields ADD COLUMN name VARCHAR DEFAULT ""')
+        session.execute(stmt)
+        stmt = text('ALTER TABLE datetime_fields ADD COLUMN name VARCHAR DEFAULT ""')
+        session.execute(stmt)
+
+        # Drop unnecessary 'position' columns
+        logger.info(fmt_log("Dropping position columns to field tables..."))
+        session.execute(text("ALTER TABLE datetime_fields DROP COLUMN position"))
+        session.execute(text("ALTER TABLE text_fields DROP COLUMN position"))
+
+        # Add 'is_multiline' column to text_fields table
+        logger.info(fmt_log("Adding is_multiline column to text_fields..."))
+        stmt = text("ALTER TABLE text_fields ADD COLUMN is_multiline BOOLEAN NOT NULL DEFAULT 0")
+        session.execute(stmt)
+        session.flush()
+
+        # Move values from old `type_key` columns into new `name` columns
+        logger.info(fmt_log("Moving values from type_key columns to name..."))
+        session.execute(text("UPDATE text_fields SET name = type_key"))
+        session.execute(text("UPDATE datetime_fields SET name = type_key"))
+        session.flush()
+
+        # Change `name` values to title case
+        logger.info(fmt_log("Normalizing TextField names..."))
+        for text_field in session.execute(select(TextField)).scalars():
+            # NOTE: The only exception to the "Title Case" conversion is the "URL" field.
+            text_field.name = text_field.name.title().replace("Url", "URL").replace("_", " ")
+        logger.info(fmt_log("Normalizing DatetimeField names..."))
+        for datetime_field in session.execute(select(DatetimeField)).scalars():
+            datetime_field.name = datetime_field.name.title().replace("_", " ")
+        session.flush()
+
+        # Add correct `is_multiline` values to text_fields table
+        logger.info(fmt_log("Updating is_multiline for legacy TEXT_BOXes..."))
+        text_boxes = [
+            x.get("name") for x in LEGACY_FIELD_MAP.values() if x.get("is_multiline") is True
+        ]
+        update_stmt = (
+            update(TextField).where(TextField.name.in_(text_boxes)).values(is_multiline=True)
+        )
+        session.execute(update_stmt)
+        session.flush()
+
+        # Repair legacy "Description" fields to use is_multiline = True
+        logger.info(fmt_log("Repairing legacy Description fields..."))
+        desc_stmt = (
+            update(TextField)
+            .where(TextField.name == "Description" and TextField.is_multiline == False)  # noqa: E712
+            .values(is_multiline=True)
+        )
+        session.execute(desc_stmt)
+
+        # Repair legacy "Comments" fields to use is_multiline = True
+        logger.info(fmt_log("Repairing legacy Comment fields..."))
+        comm_stmt = (
+            update(TextField)
+            .where(TextField.name == "Comments" and TextField.is_multiline == False)  # noqa: E712
+            .values(is_multiline=True)
+        )
+        session.execute(comm_stmt)
+
+        # Add default field templates
+        logger.info(fmt_log("Adding default field templates..."))
+        for template in DEFAULT_FIELD_TEMPLATES:
+            session.add(template)
+        session.flush()
+
+        # DB indices for improved performance
+        session.execute(
+            text("CREATE INDEX IF NOT EXISTS idx_tags_name_shorthand ON tags (name, shorthand)")
+        )
+        session.execute(
+            text("CREATE INDEX IF NOT EXISTS idx_tag_parents_child_id ON tag_parents (child_id)")
+        )
+        session.execute(
+            text("CREATE INDEX IF NOT EXISTS idx_tag_entries_entry_id ON tag_entries (entry_id)")
+        )
+
+
+class MigrationTo201(DBMigration):
+    version = 201
+    initial_version = 200
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB to DB_VERSION 201."""
+        create_text_fields_table = text("""
+        CREATE TABLE text_fields_new (
+            id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+            name VARCHAR NOT NULL,
+            entry_id INTEGER NOT NULL,
+            value VARCHAR,
+            is_multiline BOOLEAN NOT NULL,
+            FOREIGN KEY(entry_id) REFERENCES entries (id)
+        )
+        """)
+        create_datetime_fields_table = text("""
+        CREATE TABLE datetime_fields_new (
+            id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+            name VARCHAR NOT NULL,
+            entry_id INTEGER NOT NULL,
+            value VARCHAR,
+            FOREIGN KEY(entry_id) REFERENCES entries (id)
+        )
+        """)
+
+        logger.info(fmt_log("Dropping type_key from text_fields table..."))
+        session.execute(create_text_fields_table)
+        session.flush()
+        session.execute(
+            text("""
+                INSERT INTO text_fields_new (id, name, entry_id, value, is_multiline)
+                SELECT id, name, entry_id, value, is_multiline
+                FROM text_fields
+            """)
+        )
+        session.execute(text("DROP TABLE text_fields"))
+        session.execute(text("ALTER TABLE text_fields_new RENAME TO text_fields"))
+
+        logger.info(fmt_log("Dropping type_key from datetime_fields table..."))
+        session.execute(create_datetime_fields_table)
+        session.flush()
+        session.execute(
+            text("""
+                INSERT INTO datetime_fields_new (id, name, entry_id, value)
+                SELECT id, name, entry_id, value
+                FROM datetime_fields
+            """)
+        )
+        session.execute(text("DROP TABLE datetime_fields"))
+        session.execute(text("ALTER TABLE datetime_fields_new RENAME TO datetime_fields"))
+
+        session.flush()
+
+
+class MigrationTo202(DBMigration):
+    version = 202
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        """Migrate DB to DB_VERSION 202."""
+        stmt = delete(TagParent).where(TagParent.child_id.not_in(select(Tag.id).distinct()))
+        session.execute(stmt)
+        session.flush()
+        logger.info(fmt_log("Verified TagParent table data"))
+
+
+class MigrationTo300(DBMigration):
+    version = 300
+
+    @override
+    @classmethod
+    def run(cls, session: Session, library_dir: Path, fmt_log):
+        ## remove folder_id column from entries table
+        # create new table in the desired scheme (without folder_id column)
+        session.execute(
+            text("""
+        CREATE TABLE entries_new (
+            id INTEGER NOT NULL,
+            path VARCHAR NOT NULL,
+            suffix VARCHAR NOT NULL,
+            date_created DATETIME,
+            date_modified DATETIME,
+            date_added DATETIME,
+            filename TEXT NOT NULL DEFAULT '',
+            PRIMARY KEY (id),
+            UNIQUE (path)
+        )
+        """)
+        )
+        session.flush()
+        # transfer data to new table
+        session.execute(
+            text("""
+            INSERT INTO entries_new (id, path, suffix, date_created, date_modified, date_added,
+                                     filename)
+            SELECT id, path, suffix, date_created, date_modified, date_added, filename
+            FROM entries
+        """)
+        )
+        # delete old table
+        session.execute(text("DROP TABLE entries"))
+        # rename new table to old table
+        session.execute(text("ALTER TABLE entries_new RENAME TO entries"))
+        session.flush()
+
+        ## drop table "folders"
+        session.execute(text("DROP TABLE folders"))
+        session.flush()

src/tagstudio/qt/ts_qt.py

@@ -837,7 +837,7 @@ class QtDriver(DriverMixin, QObject):
         logger.info("Backing Up Library...")
         self.main_window.status_bar.showMessage(Translations["status.library_backup_in_progress"])
         start_time = time.time()
-        target_path = self.lib.save_library_backup_to_disk()
+        target_path = Library.save_library_backup_to_disk(unwrap(self.lib.library_dir))
         end_time = time.time()
         self.main_window.status_bar.showMessage(
             Translations.format(