93 lines
3.8 KiB
Markdown
93 lines
3.8 KiB
Markdown
---
|
|
type: decision
|
|
status: active
|
|
date: 2026-03-20
|
|
agent_author: "claude"
|
|
tags: [portfolio, database, supabase, orm, prisma]
|
|
related_files:
|
|
- tradingagents/portfolio/supabase_client.py
|
|
- tradingagents/portfolio/repository.py
|
|
- tradingagents/portfolio/migrations/001_initial_schema.sql
|
|
---
|
|
|
|
## Context
|
|
|
|
When designing the Portfolio Manager data layer (Phase 1), the question arose:
|
|
should we use an ORM (specifically **Prisma**) or keep the raw `supabase-py`
|
|
client that the scaffolding already plans to use?
|
|
|
|
The options considered were:
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| **Raw `supabase-py`** (chosen) | Direct Supabase PostgREST client, builder-pattern API |
|
|
| **Prisma Python** (`prisma-client-py`) | Code-generated type-safe ORM backed by Node.js |
|
|
| **SQLAlchemy** | Full ORM with Core + ORM layers, Alembic migrations |
|
|
|
|
## The Decision
|
|
|
|
**Use raw `supabase-py` without an ORM for the portfolio data layer.**
|
|
|
|
The data access layer (`supabase_client.py`) wraps the Supabase client directly.
|
|
Our own `Portfolio`, `Holding`, `Trade`, and `PortfolioSnapshot` dataclasses
|
|
provide the type-safety layer; serialisation is handled by `to_dict()` /
|
|
`from_dict()` on each model.
|
|
|
|
## Why Not Prisma
|
|
|
|
1. **Node.js runtime dependency** — `prisma-client-py` uses Prisma's Node.js
|
|
engine at code-generation time. This adds a non-Python runtime requirement
|
|
to a Python-only project.
|
|
|
|
2. **Conflicts with Supabase's migration tooling** — the project already uses
|
|
Supabase's SQL migration files (`migrations/001_initial_schema.sql`) and the
|
|
Supabase dashboard for schema changes. Prisma's `prisma migrate` maintains
|
|
its own shadow database and migration state, creating two competing systems.
|
|
|
|
3. **Code generation build step** — every schema change requires running
|
|
`prisma generate` before the Python code works. This complicates CI, local
|
|
setup, and agent-driven development.
|
|
|
|
4. **Overkill for 4 tables** — the portfolio schema has exactly 4 tables with
|
|
straightforward CRUD. Prisma's relationship traversal and complex query
|
|
features offer no benefit here.
|
|
|
|
## Why Not SQLAlchemy
|
|
|
|
1. **Not using a local database** — the database is managed by Supabase (hosted
|
|
PostgreSQL). SQLAlchemy's connection-pooling and engine management are
|
|
designed for direct database connections, which bypass Supabase's PostgREST
|
|
API and Row Level Security.
|
|
|
|
2. **Extra dependency** — SQLAlchemy + Alembic would be significant new
|
|
dependencies for a non-DB-heavy app.
|
|
|
|
## Why Raw `supabase-py` Is Sufficient
|
|
|
|
- `supabase-py` provides a clean builder-pattern API:
|
|
`client.table("holdings").select("*").eq("portfolio_id", id).execute()`
|
|
- Our dataclasses already provide compile-time type safety and lossless
|
|
serialisation; the client only handles transport.
|
|
- Migrations are plain SQL files — readable, versionable, Supabase-native.
|
|
- `SupabaseClient` is a thin singleton wrapper that translates HTTP errors into
|
|
domain exceptions — this gives us the ORM-like error-handling benefit without
|
|
the complexity.
|
|
|
|
## Constraints
|
|
|
|
- **Do not** add an ORM dependency (`prisma-client-py`, `sqlalchemy`, `tortoise-orm`)
|
|
to `pyproject.toml` without revisiting this decision.
|
|
- **Do not** bypass `SupabaseClient` by importing `supabase` directly in other
|
|
modules — always go through `PortfolioRepository`.
|
|
- If the schema grows beyond ~10 tables or requires complex multi-table joins,
|
|
revisit this decision and consider SQLAlchemy Core (not the ORM layer) with
|
|
direct `asyncpg` connections.
|
|
|
|
## Actionable Rules
|
|
|
|
- All DB access goes through `PortfolioRepository` → `SupabaseClient`.
|
|
- Migrations are `.sql` files in `tradingagents/portfolio/migrations/`, run via
|
|
the Supabase SQL Editor or `supabase db push`.
|
|
- Type safety comes from dataclass `to_dict()` / `from_dict()` — not from a
|
|
code-generated ORM schema.
|