SQLAlchemy allow null as ForeignKey
your ORM definition looks fine, DocumentModel.entity_id is nullable indeed. What I would do in this case is check the actual table definition in MySQL and make sure it corresponds with your ORM definition, e.g.
-- make sure DocumentModel.entity_id is nullable :SHOW CREATE TABLE DocumentModel\G UPDATE DocumentModel.entity_id SET entity_id = NULL WHERE entity_id = XXX;
null is not valid for a child row. As an alternative, make a parent that is only used for 'null' children and set key to that id. I don't really understand the purpose of this as you do not want orphan records. If the relationship is not really 1 to many with a parent child relationship, then you should consider a different relationship type or maybe add a field to make child records inactive.