Improve SQLAlchemy Usage and Documentation for New Developers

[lasryariel]

• Parent Issue 07.03 Milestone Tracker | Enhance codebase readability and documentation #771

Overview

Our current use of SQLAlchemy as the connection library has been identified as a potential burden for new developers, particularly in understanding how to manage database connections, update models, and modify API contracts. To alleviate these challenges, we need to improve our documentation and standardize how SQLAlchemy is used within the project. This will help new developers more easily update API contracts and interact with the database.

Action Items

1. Document SQLAlchemy Setup and Usage

   • Create comprehensive documentation on how SQLAlchemy is set up and used in the project.
   • Include detailed examples on common tasks such as:
     • Creating and updating models.
     • Managing sessions and transactions.
     • Handling migrations and schema changes.

2. Document API Contract Updates

   • Provide step-by-step instructions on how to update API contracts when modifying database models or queries.
   • Include examples of typical changes, such as adding new fields to a model or changing query logic, and how these should be reflected in the API.

3. Standardize SQLAlchemy Practices

   • Review the current usage of SQLAlchemy across the codebase to identify inconsistencies or areas for improvement.
   • Standardize the approach to session management, model definition, and query writing.
   • Document these standards to ensure consistency and ease of understanding for new developers.

4. Documentation for Onboarding New Developers

   • Create a SQLAlchemy onboarding guide specifically designed for new developers, highlighting key concepts and practices.

Resources/Instructions

A well-documented and standardized approach to using SQLAlchemy, making it easier for new developers to understand and contribute to the project, particularly when updating API contracts or working with the database.