update blog post locations SQL type

Author: VerdantFox

.github/copilot-instructions.md

@@ -27,17 +27,17 @@ HTML routes auto-discover and register all modules in `app/web/html/routes/` via
 
 ### Local development
 
-```bash
+```shell
 # Start DB (Docker Postgres) + seed dummy data
-python -m scripts.start_local_postgres
+python -m scripts.start_local_postgres --migrate head
 
 # Start app (requires tmux): runs Tailwind watcher + uvicorn with hot-reload
 ./scripts/run-dev.sh
 ```
 
 ### Running tests
 
-```bash
+```shell
 # Unit + functional tests only (default, fast)
 pytest
 
@@ -55,15 +55,22 @@ Tests use a **separate Postgres container** (`postgres_test`, port 5433). The ro
 
 ### Linting & formatting
 
-```bash
+```shell
 pre-commit run --all-files
 ```
 
 ### DB migrations
 
-```bash
-python -m scripts.alembic revision --autogenerate -m "description"
-python -m scripts.alembic upgrade head
+Database migrations use alembic to generate and run migrations. When a database migration is needed, use the following to generate a new migration file:
+
+```shell
+python -m scripts.alembic migrate -m "description of migration"
+```
+
+Note: You'll need a local Postgres instance running to generate the migration against. You can use the same local Postgres instance used for development:
+
+```shell
+python -m scripts.start_local_postgres --migrate head
 ```
 
 ## Key Conventions

README.md

@@ -15,13 +15,13 @@ You'll need to install a few things to get the website running locally. The webs
 
 First, install [uv](https://github.com/astral-sh/uv) for package management. I recommend installing it with the following command:
 
-```bash
+```shell
 curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
 Then install python environment:
 
-```bash
+```shell
 # Create a virtual environment
 uv python install 3.14
 uv venv --python=3.14 venv
@@ -33,15 +33,15 @@ uv pip install -r requirements-dev.txt
 
 Update requirements with:
 
-```bash
+```shell
 ./scripts/update-requirements.sh
 ```
 
 ### Node
 
 First, install the latest versions of npm and node. Then install the node environment:
 
-```bash
+```shell
 # Install node environment
 npm install
 ```
@@ -58,7 +58,7 @@ Docker and Docker Compose configurations are in `docker_config`.
 
 To start up the local database for development, run:
 
-```bash
+```shell
 python -m scripts.start_local_postgres
 ```
 
@@ -68,7 +68,7 @@ python -m scripts.start_local_postgres
 
 To run the app locally, you can use the following command:
 
-```bash
+```shell
 ./scripts/run-dev.sh
 ```
 
@@ -78,7 +78,7 @@ This will start an instance of `tailwind` that will build the CSS and watch for
 
 To run the app in Docker, use the following command:
 
-```bash
+```shell
 ./scripts/deploy.sh
 ```
 
@@ -88,13 +88,13 @@ This command assumes that the Postgres database is not already started by `scrip
 
 To stop the app, use:
 
-```bash
+```shell
 ./scripts/deploy.sh --down
 ```
 
 For more options, use:
 
-```bash
+```shell
 ./scripts/deploy.sh --help
 ```
 
@@ -104,13 +104,13 @@ Tests are written in Python with pytest. They include functional tests against t
 
 To run the playwright tests, you'll need to first install the playwright browsers:
 
-```bash
+```shell
 playwright install
 ```
 
 To run tests use one of the following commands:
 
-```bash
+```shell
 # Standard run of functional and unit tests
 pytest
 
@@ -128,13 +128,13 @@ pytest --cov --cov-report=term --cov-report=html
 
 I use pre-commit to run linting and formatting checks before every commit. Install the pre-commit hooks with:
 
-```bash
+```shell
 pre-commit install
 ```
 
 To run the checks manually, use:
 
-```bash
+```shell
 pre-commit run --all-files
 ```
 
@@ -148,7 +148,7 @@ Lint checks include (but are not limited to):
 
 To update dependencies, run:
 
-```bash
+```shell
 # Update Python dependencies
 ./scripts/update-requirements.sh --python
 
@@ -187,7 +187,7 @@ Server-side, a cron job runs every 5 minutes to check for new commits on the `re
 
 To deploy the app manually, SSH into the server, go to the project, and use the following command:
 
-```bash
+```shell
 ./scripts/deploy.sh --prod
 ```
 
@@ -204,7 +204,7 @@ SSL certificates are generated by the domain registrar and are stored in the `ce
 
 In addition to the SSL certificates, you'll need to generate a Diffie-Hellman key exchange file for nginx. You can generate this file with the following command:
 
-```bash
+```shell
 sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048
 ```
 

app/datastore/db_models.py

@@ -5,7 +5,7 @@
 
 import sqlalchemy as sa
 from sqlalchemy import Column, Computed, ForeignKey, Index, String, Table, asc
-from sqlalchemy.dialects.postgresql import TSVECTOR
+from sqlalchemy.dialects.postgresql import ARRAY, TSVECTOR
 from sqlalchemy.ext.asyncio import AsyncAttrs
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
 
@@ -182,8 +182,9 @@ class BlogPostMedia(Base):
     Attributes
     ----------
         name: The name of the media, given as the title of the HTML tag.
-        locations: The location of the file on the filesystem. If multiple versions
-            of the file are included, they are comma-separated.
+        locations: The locations of the file on the filesystem. If multiple
+            versions of the file are included (e.g. webp + original), each
+            path is a separate element in the list.
 
     """
 
@@ -193,15 +194,11 @@ class BlogPostMedia(Base):
     blog_post_id: Mapped[BlogPostFK | None]
     blog_post: Mapped[BlogPost] = relationship(back_populates="media")
     name: Mapped[str]
-    locations: Mapped[str]
+    locations: Mapped[list[str]] = mapped_column(ARRAY(String))
     media_type: Mapped[str]
     position: Mapped[int | None]
     created_timestamp: Mapped[DateTimeIndexed]
 
-    def locations_to_list(self) -> list[str]:
-        """Get the media locations as a list."""
-        return self.locations.split(",")
-
 
 class BlogPostComment(Base):
     """Blog post comment model."""

app/services/blog/blog_handler.py

@@ -554,14 +554,12 @@ async def save_media_for_blog_post(
     name: str,
 ) -> db_models.BlogPost:
     """Save media for a blog post."""
-    locations_str, media_type = _save_bp_media(
-        name=name, blog_post_slug=blog_post.slug, media=media
-    )
+    locations, media_type = _save_bp_media(name=name, blog_post_slug=blog_post.slug, media=media)
     return await commit_media_to_db(
         db=db,
         blog_post=blog_post,
         name=name,
-        locations_str=locations_str,
+        locations=locations,
         media_type=media_type,
     )
 
@@ -597,7 +595,7 @@ async def delete_media_from_blog_post(
         media = result.scalars().one()
     except sqlalchemy.exc.NoResultFound as e:
         raise errors.BlogPostMediaNotFoundError from e
-    media_locations = media.locations_to_list()
+    media_locations = media.locations
     for location in media_locations:
         media_handler.del_media_from_path_str(location)
     await db.delete(media)
@@ -606,7 +604,7 @@ async def delete_media_from_blog_post(
     return blog_post
 
 
-def _save_bp_media(name: str, blog_post_slug: str, media: UploadFile) -> tuple[str, str]:
+def _save_bp_media(name: str, blog_post_slug: str, media: UploadFile) -> tuple[list[str], str]:
     file_name = f"{blog_utils.get_slug(name)}--{blog_post_slug}"
     return media_handler.upload_blog_media(
         media=media,
@@ -619,15 +617,15 @@ async def commit_media_to_db(  # noqa: PLR0913 (too-many-arguments)
     *,
     blog_post: db_models.BlogPost,
     name: str,
-    locations_str: str,
+    locations: list[str],
     media_type: str,
     position: int | None = None,
 ) -> db_models.BlogPost:
     """Commit a blog post media to the database."""
     bp_media_object = db_models.BlogPostMedia(
         blog_post_id=blog_post.id,
         name=name,
-        locations=locations_str,
+        locations=locations,
         media_type=media_type,
         created_timestamp=datetime.now(UTC),
         position=position,

app/services/media/media_handler.py

@@ -63,12 +63,12 @@ async def upload_avatar(pic: UploadFile, name: str) -> str:
     return get_path_str_from_static(path)
 
 
-def upload_blog_media(media: UploadFile, name: str) -> tuple[str, str]:
+def upload_blog_media(media: UploadFile, name: str) -> tuple[list[str], str]:
     """Upload a blog media file.
 
     Returns
     -------
-        A tuple of the path string and the media type.
+        A tuple of the list of path strings and the media type.
 
     See `save_media` for more details.
 
@@ -77,17 +77,15 @@ def upload_blog_media(media: UploadFile, name: str) -> tuple[str, str]:
     return save_media(media, name)
 
 
-def save_media(media: UploadFile, name: str) -> tuple[str, str]:
+def save_media(media: UploadFile, name: str) -> tuple[list[str], str]:
     """Save a media file.
 
     Returns
     -------
-        A tuple of the path string and the media type.
+        A tuple of the list of path strings and the media type.
 
-    The path string is a comma-separated list of paths.
-
-    Images save a webp version as well as the original,
-    if the webp version is smaller.
+        Images save a webp version as well as the original,
+        if the webp version is smaller.
 
     """
     media_type = get_media_type_from_file(media)
@@ -99,15 +97,15 @@ def save_media(media: UploadFile, name: str) -> tuple[str, str]:
     raise ValueError(msg)
 
 
-def save_image(name: str, image_file: MediaFileProtocol) -> str:
+def save_image(name: str, image_file: MediaFileProtocol) -> list[str]:
     """Save an image, and its webp version."""
     og_image_path = BLOG_UPLOAD_FOLDER / _fix_name_suffix(name)
 
     # GIF and SVG don't save properly with pillow
     # Webp is already compressed
     if og_image_path.suffix.casefold() in {".gif", ".svg", ".webp"}:
         og_image_path.write_bytes(image_file.read())
-        return get_path_str_from_static(og_image_path)
+        return [get_path_str_from_static(og_image_path)]
 
     try:
         pil_save(
@@ -126,7 +124,7 @@ def save_image(name: str, image_file: MediaFileProtocol) -> str:
         if compare_image_sizes(og_image_path, webp_image_path):
             webp_image_path.unlink()
         images = (path for path in (webp_image_path, og_image_path) if path.exists())
-    return ",".join(get_path_str_from_static(image) for image in images)
+    return [get_path_str_from_static(image) for image in images]
 
 
 def _fix_name_suffix(name: str) -> str:
@@ -139,11 +137,11 @@ def _fix_name_suffix(name: str) -> str:
     return f"{start}.{mapped_suffix}" if mapped_suffix else name
 
 
-def save_video(name: str, video: MediaFileProtocol) -> str:
+def save_video(name: str, video: MediaFileProtocol) -> list[str]:
     """Save a video."""
     video_path = BLOG_UPLOAD_FOLDER / name
     video_path.write_bytes(video.read())
-    return get_path_str_from_static(video_path)
+    return [get_path_str_from_static(video_path)]
 
 
 def pil_save(

app/web/html/templates/blog/partials/list_post_media.html

@@ -57,7 +57,7 @@ <h2 class="mt-12 mb-8 text-2xl">Uploaded Media:</h2>
         </p>
       </span>
       <hr class="mb-6" />
-      {% set locations = media_item.locations_to_list() %}
+      {% set locations = media_item.locations %}
       {% if media_item.media_type == "image" and locations.__len__() == 1 %}
         <span
           id="media-html-{{ loop.index }}"