344 lines
9.9 KiB
Markdown
344 lines
9.9 KiB
Markdown
# Supabase Connector
|
||
|
||
Простой и удобный Python коннектор для работы с [Supabase](https://supabase.com).
|
||
|
||
## 🎯 О проекте
|
||
|
||
Этот проект предоставляет удобную обертку над официальным Python клиентом Supabase, упрощая базовые операции с базой данных и Storage.
|
||
|
||
## ✨ Возможности
|
||
|
||
- ✅ Простое подключение к Supabase через переменные окружения
|
||
- 📊 CRUD операции (Create, Read, Update, Delete)
|
||
- 🔍 Фильтрация и лимитирование результатов
|
||
- 📦 Работа с Supabase Storage
|
||
- 🛡️ Обработка ошибок
|
||
- 🎨 Чистый и понятный API
|
||
|
||
## 📋 Требования
|
||
|
||
- Python 3.8+
|
||
- Аккаунт Supabase (бесплатный или платный)
|
||
|
||
## 🚀 Установка
|
||
|
||
### Вариант 1: Клонирование репозитория
|
||
|
||
```bash
|
||
git clone https://github.com/yourusername/supabase-connector.git
|
||
cd supabase-connector
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### Вариант 2: Установка как пакет (в разработке)
|
||
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
## ⚙️ Настройка
|
||
|
||
1. Создайте файл `.env` в корне проекта:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. Заполните данными из вашего Supabase проекта:
|
||
|
||
```env
|
||
SUPABASE_URL=https://your-project-id.supabase.co
|
||
SUPABASE_KEY=your_anon_key
|
||
```
|
||
|
||
**Где найти эти данные:**
|
||
1. Откройте [Supabase Dashboard](https://app.supabase.com)
|
||
2. Выберите ваш проект
|
||
3. Перейдите в Settings → API
|
||
4. Скопируйте **Project URL** и **anon/public key**
|
||
|
||
## 📖 Использование
|
||
|
||
### Базовый пример
|
||
|
||
```python
|
||
from supabase import SupabaseManager
|
||
|
||
# Инициализация
|
||
sb = SupabaseManager()
|
||
|
||
# Получение данных
|
||
users = sb.select(table="users", limit=10)
|
||
print(f"Найдено пользователей: {len(users)}")
|
||
|
||
# Добавление записи
|
||
new_user = sb.insert(
|
||
table="users",
|
||
data={
|
||
"name": "Тимур",
|
||
"email": "timur@example.com",
|
||
"age": 28
|
||
}
|
||
)
|
||
print(f"Создан пользователь с ID: {new_user.get('id')}")
|
||
```
|
||
|
||
### Фильтрация данных
|
||
|
||
```python
|
||
# Получить пользователей с определенным возрастом
|
||
users_30 = sb.select(
|
||
table="users",
|
||
filters={"age": 30}
|
||
)
|
||
|
||
# Получить только имена и email
|
||
users = sb.select(
|
||
table="users",
|
||
columns="name, email",
|
||
limit=5
|
||
)
|
||
```
|
||
|
||
### Обновление записей
|
||
|
||
```python
|
||
# Обновить возраст пользователя с ID=1
|
||
updated = sb.update(
|
||
table="users",
|
||
data={"age": 31},
|
||
filters={"id": 1}
|
||
)
|
||
```
|
||
|
||
### Удаление записей
|
||
|
||
```python
|
||
# Удалить пользователя с ID=1
|
||
deleted = sb.delete(
|
||
table="users",
|
||
filters={"id": 1}
|
||
)
|
||
```
|
||
|
||
### Работа с Storage
|
||
|
||
```python
|
||
# Загрузить файл
|
||
with open("avatar.png", "rb") as f:
|
||
file_data = f.read()
|
||
|
||
sb.upload_file(
|
||
bucket="avatars",
|
||
file_path="user_123/avatar.png",
|
||
file_data=file_data,
|
||
content_type="image/png"
|
||
)
|
||
|
||
# Получить публичный URL
|
||
url = sb.get_public_url(
|
||
bucket="avatars",
|
||
file_path="user_123/avatar.png"
|
||
)
|
||
print(f"Файл доступен по адресу: {url}")
|
||
```
|
||
|
||
### Продвинутые запросы
|
||
|
||
Для сложных запросов используйте прямой доступ к клиенту:
|
||
|
||
```python
|
||
client = sb.get_client()
|
||
|
||
# Запрос с операторами сравнения
|
||
adults = client.table("users")\
|
||
.select("*")\
|
||
.gte("age", 18)\
|
||
.order("age", desc=True)\
|
||
.execute()
|
||
|
||
# Поиск по паттерну
|
||
ivan_users = client.table("users")\
|
||
.select("*")\
|
||
.ilike("name", "%иван%")\
|
||
.execute()
|
||
```
|
||
|
||
## 📁 Структура проекта
|
||
|
||
```
|
||
supabase-connector/
|
||
├── supabase.py # Основной класс SupabaseManager
|
||
├── __init__.py # Инициализация пакета
|
||
├── example.py # Примеры использования
|
||
├── requirements.txt # Зависимости
|
||
├── setup.py # Настройка пакета
|
||
├── .env.example # Шаблон конфигурации
|
||
├── .gitignore # Исключения для git
|
||
└── README.md # Документация
|
||
```
|
||
|
||
## 🧪 Запуск примеров
|
||
|
||
В файле `example.py` находятся готовые примеры использования:
|
||
|
||
```bash
|
||
python example.py
|
||
```
|
||
|
||
Раскомментируйте нужные примеры в функции `main()`.
|
||
|
||
## 📝 API Reference
|
||
|
||
### SupabaseManager
|
||
|
||
#### `__init__()`
|
||
Инициализирует подключение к Supabase, используя переменные окружения.
|
||
|
||
#### `select(table, columns="*", filters=None, limit=None)`
|
||
Выполняет SELECT запрос.
|
||
|
||
**Параметры:**
|
||
- `table` (str): Название таблицы
|
||
- `columns` (str): Колонки для выборки
|
||
- `filters` (dict): Словарь с фильтрами `{column: value}`
|
||
- `limit` (int): Максимальное количество записей
|
||
|
||
**Возвращает:** `List[Dict]`
|
||
|
||
#### `insert(table, data)`
|
||
Вставляет новую запись.
|
||
|
||
**Параметры:**
|
||
- `table` (str): Название таблицы
|
||
- `data` (dict): Данные для вставки
|
||
|
||
**Возвращает:** `Dict`
|
||
|
||
#### `update(table, data, filters)`
|
||
Обновляет записи.
|
||
|
||
**Параметры:**
|
||
- `table` (str): Название таблицы
|
||
- `data` (dict): Данные для обновления
|
||
- `filters` (dict): Фильтры `{column: value}`
|
||
|
||
**Возвращает:** `List[Dict]`
|
||
|
||
#### `delete(table, filters)`
|
||
Удаляет записи.
|
||
|
||
**Параметры:**
|
||
- `table` (str): Название таблицы
|
||
- `filters` (dict): Фильтры `{column: value}`
|
||
|
||
**Возвращает:** `List[Dict]`
|
||
|
||
#### `upload_file(bucket, file_path, file_data, content_type=None)`
|
||
Загружает файл в Storage.
|
||
|
||
**Параметры:**
|
||
- `bucket` (str): Название bucket
|
||
- `file_path` (str): Путь к файлу в bucket
|
||
- `file_data` (bytes): Данные файла
|
||
- `content_type` (str): MIME тип файла
|
||
|
||
**Возвращает:** `bool`
|
||
|
||
#### `get_public_url(bucket, file_path)`
|
||
Получает публичный URL файла.
|
||
|
||
**Параметры:**
|
||
- `bucket` (str): Название bucket
|
||
- `file_path` (str): Путь к файлу
|
||
|
||
**Возвращает:** `str`
|
||
|
||
#### `get_client()`
|
||
Возвращает прямой доступ к клиенту Supabase для сложных операций.
|
||
|
||
**Возвращает:** `Client`
|
||
|
||
## 🧪 Создание тестовой таблицы
|
||
|
||
Для тестирования создайте таблицу в Supabase:
|
||
|
||
```sql
|
||
CREATE TABLE users (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
name TEXT NOT NULL,
|
||
email TEXT UNIQUE NOT NULL,
|
||
age INTEGER,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- Тестовые данные
|
||
INSERT INTO users (name, email, age) VALUES
|
||
('Иван Иванов', 'ivan@example.com', 30),
|
||
('Мария Петрова', 'maria@example.com', 25),
|
||
('Алексей Сидоров', 'alex@example.com', 35);
|
||
```
|
||
|
||
## 🔐 Безопасность
|
||
|
||
- ⚠️ Никогда не коммитьте файл `.env` в git
|
||
- Используйте **anon key** для клиентских операций
|
||
- Настройте Row Level Security (RLS) в Supabase
|
||
- Для серверных операций используйте **service_role key** с осторожностью
|
||
|
||
## 🛠️ Расширение функциональности
|
||
|
||
Вы можете легко добавить свои методы в класс `SupabaseManager`:
|
||
|
||
```python
|
||
class SupabaseManager:
|
||
# ... существующие методы ...
|
||
|
||
def count_records(self, table: str) -> int:
|
||
"""Подсчет количества записей в таблице"""
|
||
data = self.select(table=table)
|
||
return len(data)
|
||
|
||
def search_by_text(self, table: str, column: str, search_term: str):
|
||
"""Полнотекстовый поиск"""
|
||
return self.client.table(table)\
|
||
.select("*")\
|
||
.ilike(column, f"%{search_term}%")\
|
||
.execute().data
|
||
```
|
||
|
||
## 🐛 Решение проблем
|
||
|
||
### Ошибка подключения
|
||
```
|
||
ValueError: SUPABASE_URL и SUPABASE_KEY должны быть установлены
|
||
```
|
||
**Решение:** Проверьте файл `.env` и убедитесь, что указаны правильные значения.
|
||
|
||
### Ошибка доступа к таблице
|
||
```
|
||
Ошибка при выполнении SELECT: ...
|
||
```
|
||
**Решение:**
|
||
1. Убедитесь, что таблица существует
|
||
2. Проверьте настройки RLS (Row Level Security)
|
||
3. Убедитесь, что у вашего ключа есть доступ к таблице
|
||
|
||
## 📚 Дополнительные ресурсы
|
||
|
||
- [Официальная документация Supabase](https://supabase.com/docs)
|
||
- [Supabase Python Client](https://supabase.com/docs/reference/python/introduction)
|
||
- [Row Level Security](https://supabase.com/docs/guides/auth/row-level-security)
|
||
|
||
## 🤝 Вклад в проект
|
||
|
||
Приветствуются любые предложения и улучшения! Создавайте Issues и Pull Requests.
|
||
|
||
## 📄 Лицензия
|
||
|
||
MIT License - используйте свободно в своих проектах.
|
||
|
||
## ⭐ Поддержка
|
||
|
||
Если проект был полезен, поставьте звезду на GitHub!
|