From 14f4a097a71bb514da33690fa5a6baac198e5e58 Mon Sep 17 00:00:00 2001 From: sarina Date: Tue, 7 Apr 2026 15:07:40 -0400 Subject: [PATCH 1/3] Add docs on db technologies and postgresql support Co-authored-by: Claude --- source/site_ops/concepts/databases.rst | 86 +++++++++++++ source/site_ops/how-tos/index.rst | 1 + source/site_ops/how-tos/use_postgresql.rst | 137 +++++++++++++++++++++ 3 files changed, 224 insertions(+) create mode 100644 source/site_ops/concepts/databases.rst create mode 100644 source/site_ops/how-tos/use_postgresql.rst diff --git a/source/site_ops/concepts/databases.rst b/source/site_ops/concepts/databases.rst new file mode 100644 index 000000000..c3a7e7dbe --- /dev/null +++ b/source/site_ops/concepts/databases.rst @@ -0,0 +1,86 @@ +.. _Open edX Databases: + +Open edX Platform Database and Search Technologies +################################################## + +.. tags:: site operator, concept + +The Open edX platform uses several databases and search backends, each +serving different purposes. + +Relational (SQL) +**************** + +**MySQL** + The long-standing primary relational database for most services (LMS, + CMS/Studio), storing users, courses, enrollments, and grades. + +**PostgreSQL** + Newly supported as of the Verawood release, with migrations updated to + make the Open edX platform compatible across both MySQL and PostgreSQL. + Changes include dynamic SQL generation based on the database engine, + cross-database field type handling, and custom psycopg2 adapter + registration for Open edX's OpaqueKey types like ``CourseLocator``. A + community-developed Tutor plugin (`tutor-contrib-postgresql `_) + supports PostgreSQL-based Tutor deployments. See :ref:`use postgresql`. + +**SQLite** + Used in local development and testing environments. + +NoSQL / Document +**************** + +**MongoDB** + Used to store course content structure in Studio. There is ongoing work to + migrate away from MongoDB toward MySQL via the Learning Core + (`openedx-learning `_) initiative. + +Caching / In-Memory +******************* + +**Redis** + Used for caching, session storage, and Celery task queuing. Superseded + Memcached in modern deployments. + +**Memcached** + Legacy caching layer, largely replaced by Redis. + +Search +****** + +**Meilisearch** + The current primary search engine for content library and course + authoring search (introduced in Quince), used by the Authoring MFE for + course and library content discovery, as well as the Catalog MFE for course searching. + +**Typesense** + A supported alternative search backend for site operators, attractive in + part because it supports raft-based clustering for high availability — a + limitation that has been noted with Meilisearch. See :ref:`Use Typesense search backend`. + + .. note:: Typesense is currently (as of Verawood) only supported for LMS searching, _not_ Studio/libraries. + +**Elasticsearch / OpenSearch** + Used for older LMS-level search (course catalog, user search). OpenSearch + is the current preferred variant, with ongoing community discussion about + whether to deprecate it in favor of lighter-weight alternatives. + +Message Broker +************** + +**Redis** (also serves this role) **or RabbitMQ** + Used as a Celery broker for background task processing. + +.. seealso:: + + :ref:`Use Typesense search backend` + + :ref:`use postgresql` + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +| 2025-04-10 | sarina | Verawood | Pass | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/source/site_ops/how-tos/index.rst b/source/site_ops/how-tos/index.rst index 7e726cc9e..310287357 100644 --- a/source/site_ops/how-tos/index.rst +++ b/source/site_ops/how-tos/index.rst @@ -4,6 +4,7 @@ Site Operators: How-tos .. tags:: site operator, how-to .. toctree:: + :maxdepth: 1 :glob: * diff --git a/source/site_ops/how-tos/use_postgresql.rst b/source/site_ops/how-tos/use_postgresql.rst new file mode 100644 index 000000000..5272583aa --- /dev/null +++ b/source/site_ops/how-tos/use_postgresql.rst @@ -0,0 +1,137 @@ +.. _use postgresql: + +Using PostgreSQL as the Relational Database Backend +################################################### + +.. note:: + + PostgreSQL support was introduced in the Verawood release. The Tutor plugin + that enables this feature (`tutor-contrib-postgresql `) + is under active development. Migration from an existing MySQL installation is + not yet supported. See `Current PostgreSQL Limitations`_ for details. + +PostgreSQL is a powerful open source relational database system with a strong +reputation for reliability, standards compliance, and extensibility. It is a +common choice for production web applications and is widely supported by +managed cloud database services such as Amazon RDS, Google Cloud SQL, and +Azure Database for PostgreSQL. + +Historically, the Open edX platform used MySQL as its only supported relational +database. As of the Verawood release, PostgreSQL is also supported as a +relational database backend for the Open edX platform, thanks to community +contributions that updated the platform's Django migrations and field adapters +to work correctly across both database engines. + +Prerequisites +************* + +- A Tutor-based Open edX deployment (local or Kubernetes) +- Tutor Verawood or later +- A fresh Open edX installation (see `Current PostgreSQL Limitations`_) + +Installation +************ + +PostgreSQL support is provided via the community-maintained Tutor plugin +``tutor-contrib-postgresql``, authored by `@qasimgulzar +`_. + +.. warning:: + + This plugin is under active development and has not yet reached a stable + release. Use in production environments is at your own risk. Review the + `plugin repository `_ + for the latest status before proceeding. + +Step 1: Install the plugin +========================== + +.. code-block:: bash + + pip install git+https://github.com/qasimgulzar/tutor-contrib-postgresql + +Step 2: Enable the plugin +========================= + +.. code-block:: bash + + tutor plugins enable postgresql + +Step 3: Build the Open edX image +================================= + +The Open edX image must be rebuilt to include the necessary PostgreSQL client +libraries and Python packages (``psycopg2``). + +.. code-block:: bash + + tutor images build openedx + +Step 4: Launch the platform +============================ + +.. code-block:: bash + + tutor local launch + +This will initialize a fresh Open edX database in PostgreSQL and run all +Django migrations against it. + +.. _Current PostgreSQL Limitations: + +Current Limitations +******************* + +Fresh installations only +======================== + +At this time, PostgreSQL support is available for fresh Open edX installations +only. There is no supported or documented migration path from an existing MySQL +database to PostgreSQL. Operators with an existing MySQL-backed deployment who +wish to switch to PostgreSQL will need to wait for migration tooling and +documentation to be developed. + +If you are interested in contributing to or tracking the development of +MySQL-to-PostgreSQL migration support, see the `tutor-contrib-postgresql +repository `_ and the +`original platform pull request +`_. + +Known rough edges +================= + +PostgreSQL support was introduced with the following known limitations that may +be addressed in subsequent releases. + +- Opaque key adapter coverage for v2 content libraries (beta libraries in + Studio) may be incomplete. Runtime errors related to ``LearningContextKey`` + or ``UsageKey`` serialization, if encountered, should be reported to the + plugin maintainer. +- The ``tutor-contrib-postgresql`` plugin does not yet have a stable release. + Install directly from the GitHub repository as shown above. + +Getting Help +************ + +PostgreSQL support for the Open edX platform is a community-driven effort. If +you encounter issues or have questions: + +- Open an issue on the `tutor-contrib-postgresql repository + `_ +- Post on the `Open edX discussion forum `_ + + +.. seealso:: + + :ref:`Open edX Databases` + + `Tutor PostgreSQL plugin ` + + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +| 2025-04-10 | sarina | Verawood | Pass | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file From 7b48377d59098d3c0d8f80f6ba73456c90985d5c Mon Sep 17 00:00:00 2001 From: sarina Date: Tue, 7 Apr 2026 16:38:21 -0400 Subject: [PATCH 2/3] Fix: typos --- source/site_ops/how-tos/use_postgresql.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/site_ops/how-tos/use_postgresql.rst b/source/site_ops/how-tos/use_postgresql.rst index 5272583aa..a835281b0 100644 --- a/source/site_ops/how-tos/use_postgresql.rst +++ b/source/site_ops/how-tos/use_postgresql.rst @@ -1,12 +1,12 @@ .. _use postgresql: -Using PostgreSQL as the Relational Database Backend -################################################### +Use PostgreSQL as the Relational Database Backend +################################################# .. note:: PostgreSQL support was introduced in the Verawood release. The Tutor plugin - that enables this feature (`tutor-contrib-postgresql `) + that enables this feature (`tutor-contrib-postgresql `_) is under active development. Migration from an existing MySQL installation is not yet supported. See `Current PostgreSQL Limitations`_ for details. From e75465a80642d3709d091532515877c231778a3c Mon Sep 17 00:00:00 2001 From: sarina Date: Tue, 7 Apr 2026 16:39:00 -0400 Subject: [PATCH 3/3] Fix: typos --- source/site_ops/how-tos/use_postgresql.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/site_ops/how-tos/use_postgresql.rst b/source/site_ops/how-tos/use_postgresql.rst index a835281b0..0670205b4 100644 --- a/source/site_ops/how-tos/use_postgresql.rst +++ b/source/site_ops/how-tos/use_postgresql.rst @@ -125,7 +125,7 @@ you encounter issues or have questions: :ref:`Open edX Databases` - `Tutor PostgreSQL plugin ` + `Tutor PostgreSQL plugin `_ **Maintenance chart**