Django

Django — это популярный Python веб-фреймворк с мощной ORM для работы с базами данных.

YDB поддерживает интеграцию с Django через специальный бэкенд django-ydb-backend, который обеспечивает полную поддержку Django ORM для работы с YDB.

Внимание

Интеграция с Django пока находится на этапе бета-тестирования. Обратите внимание, что сейчас поля ForeignKey, ManyToManyField и OneToOneField ещё не поддерживаются — их реализация находится в процессе разработки.

Установка

Установите пакет django-ydb-backend с помощью pip:

pip install django-ydb-backend

Конфигурация

Настройки подключения

Для подключения к YDB используйте стандартный механизм настройки баз данных Django через переменную DATABASES в файле settings.py. Подробнее о конфигурации баз данных в Django можно прочитать в официальной документации.

Необходимые параметры конфигурации подключения:

  • NAME — имя базы данных Django.
  • ENGINE — используется значение ydb_backend.backend.
  • HOST — адрес сервера YDB (например, localhost).
  • PORT — порт gRPC YDB (по умолчанию 2136).
  • DATABASE — абсолютный путь к базе данных YDB (например, /local для локальных тестов или /my_production_db для production).

Пример настройки подключения:

DATABASES = {
    "default": {
        "NAME": "ydb_db",
        "ENGINE": "ydb_backend.backend",
        "HOST": "localhost",
        "PORT": "2136",
        "DATABASE": "/local",
    }
}

Методы аутентификации

Для использования анонимной аутентификации не нужно передавать дополнительные параметры.

Для использования статических учетных данных нужно указать username и password:

DATABASES = {
    "default": {
        "ENGINE": "ydb_backend.backend",
        "CREDENTIALS": {
            "username": "...",
            "password": "..."
        }
    }
}

Для использования токена доступа нужно указать token:

DATABASES = {
    "default": {
        "ENGINE": "ydb_backend.backend",
        "CREDENTIALS": {
            "token": "..."
        },
    }
}

Для использования сервисного аккаунта нужно указать service_account_json:

DATABASES = {
    "default": {
        "ENGINE": "ydb_backend.backend",
        "CREDENTIALS": {
            "service_account_json": {
                "id": "...",
                "service_account_id": "...",
                "created_at": "...",
                "key_algorithm": "...",
                "public_key": "...",
                "private_key": "..."
            }
        }
    }
}

Использование шифрования

Если у вас развернут кластер YDB с использованием шифрования, необходимо добавить в настройки базы данных блок OPTIONS с указанием протокола и пути к сертификату. Например:

Это обеспечит защищённое соединение с кластером YDB.

DATABASES = {
    "default": {
        ...
        "OPTIONS": {
            "protocol": "grpcs",
            "root_certificates_path": "path/to/cert.crt",
        }
    }
}

Поля Django

YDB backend поддерживает встроенные поля Django.

Поддерживаемые поля Django

Класс YDB тип Python тип Комментарии
SmallAutoField Int16 int YDB тип SmallSerial будет генерировать значения автоматически. Диапазон -32768 до 32767
AutoField Int32 int YDB тип Serial будет генерировать значения автоматически. Диапазон -2147483648 до 2147483647
BigAutoField Int64 int YDB тип BigSerial будет генерировать значения автоматически. Диапазон -9223372036854775808 до 9223372036854775807
CharField UTF-8 str
TextField UTF-8 str
BinaryField String bytes
SlugField UTF-8 str
FileField String bytes
FilePathField UTF-8 str
DateField Date datetime.date Диапазон значений: с 00:00 01.01.1970 до 00:00 01.01.2106. Внутреннее представление: беззнаковое 16-битное целое
DateTimeField DateTime datetime.datetime Внутреннее представление: беззнаковое 32-битное целое
DurationField Interval int Диапазон значений от -136 лет до +136 лет. Внутреннее представление: знаковое 64-битное целое. Нельзя использовать в первичном ключе
SmallIntegerField Int16 int Диапазон -32768 до 32767
IntegerField Int32 int Диапазон -2147483648 до 2147483647
BigIntegerField Int64 int Диапазон -9223372036854775808 до 9223372036854775807
PositiveSmallIntegerField UInt16 int Диапазон 0 до 65535
PositiveIntegerField UInt32 int Диапазон 0 до 4294967295
PositiveBigIntegerField UInt64 int Диапазон 0 до 18446744073709551615
FloatField Float float Вещественное число с переменной точностью, размер 4 байта. Нельзя использовать в первичном ключе
DecimalField Decimal Decimal Python значения округляются до масштаба поля базы данных. Поддерживает только Decimal(22,9)
UUIDField UUID uuid.UUID
IPAddressField UTF-8 str
GenericIPAddressField UTF-8 str
BooleanField Bool boolean
EmailField UTF-8 str

Быстрый старт

Необходимые условия

Перед началом работы убедитесь, что:

  1. Развернут кластер YDB локально или используя Ansible
  2. Установлены Python-пакеты: Django, django-ydb-backend, djangorestframework
  3. Склонирован репозиторий с примером

Перейдите в рабочую директорию

cd examples/bookstore

Конфигурация подключения к YDB

Для интеграции YDB с Django укажите параметры подключения в файле config/settings.py проекта:

DATABASES = {
    "default": {
        "NAME": "ydb_db",
        "ENGINE": "ydb_backend.backend",
        "HOST": "localhost",
        "PORT": "2136",
        "DATABASE": "/local",
        "OPTIONS": {
            "protocol": "grpcs",
            "root_certificates_path": "path/to/cert.crt",
        }
    }
}

Запустите миграции

python manage.py migrate

Запустите сервер

python manage.py runserver

Проверьте работу приложения

После запуска приложение будет доступно по адресу http://127.0.0.1:8000 (по умолчанию).

Полезные ссылки

Предыдущая
SQLAlchemy
Следующая
Векторный поиск