{"id":4396,"library":"sqlalchemy-mate","title":"SQLAlchemy Mate","description":"SQLAlchemy Mate (sqlalchemy-mate) is a library that extends SQLAlchemy's ORM capabilities, simplifying common CRUD (Create, Read, Update, Delete) operations and session management. It aims to reduce boilerplate code for database interactions. The current version is 2.0.0.3, with recent updates focusing on the 2.x API. Releases often occur for minor bug fixes or feature enhancements within major versions.","status":"active","version":"2.0.0.3","language":"en","source_language":"en","source_url":"https://github.com/MacHu-GWU/sqlalchemy_mate-project","tags":["sqlalchemy","orm","crud","database","productivity"],"install":[{"cmd":"pip install sqlalchemy-mate","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"sqlalchemy-mate is an extension library built on top of SQLAlchemy's ORM.","package":"sqlalchemy","optional":false}],"imports":[{"note":"The declarative base class for SQLAlchemy Mate models, providing extended CRUD functionality.","symbol":"ExtendedBase","correct":"from sqlalchemy_mate import ExtendedBase"},{"note":"A module providing utilities like `extended_session_factory` for simplified session management.","symbol":"sm","correct":"from sqlalchemy_mate import sm"},{"note":"Convenience functions for creating SQLAlchemy engines for various databases (e.g., SQLite, PostgreSQL).","symbol":"engine_factory","correct":"from sqlalchemy_mate import engine_factory"}],"quickstart":{"code":"import os\nfrom sqlalchemy import Column, Integer, String, create_engine\nfrom sqlalchemy_mate import ExtendedBase, sm\n\n# 1. Define your model inheriting from ExtendedBase\nclass User(ExtendedBase):\n    __tablename__ = \"users\"\n    id = Column(Integer, primary_key=True)\n    name = Column(String(50), nullable=False)\n    email = Column(String(50), unique=True, nullable=False)\n\n    def __repr__(self):\n        return f\"<User(id={self.id}, name='{self.name}', email='{self.email}')>\"\n\n# 2. Create an in-memory SQLite engine for demonstration\nengine = create_engine(\"sqlite:///:memory:\", echo=False)\n\n# 3. Create tables based on the metadata\nExtendedBase.metadata.create_all(engine)\n\n# 4. Use sm.extended_session_factory for simplified session management\nwith sm.extended_session_factory(engine) as session:\n    # 5. Create and add new objects\n    user1 = User(name=\"Alice\", email=\"alice@example.com\")\n    user2 = User(name=\"Bob\", email=\"bob@example.com\")\n    session.add_all([user1, user2])\n    session.commit() # Commit changes to the database\n\n    print(\"\\n--- Added Users ---\")\n    print(f\"User 1 ID: {user1.id}\") # IDs are assigned after commit\n    print(f\"User 2 ID: {user2.id}\")\n\n    # 6. Query objects\n    print(\"\\n--- Query All Users ---\")\n    all_users = session.query(User).all()\n    for user in all_users:\n        print(user)\n\n    print(\"\\n--- Query Specific User ---\")\n    alice = session.query(User).filter_by(name=\"Alice\").one_or_none()\n    if alice:\n        print(f\"Found Alice: {alice}\")\n\n    # 7. Update an object\n    if alice:\n        alice.name = \"Alicia\"\n        session.add(alice) # Re-add modified object to session\n        session.commit()\n        print(\"\\n--- Updated User ---\")\n        print(f\"Alice updated to: {session.query(User).filter_by(email='alice@example.com').one_or_none()}\")\n\n    # 8. Delete an object\n    bob = session.query(User).filter_by(name=\"Bob\").one_or_none()\n    if bob:\n        session.delete(bob)\n        session.commit()\n        print(\"\\n--- Deleted User ---\")\n        print(f\"Bob deleted. Remaining users: {session.query(User).all()}\")","lang":"python","description":"This quickstart demonstrates how to define a model using `ExtendedBase`, create an in-memory SQLite database, manage sessions with `sm.extended_session_factory`, and perform basic CRUD operations (create, read, update, delete) on the `User` model."},"warnings":[{"fix":"Review the official documentation and examples for `sqlalchemy-mate` 2.x to update session handling and `ExtendedBase` method calls.","message":"Major API changes occurred in version 2.0.0.0. Users upgrading from 1.x to 2.x will need to refactor their code, especially around session management (now primarily using `sm.extended_session_factory`) and the methods available on `ExtendedBase`.","severity":"breaking","affected_versions":">=2.0.0.0"},{"fix":"Always use the `with` statement for `sm.extended_session_factory` to ensure sessions are properly closed. Explicitly call `session.commit()` after write operations and consider `session.rollback()` in error scenarios.","message":"While `sqlalchemy-mate` simplifies session management with `sm.extended_session_factory`, it's still crucial to understand core SQLAlchemy session mechanics. Improper handling of sessions (e.g., not committing or rolling back transactions, not closing connections in long-running processes) can lead to unexpected data states or connection leaks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Familiarize yourself with SQLAlchemy's official documentation. `sqlalchemy-mate` is best utilized by those who already have a basic grasp of SQLAlchemy's ORM.","message":"SQLAlchemy Mate extends SQLAlchemy; it does not replace it. A foundational understanding of core SQLAlchemy concepts (e.g., engines, metadata, declarative base, relationships, query objects) is still necessary for effective use, especially for complex queries or advanced ORM patterns.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}