Metadata-Version: 2.4
Name: strands_session_sql
Version: 0.1.0
Summary: SQL session manager (storage backend) for Strands Agents via SQLAlchemy — one provider for SQLite, PostgreSQL, MySQL, and more
Project-URL: Homepage, https://github.com/skamalj/strands-agents-session
Project-URL: Repository, https://github.com/skamalj/strands-agents-session.git
Author-email: Kamal <skamalj@github.com>
Keywords: agent-state,mysql,persistence,postgres,postgresql,session,sql,sqlalchemy,sqlite,strands,strands-agents
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: strands-agents
Requires-Dist: strands-agents-session>=0.1.0
Provides-Extra: mysql
Requires-Dist: pymysql>=1.1; extra == 'mysql'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Description-Content-Type: text/markdown

# strands-session-sql

SQL **session manager** (storage backend) for [Strands Agents](https://strandsagents.com), via **SQLAlchemy**. One provider for any SQLAlchemy-supported database — **SQLite, PostgreSQL, MySQL**, and more — selected purely by connection URL. The Python equivalent of "JDBC backends": one API, many databases.

Part of the [`strands-agents-session`](https://pypi.org/project/strands-agents-session/) family — it implements the base `SessionStorage` interface, so all the Strands session-repository logic comes from the core.

> **Storage only, by design.** Message *pruning* in Strands is a `ConversationManager` concern, decoupled from storage. This package does not prune.

## Installation

```bash
pip install strands-session-sql              # SQLite works out of the box (built-in)
pip install "strands-session-sql[postgres]"  # + psycopg (PostgreSQL)
pip install "strands-session-sql[mysql]"     # + pymysql (MySQL)
# or via the family extra:
pip install "strands-agents-session[sql]"
```

**Requires Python 3.10+.** SQLite needs no driver; other databases need their SQLAlchemy driver (the extras above).

## Quick start

```python
from strands import Agent
from strands_session_sql import SQLSessionManager

# SQLite (zero infra)
agent = Agent(session_manager=SQLSessionManager(
    session_id="user-123", url="sqlite:///sessions.db",
))

# PostgreSQL
mgr = SQLSessionManager(session_id="user-123",
                        url="postgresql+psycopg://user:pass@localhost:5432/mydb")

# MySQL
mgr = SQLSessionManager(session_id="user-123",
                        url="mysql+pymysql://user:pass@localhost:3306/mydb")
```

The table is created automatically if it does not exist.

## API

### `SQLSessionManager(session_id, *, url=None, table_name="strands_sessions", engine=None)`

| Parameter | Description |
|---|---|
| `session_id` | Session identifier |
| `url` | SQLAlchemy connection URL |
| `table_name` | Table name (default `strands_sessions`; created if absent) |
| `engine` | Optional pre-built SQLAlchemy `Engine` to reuse — supply this **or** `url` |

## Authentication

Auth is carried in the connection URL (user/password, host, TLS query args), or via a pre-built SQLAlchemy `Engine` for advanced setups (custom pools, SSL, IAM plugins):

```text
postgresql+psycopg://user:pass@host:5432/db?sslmode=require
mysql+pymysql://user:pass@host/db?ssl_ca=/path/ca.pem
sqlite:///sessions.db
```

## Data model

A single table with a composite primary key `(pk, sk)` and a `data` column:

```sql
CREATE TABLE strands_sessions (
    pk VARCHAR(255) NOT NULL,
    sk VARCHAR(255) NOT NULL,
    data TEXT NOT NULL,
    PRIMARY KEY (pk, sk)
);
```

`list_messages(offset, limit)` maps to `WHERE pk = ? AND sk >= ? ORDER BY sk LIMIT ?`. Message sort keys are zero-padded so lexical order matches numeric order.

## License

MIT
