# pyteledb

A **Telegram-native embedded database** for Telegram bots.

## What is pyteledb?

pyteledb is a Python library that implements a persistence abstraction where **Telegram itself is the storage layer**. Instead of using an external database, your data lives directly in Telegram messages.

### Core Concepts

| Telegram Concept | pyteledb Mapping |
|-----------------|------------------|
| Channel/Group | Database |
| Pinned Message | Root Index |
| Message | Record |
| Message Edit | Record Update |
| File Attachment | Large Payload |

## Why pyteledb?

- **Zero infrastructure** — No database server to manage
- **Built-in persistence** — Telegram stores your data
- **Human-inspectable** — View your data directly in Telegram
- **Bot API only** — No MTProto complexity

## Quick Example

```python
from pyteledb import TelegramDatabase, DatabaseConfig

config = DatabaseConfig(
    bot_token="YOUR_BOT_TOKEN",
    chat_id=-100123456789,
)

async with TelegramDatabase(config) as db:
    await db.initialize()
    
    # CRUD operations
    record = await db.insert({"name": "Alice"})
    await db.update(record.id, {"name": "Bob"})
    await db.delete(record.id)
```

## Target Audience

pyteledb is designed for:

- **Small to medium Telegram bots** with predictable workloads
- **Developer tooling** that needs simple persistence
- **Projects requiring human-inspectable data**

## Non-Goals

pyteledb intentionally does NOT provide:

- SQL/NoSQL feature parity
- High-throughput capabilities
- Complex query languages
- Multi-service orchestration

---

Ready to get started? Head to the [Getting Started](/getting-started) guide.
