feat(session): add DatabaseSessionManager for PostgreSQL/MySQL/SQLite support

[andormarkus]

Description

This PR adds comprehensive documentation for the new DatabaseSessionManager feature, which enables SQL database persistence for agent sessions (PostgreSQL, MySQL, and SQLite).

The documentation aligns with SDK PR #1031 and will be ready to merge once that PR is released.

Key Documentation Added:

1. User Guide - Session Management section with detailed DatabaseSessionManager coverage
2. Example Code - Working Python example demonstrating basic and production usage patterns
3. Navigation Updates - Added to examples menu and overview page

Type of Change

• New content addition
• Content update/revision
• Structure/organization improvement
• Typo/formatting fix
• Bug fix
• Other (please describe):

Motivation and Context

The DatabaseSessionManager provides a cloud-agnostic, cost-effective alternative to S3-based session storage for production deployments. This documentation enables users to:

• Understand when and why to use database sessions
• Set up database schema with Alembic migrations
• Implement basic and production-grade connection pooling patterns
• Choose between PostgreSQL, MySQL, and SQLite based on their needs

Areas Affected

Modified Files:

• docs/user-guide/concepts/agents/session-management.md

  • Added DatabaseSessionManager as third built-in session manager
  • Comprehensive setup guide with Alembic migration instructions
  • Database schema structure tables
  • Basic and production usage examples
  • Connection string examples for all supported databases

• docs/examples/README.md

  • Added Database Session Manager to Python examples list

• mkdocs.yml

  • Added Database Session Manager to Examples navigation

New Files:

• docs/examples/python/database_session_manager.py

  • Basic usage example with session persistence demo
  • Production usage example with shared SQLAlchemy engine

• docs/examples/python/database_session_manager.md

  • Example documentation with overview table
  • Prerequisites and installation instructions
  • Code examples for basic and production usage
  • Supported databases reference

Implementation Details

Documentation Structure:

User Guide Section:

• Installation instructions (pip install strands-agents[database])
• Database Schema Setup (3-step Alembic guide)
• Database Schema Structure (detailed table definitions)
• Basic Usage (simple connection string)
• Production Usage (shared engine with connection pooling)
• Supported Database Connection Strings

Example Structure:

• Link to Python code file (following existing pattern)
• Overview table with key features
• Working code demonstrating session persistence
• Production pattern with connection pooling for multiple users

Design Decisions:

1. Concise Documentation: Kept section length similar to S3SessionManager for consistency
2. Practical Focus: Emphasized real-world usage patterns (basic + production)
3. Clear Prerequisites: Alembic setup clearly documented as required step
4. Schema Transparency: Detailed table structures for understanding data model

Checklist

• I have read the CONTRIBUTING document
• My changes follow the project's documentation style
• I have tested the documentation locally using mkdocs serve
• Links in the documentation are valid and working
• Images/diagrams are properly sized and formatted (N/A - no images)
• All new and existing tests pass

Additional Notes

• The DatabaseSessionManager API reference line is intentionally omitted from docs/api-reference/session.md until the SDK feature is released to PyPI
• Example code has been tested and produces expected output showing session persistence
• Documentation follows the same structure and style as FileSessionManager and S3SessionManager sections
• Branch name: feature/database-session-manager matches the SDK PR branch

Related SDK PR: strands-agents/sdk-python#1031

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.