Django SQL Explorer 安装与配置指南

Django SQL Explorer 安装与配置指南

django-sql-explorer Easily share data across your company via SQL queries. 项目地址: https://gitcode.com/gh_mirrors/dj/django-sql-explorer

项目概述

Django SQL Explorer 是一个强大的 Django 应用，它允许开发者和数据分析师直接在 Web 界面上编写和执行 SQL 查询，无需通过 Django ORM。这个工具特别适合需要直接与数据库交互的场景，如数据分析、报表生成等。

环境要求

在开始安装前，请确保您的系统满足以下要求：

• Python 3.10 或更高版本
• Django 3.2 或更高版本

安装步骤

1. 创建 Django 项目

如果您还没有 Django 项目，可以通过以下命令创建一个：

pip install django
django-admin startproject project

2. 安装 Django SQL Explorer

通过 pip 安装核心包：

pip install django-sql-explorer

如果需要支持 Excel 文件下载功能，安装时添加额外依赖：

pip install django-sql-explorer[xls]

配置指南

1. 添加应用到 INSTALLED_APPS

在项目的 settings.py 文件中，将 'explorer' 添加到 INSTALLED_APPS 列表中：

INSTALLED_APPS = (
    'explorer',
)

2. 数据库连接配置

配置数据库连接设置，建议使用只读账户：

EXPLORER_CONNECTIONS = { 'Default': 'readonly' }
EXPLORER_DEFAULT_CONNECTION = 'readonly'

这里的键是显示给用户的友好名称，值是 settings.DATABASES 中定义的数据库别名。

安全提示：强烈建议在数据库中设置只读角色，并在项目中使用这些只读连接。

3. URL 配置

在项目的 urls.py 文件中添加以下内容：

from django.urls import path, include

urlpatterns = [
    path('explorer/', include('explorer.urls')),
]

所有 Explorer 的 URL 访问都受 EXPLORER_PERMISSION_VIEW 和 EXPLORER_PERMISSION_CHANGE 设置控制。

4. 快速开发配置（仅限开发环境）

如果您在开发环境中快速测试，可以使用默认连接：

EXPLORER_CONNECTIONS = { 'Default': 'default' }
EXPLORER_DEFAULT_CONNECTION = 'default'

数据库迁移与运行

1. 执行数据库迁移：

python manage.py migrate

2. 创建超级用户：

python manage.py createsuperuser

3. 启动开发服务器：

python manage.py runserver

现在，您可以通过访问 http://127.0.0.1:8000/explorer/ 开始使用 SQL Explorer。

静态文件注意事项

Explorer 需要正确设置 STATIC_URL。在标准 Django 设置中这不是问题，但如果您使用如 Django Storages 与 S3 等服务，必须确保 STATIC_URL 指向正确的静态文件位置。

AI SQL 助手功能

要启用 AI 功能，需要安装额外的依赖：

pip install openai tiktoken

默认配置使用 OpenAI 的 gpt-4-0125-preview 模型。在 settings.py 中设置 API 密钥：

EXPLORER_AI_API_KEY = 'your_openai_api_key'
# 或更安全的方式
EXPLORER_AI_API_KEY = os.environ.get("OPENAI_API_KEY")

自定义 AI 提供者

您可以配置使用其他 AI 提供者和模型，例如使用 OpenRouter 和 Mixtral 8x7B Instruct：

EXPLORER_ASSISTANT_MODEL = {
    "name": "mistralai/mixtral-8x7b-instruct:nitro",
    "max_tokens": 32768
}
EXPLORER_ASSISTANT_BASE_URL = "https://openrouter.ai/api/v1"
EXPLORER_AI_API_KEY = os.environ.get("OPENROUTER_API_KEY")

高级配置选项

参数化查询行为

默认情况下，查看参数化查询时会自动使用默认参数值运行 SQL。如果查询性能较差，可以禁用此行为：

EXPLORER_AUTORUN_QUERY_WITH_PARAMS = False

Celery 集成

一些高级功能（如快照、邮件查询）需要 Celery。安装 Celery 后，在设置中启用：

EXPLORER_TASKS_ENABLED = True

从源码安装注意事项

由于前端资源需要构建，不建议直接从源码通过 pip 安装。正确的方式是克隆仓库并按照开发说明进行构建。

最佳实践建议

1. 安全性：始终在生产环境中使用只读数据库账户
2. 权限控制：合理配置 EXPLORER_PERMISSION_VIEW 和 EXPLORER_PERMISSION_CHANGE
3. 性能考虑：对于复杂查询，考虑禁用 EXPLORER_AUTORUN_QUERY_WITH_PARAMS
4. AI 功能：注意 API 调用的成本和安全性

通过以上步骤，您应该能够成功安装并配置 Django SQL Explorer，开始高效地进行数据库查询和分析工作。

django-sql-explorer Easily share data across your company via SQL queries. 项目地址: https://gitcode.com/gh_mirrors/dj/django-sql-explorer