Add SQLAlchemy migration plan for mdapi_sql services

[MrIbrahem]

This change adds a detailed and professional migration plan document in Arabic at docs/sql_migration_plan.md to guide the migration from the legacy mdapi_sql database services to the new SQLAlchemy-based ORM system.

---

PR created automatically by Jules for task 17410860539707740453 started by @MrIbrahem

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 08a9513f-5f02-4e28-8481-8951479f0361

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sqlalchemy-migration-plan-17410860539707740453

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request introduces a detailed migration plan (docs/sql_migration_plan.md) to transition from legacy raw SQL services to a new SQLAlchemy ORM-based service layer. The review feedback identifies several critical discrepancies between the proposed migration mappings and the actual signatures and behaviors of the existing SQLAlchemy services. Specifically, the reviewer notes that: (1) qid_others_service.py does not currently support double-checking both tables during insertion as described; (2) get_db_users() is mapped to user_page_service.py which manages a different table (pages_users instead of users); and (3) proposed calls to update_page for updating targets or setting deletion flags will raise TypeErrors due to missing required positional arguments (title and target).

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The note states that the alternative functions insert or add_qid_other insert and check for pre-existence in both tables (qids and qids_others).

However, looking at the current implementation of qid_others_service.py, both insert and add_qid_other only query the qids_others table and do not perform any checks on the qids table (unlike the legacy add_qid in sql_qids_others.py which used a NOT EXISTS clause on both tables).

To prevent duplicate or inconsistent records across tables, please update the note to clarify that the current service functions do not support this double-check yet, and indicate that the service needs to be updated before migration.

Suggested change

	| `add_qid(title, qid)` | `insert(title, qid)` أو `add_qid_other(title, qid)` | تقوم بالإدخال والتحقق من عدم الوجود المسبق في كلا الجدولين. |
	| add_qid(title, qid) | دالة جديدة أو تحديث الخدمة الحالية | تقوم بالإدخال والتحقق من عدم الوجود المسبق في كلا الجدولين (تحتاج الخدمة الحالية للتحديث لدعم الفحص المزدوج). |

[gemini-code-assist]

The legacy function get_db_users() queries the users table (which contains approved/registered usernames), whereas the proposed service pages/user_page_service.py manages the pages_users table (represented by UserPageRecord, which contains page translation records by users).

These two tables have completely different structures and purposes. It is highly recommended to point to a dedicated user service (e.g., users/user_service.py or similar) instead of directing developers to user_page_service.py.

Suggested change

	| `get_db_users()` | `pages/user_page_service.py` أو دالة مستخدم مخصصة | جلب قائمة أسماء المستخدمين المميزين المسجلين في جدول `users`. |
	| get_db_users() | خدمة مستخدمين مخصصة (مثال: users/user_service.py) | جلب قائمة أسماء المستخدمين المميزين المسجلين في جدول users. |

[gemini-code-assist]

The proposed function update_page in page_service.py has the following signature:

def update_page(
    page_id: int,
    title: str,
    target: str,
    **kwargs: Any,
) -> PageRecord:

Both title and target are required positional arguments.

Calling update_page(page_id=iid, target=new_target) as suggested in the table will raise a TypeError because the required title argument is missing.

Please clarify this in the notes, or suggest using set_page_target after retrieving the record, or modify update_page to make those parameters optional.

Suggested change

	| `set_target_where_id(new_target, iid)` | `pages/page_service.py` -> `update_page(page_id=iid, target=new_target)` | تعديل السجل وتحديث حقل `target` وحقل `pupdate` تلقائياً عبر الـ ORM. |
	| set_target_where_id(new_target, iid) | pages/page_service.py -> set_page_target(...) بعد جلب السجل | تعديل السجل وتحديث حقل target وحقل pupdate تلقائياً عبر الـ ORM (يتطلب جلب كائن PageRecord أولاً). |

[gemini-code-assist]

Similar to the previous comment, update_page requires both title and target as positional arguments.

Calling update_page(page_id=iid, deleted=1) will fail with a TypeError.

It is recommended to suggest creating a dedicated soft-delete function (e.g., delete_page_by_id(page_id)) or updating update_page to support partial updates.

Suggested change

	| `set_deleted_where_id(iid)` | `pages/page_service.py` -> `update_page(page_id=iid, deleted=1)` | وسم الصفحة كـ "محذوفة" من خلال تحديث حقل `deleted` المقابل للـ ID المعطى. |
	| set_deleted_where_id(iid) | pages/page_service.py -> دالة جديدة أو تحديث جزئي | وسم الصفحة كـ "محذوفة" من خلال تحديث حقل deleted المقابل للـ ID المعطى (يتطلب دالة تدعم التحديث الجزئي دون إلزامية العنوان والهدف). |