Hi, thanks a lot for the guidance!

I now understand that the recommended way would be to use a UserDefinedType for hierarchyid, and that I can customize how it renders in Alembic by providing a repr() so migrations generate properly. The link to the autogenerate docs was helpful.

I’m still wondering about a couple of points before I commit to this direction:

Alternative with self-referencing FK:
Would it be more practical to avoid hierarchyid altogether and just model the tree using a self-referencing foreign key (e.g. parent_id referencing the same table)?

If I go that route, what’s the best way to optimize tree queries (e.g. retrieving all descendants or computing hierarchy depth) in SQL Server? I’m aware that recursive CTEs are an option, but I’m not sure how they compare performance-wise to hierarchyid for moderate-sized trees.

SQLModel vs. SQLAlchemy directly:
I suspect that part of my problem is that I’m layering SQLModel on top of SQLAlchemy, which may cause Alembic to default to String when it doesn’t recognize a custom type. Do you think I’d be better off using plain SQLAlchemy here, at least for this table? Or is UserDefinedType + a correct repr() usually enough even when SQLModel is in the mix?

Any advice on whether it’s worth sticking with hierarchyid (and investing in a custom type) versus going with a more standard self-referencing FK model would help me choose the right approach.

Thanks again!

Alternative with self-referencing FK: Would it be more practical to avoid hierarchyid altogether and just model the tree using a self-referencing foreign key (e.g. parent_id referencing the same table)?

that's normally what I do since this is a well understood design (adjacency list) and is very simple....

If I go that route, what’s the best way to optimize tree queries (e.g. retrieving all descendants or computing hierarchy depth) in SQL Server? I’m aware that recursive CTEs are an option, but I’m not sure how they compare performance-wise to hierarchyid for moderate-sized trees.

If you are using adjacency list, there's really two options. There's the recursive CTE thing. Or, if this data is being written and read in a very particular way, meaning, particular hierarchies you tend to pull all into memory in any case and they all correspond to some other non-hierarchical identifier, you just pull the whole list of rows into memory and organize them in memory. I've never had an application where I needed to query a recursive hierarchy as a single giant tree where I am doing all the tree traversal operations in SQL among millions of nodes. If I did need that, I would absolutely use a graph database that's designed for that.

hierarchyid looks to be some version of "materialized path". we have an very very old example of that here: https://docs.sqlalchemy.org/en/20/_modules/examples/materialized_paths/materialized_paths.html

SQLModel vs. SQLAlchemy directly: I suspect that part of my problem is that I’m layering SQLModel on top of SQLAlchemy, which may cause Alembic to default to String when it doesn’t recognize a custom type. Do you think I’d be better off using plain SQLAlchemy here, at least for this table? Or is UserDefinedType + a correct repr() usually enough even when SQLModel is in the mix?

if SQLModel lets you put a SQLAlchemy type object in a mapping, that should be all you need