Metadata-Version: 2.4
Name: shardorm
Version: 0.0.2
Summary: A lightweight Python micro-ORM with sharding, replication, and failover layer
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psycopg[binary]>=3.0.0
Requires-Dist: psycopg_pool>=3.0.0
Dynamic: license-file

# ShardORM

> A lightweight Python micro-ORM with automatic PostgreSQL sharding, replication, failover, and schema synchronization.
>
> **No SQLAlchemy. No Alembic. Just SQL.**

ShardORM is built directly on top of **psycopg 3**, **psycopg_pool**, and the Python standard library. It automatically distributes data across PostgreSQL shards while keeping your schema synchronized on every node.

---

## Features

- 🗄️ Automatic PostgreSQL sharding
- 🔄 Consistent hashing with virtual nodes
- 📦 Configurable replication factor
- ⚡ Automatic read failover
- 🌍 Full table replication (`full_sync`)
- 🔀 Online shard rebalancing
- 📜 SQL-based migrations
- 🔒 Optional distributed transactions (PostgreSQL 2PC)
- 🏊 Built-in connection pooling
- 📝 Pure SQL — no query generation

---

## Installation

```bash
pip install shardorm
```

Requirements:

- Python 3.11+
- PostgreSQL 13+
- psycopg 3
- psycopg_pool

---

## Configuration

ShardORM loads its configuration from:

```
./shardorm.config.json
```

or

```
$SHARDORM_CONFIG
```

Generate a template:

```bash
shardorm init-config
```

Example:

```json
{
  "vnodes": 128,
  "replication_factor": 2,

  "shards": [
    {
      "name": "shard1",
      "dsn": "postgresql://user:password@localhost/db1"
    },
    {
      "name": "shard2",
      "dsn": "postgresql://user:password@localhost/db2"
    }
  ],

  "tables": {
    "users": {
      "policy": "sharded",
      "shard_key": "id"
    },

    "countries": {
      "policy": "full_sync"
    }
  }
}
```

---

## Table Policies

### Sharded

Rows are distributed across the cluster using a consistent hash ring.

```json
{
  "users": {
    "policy": "sharded",
    "shard_key": "id"
  }
}
```

### Full Sync

Rows are replicated to every configured shard.

```json
{
  "countries": {
    "policy": "full_sync"
  }
}
```

---

## CLI

```bash
shardorm init-config
shardorm status
shardorm make-migration create_users
shardorm migrate
shardorm add-table users id:UUID:PK email:TEXT
shardorm add-column users age:INTEGER
shardorm drop-table users --yes
shardorm rescale users
shardorm rescale users --apply
```

---

## FastAPI Example

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from shardorm import ShardORM

app = FastAPI(title="ShardORM Example")

db = ShardORM.from_config()


class UserCreate(BaseModel):
    id: str
    name: str
    email: str


@app.on_event("shutdown")
def shutdown():
    db.close()


@app.post("/users")
def create_user(user: UserCreate):
    try:
        result = (
            db.table("users")
            .insert(
                id=user.id,
                data=user.model_dump()
            )
        )

        return {
            "status": "success",
            "write_result": result
        }

    except Exception as e:
        raise HTTPException(500, str(e))


@app.get("/users/{user_id}")
def get_user(user_id: str):
    users = (
        db.table("users")
        .where(id=user_id)
        .select()
    )

    if not users:
        raise HTTPException(404, "User not found")

    return users[0]


@app.get("/cluster/status")
def cluster_status():
    return {
        "shards": db.status()
    }
```

---

## How It Works

```
Shard Key
     │
     ▼
Hash Function
     │
     ▼
Consistent Hash Ring
     │
     ▼
Virtual Nodes
     │
     ▼
Replication Factor
     │
     ▼
Destination Shards
```

Only the required shards are contacted for reads and writes. When new shards are added, only the affected rows are moved during rebalancing.

---

## Two-Phase Commit (Optional)

Enable atomic distributed transactions for a table:

```json
{
  "orders": {
    "policy": "sharded",
    "write_mode": "2pc"
  }
}
```

Internally this uses PostgreSQL's native:

```sql
PREPARE TRANSACTION
COMMIT PREPARED
ROLLBACK PREPARED
```

> PostgreSQL requires `max_prepared_transactions > 0`.

---

## Why ShardORM?

| Feature | ShardORM |
|----------|-----------|
| ORM | Lightweight |
| Pure SQL | ✅ |
| psycopg 3 | ✅ |
| Connection Pooling | ✅ |
| Sharding | ✅ |
| Replication | ✅ |
| Read Failover | ✅ |
| Online Rebalancing | ✅ |
| SQL Migrations | ✅ |
| PostgreSQL 2PC | ✅ |

---

## License

Licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**.
