feat!: rm user db_constraint in CourseEnrollment

[johanseto]

Title: Refactor: Remove Database Foreign Key Constraint on User Table in CourseEnrollment

Inspired by the courseware student module's good performance.

openedx-platform/lms/djangoapps/courseware/models.py

Line 95 in b1b59dd

student = models.ForeignKey(User, db_index=True, db_constraint=False, on_delete=models.CASCADE)

1. Context & Architecture

The CourseEnrollment model is a critical piece of the application's core logic, tracking the many-to-many relationship between users and the courses they are enrolled in. Historically, the database schema linked the CourseEnrollment to the central User table using a strict database-level Foreign Key (FK) constraint to enforce referential integrity.

2. The Problem: High-Traffic Lock Contention on the User Table

In scenarios involving mass enrollments or high concurrency (e.g., thousands of students joining a course simultaneously at the start of a semester), the strict database-level Foreign Key constraint introduces a major performance bottleneck.

Whenever an application inserts or updates a CourseEnrollment row, the relational database engine (e.g., MySQL or PostgreSQL) acquires a shared read lock on the corresponding row in the parent User table to guarantee that the referenced user exists. Because the User table is centrally accessed and locked by numerous other services and domains simultaneously, this causes contention.

The resulting lock queues drastically slow down all database transactions touching the User table, causing latency spikes, connection pool exhaustion, and potentially triggering application-wide timeouts and deadlocks during periods of heavy traffic.

3. The Solution

This PR removes the database-level enforcement of the foreign key constraint on the User table within the CourseEnrollment model (e.g., by utilizing db_constraint=False in the Django model field).

To ensure data integrity is maintained at the application level, a safety check has been established within the model layer:

• Application-Level Enforcement: We ensure get_or_create_enrollment is strictly interacting with a valid User object (rather than raw integer IDs).
• Pre-save User Persistence Check: If an unpersisted User object is passed (i.e., one lacking an .id), the application explicitly forces a user.save() before attempting to log the enrollment. This guarantees we have a real identifier mapped in the CourseEnrollment table, thus avoiding a potential IntegrityError due to a null user_id.

4. Impact & Benefits

• Significantly Boosted Write Throughput: Decoupling the writes in CourseEnrollment from locks on the User table allows enrollment inserts/updates to execute concurrently and independently without queuing behind lock states.
• Reduction of Database Contention: Eliminating the shared locks mitigates transaction latency across all services that frequently update or query the core User table.
• Enhanced System Scalability: The database can gracefully process high-volume, concurrent mass-enrollment events without degrading the core user-access performance.

5. Trade-offs & Considerations

• Application-Enforced Integrity: We are trading absolute database-level referential integrity for high availability and write performance. While the database will no longer inherently block deleting a user if child enrollments exist, our application controls handle data validations upstream.
• Orphaned Records: As the database does not enforce cascading rules or restrict deletes automatically anymore for this relationship, logic handling user deletion must safely account for cleaning up or archiving orphaned CourseEnrollment records either inline or via asynchronous background jobs.

Consideration

The model get_or_create receives an user object. So is controlled that user is used to create a course_enrollment without using a random int.

openedx-platform/common/djangoapps/student/models/course_enrollment.py

Lines 375 to 407 in a022b69

	@classmethod
	def get_or_create_enrollment(cls, user, course_key):
	"""
	Create an enrollment for a user in a class. By default *this enrollment
	is not active*. This is useful for when an enrollment needs to go
	through some sort of approval process before being activated. If you
	don't need this functionality, just call `enroll()` instead.
	Returns a CourseEnrollment object.
	`user` is a Django User object. If it hasn't been saved yet (no `.id`
	attribute), this method will automatically save it before
	adding an enrollment for it.
	`course_key` must be a opaque_keys CourseKey object.
	It is expected that this method is called from a method which has already
	verified the user authentication and access.
	If the enrollment is done due to a CourseEnrollmentAllowed, the CEA will be
	linked to the user being enrolled so that it can't be used by other users.
	"""
	# If we're passing in a newly constructed (i.e. not yet persisted) User,
	# save it to the database so that it can have an ID that we can throw
	# into our CourseEnrollment object. Otherwise, we'll get an
	# IntegrityError for having a null user_id.
	assert isinstance(course_key, CourseKey)
	if user.id is None:
	user.save()
	enrollment, __ = cls.objects.get_or_create(
	user=user,

Test

Run migrations

Inspired also by PR nelc#78

similar approach in openedx/completion#443

[openedx-webhooks]

Thanks for the pull request, @johanseto!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Submit a signed contributor agreement (CLA)

⚠️ We ask all contributors to the Open edX project to submit a signed contributor agreement or indicate their institutional affiliation.
Please see the CONTRIBUTING file for more information.

If you've signed an agreement in the past, you may need to re-sign.
See The New Home of the Open edX Codebase for details.

Once you've signed the CLA, please allow 1 business day for it to be processed.
After this time, you can re-run the CLA check by adding a comment below that you have signed it.
If the CLA check continues to fail, you can tag the @openedx/cla-problems team in a comment for further assistance.

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[mphilbrick211]

Hi @johanseto! Welcome, and thank you for this contribution! In order for your CLA check to turn green, you'll need to submit a CLA form. If you are contributing as an individual, please fill out the individual CLA form here.

If you are contributing on behalf of an organization, please have your manager reach out to oscm@axim.org so you may be added to your org's existing entity agreement.

Please let me know if you have any questions. Thanks!