# Getting Started

This guide will help you set up pyteledb and create your first Telegram-native database.

## Prerequisites

- Python 3.10 or higher
- A Telegram Bot Token (get one from [@BotFather](https://t.me/BotFather))
- A Telegram channel or group where your bot is an admin

## Installation

```bash
pip install pyteledb
```

For SQLite cache support:

```bash
pip install pyteledb[sqlite]
```

## Setup

### 1. Create a Telegram Channel/Group

1. Create a new channel or group in Telegram
2. Add your bot as an administrator
3. Get the chat ID (you can use [@RawDataBot](https://t.me/RawDataBot))

### 2. Initialize the Database

```python
import asyncio
from pyteledb import TelegramDatabase, DatabaseConfig

async def main():
    # Configure the database
    config = DatabaseConfig(
        bot_token="YOUR_BOT_TOKEN",
        chat_id=-100123456789,  # Your channel/group ID
        db_name="my_first_db",
    )

    # Create and initialize
    async with TelegramDatabase(config) as db:
        root = await db.initialize()
        print(f"Database initialized: {root.db_name}")
        print(f"Database ID: {root.db_id}")

asyncio.run(main())
```

When you run this, pyteledb will:
1. Create a root index message in your channel
2. Pin that message (this is your database entry point)

## Basic Operations

### Insert Records

```python
# Insert a single record
record = await db.insert({
    "user_id": 12345,
    "name": "Alice",
    "score": 100,
})
print(f"Created: {record.id}")
```

### Read Records

```python
# Get by ID
record = await db.get(record_id)
print(record.payload)  # {"user_id": 12345, "name": "Alice", "score": 100}
```

### Update Records

```python
# Update with new data
updated = await db.update(record_id, {
    "user_id": 12345,
    "name": "Alice",
    "score": 150,  # Updated score
})
print(f"New version: {updated.version}")
```

### Delete Records

```python
# Delete a record
await db.delete(record_id)
```

## Configuration Options

```python
config = DatabaseConfig(
    # Required
    bot_token="YOUR_BOT_TOKEN",
    chat_id=-100123456789,

    # Optional
    db_name="my_database",      # Database name (default: "pyteledb")
    cache_enabled=True,         # Enable local caching (default: True)
    cache_ttl=300.0,            # Cache TTL in seconds (default: 300)
    cache_max_size=1000,        # Max cached records (default: 1000)
    use_locking=True,           # Enable write locking (default: True)
    lock_ttl=30.0,              # Lock timeout in seconds (default: 30)
)
```

## What's Next?

- Learn about the [Architecture](/architecture) behind pyteledb
- Explore the [API Reference](/api/database) for detailed documentation
- Check out the [examples](https://github.com/SilentDemonSD/pyteledb/tree/main/examples) directory
