Django SQL Explorer

5.3 · active · verified Fri Apr 17

Django SQL Explorer provides a delightful SQL editor and interface for writing and sharing SQL queries directly within a Django admin-like environment. It allows users to quickly generate reports, download data, and visualize results, with recent versions (like 5.3) adding AI assistance for query generation. It is actively maintained, with new releases often coinciding with major Django version compatibility updates.

Common errors

```
ModuleNotFoundError: No module named 'explorer'
```
cause The `explorer` app was not added to `INSTALLED_APPS` in your Django `settings.py`, or `django-sql-explorer` was not installed.

fix Ensure `pip install django-sql-explorer` has been run and add `'explorer'` to your `INSTALLED_APPS` list in `settings.py`.
```
django.urls.exceptions.NoReverseMatch: Reverse for 'explorer:query_list' not found. 'explorer' is not a registered namespace.
```
cause The `explorer.urls` are not correctly included in your project's `urls.py`.

fix In your project's `urls.py`, add `path('explorer/', include('explorer.urls'))` to your `urlpatterns`.
```
django.db.utils.OperationalError: no such table: explorer_query
```
cause The database migrations for `django-sql-explorer` have not been run.

fix Run `python manage.py migrate` to create the necessary database tables for the explorer app.

Warnings

breaking Major Django version compatibility: Ensure your `django-sql-explorer` version is compatible with your Django version. For example, older versions of explorer might not work correctly with Django 3.x, 4.x, or 5.x. Check the project's `setup.py` or documentation for `requires_django`.
Fix: Upgrade `django-sql-explorer` to the latest version (`pip install --upgrade django-sql-explorer`) to ensure compatibility with recent Django releases. If specific compatibility is needed, consult the release notes.
gotcha Security Risk: Granting SQL access is powerful. Ensure `EXPLORER_PERMISSION_VIEW` and `EXPLORER_PERMISSION_CHANGE` settings are configured carefully. By default, these check `request.user.is_staff` and `request.user.is_superuser` respectively, but can be customized to any callable that returns True/False.
Fix: Explicitly define `EXPLORER_PERMISSION_VIEW` and `EXPLORER_PERMISSION_CHANGE` in `settings.py` to match your organization's security policies. For example, `EXPLORER_PERMISSION_VIEW = lambda request: request.user.groups.filter(name='Data Analysts').exists()`.
gotcha Database Connections: `django-sql-explorer` uses your Django project's default database connection. If you have multiple databases configured, you need to be mindful of which database it's querying. It does not natively support switching between multiple configured databases within the explorer UI, though custom solutions or proxy views could achieve this.
Fix: If querying a specific non-default database is required, consider configuring that database as the 'default' for a separate explorer instance, or use Django's database routing feature to direct `explorer`'s queries to a specific database if you have custom logic.
deprecated Old URL patterns: In very old versions (<3.0), the URL inclusion pattern or some view names might have been different, leading to `NoReverseMatch` errors.
Fix: Ensure you are using `path('explorer/', include('explorer.urls'))` in your project's `urls.py`. Always refer to the official documentation for the version you are using for the correct URL configuration.

Install

pip install django-sql-explorer Install with pip

Imports

Add to INSTALLED_APPS
wrong:
```
INSTALLED_APPS = ['django_sql_explorer', ...]
```
correct:
```
INSTALLED_APPS = ['explorer', ...]
```
The PyPI package is `django-sql-explorer` but the Django application name is simply `explorer`.

Include URLs

wrong:

path('sql-explorer/', include('django_sql_explorer.urls'))

correct:

from django.urls import include, path

urlpatterns = [
    path('explorer/', include('explorer.urls')),
    # ... other url patterns
]

Use the `explorer` app's URLs, typically under the `/explorer/` path.

Query Model
```
from explorer.models import Query
```
For programmatic access to saved queries.

Quickstart

To set up Django SQL Explorer, first ensure you have Django installed. Then, install `django-sql-explorer` via pip. Add `'explorer'` to your `INSTALLED_APPS` in `settings.py` and include `explorer.urls` in your project's `urls.py`. Run `python manage.py migrate` to create Explorer's database tables. Access is typically restricted to staff or superusers by default. Navigate to `/explorer/` after running the development server and log in with an appropriate user.

import os

# settings.py
# Minimum settings for django-sql-explorer

DEBUG = True

SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-dev')

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'explorer', # Add explorer app
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

ROOT_URLCONF = 'myproject.urls'

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

WSGI_APPLICATION = 'myproject.wsgi.application'

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(os.getcwd(), 'db.sqlite3'),
    }
}

AUTH_PASSWORD_VALIDATORS = [
    {'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator'},
    {'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator'},
    {'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator'},
    {'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator'},
]

LANGUAGE_CODE = 'en-us'
TIME_ZONE = 'UTC'
USE_I18N = True
USE_L10N = True
USE_TZ = True

STATIC_URL = '/static/'

# explorer specific settings (optional, defaults to is_staff checks)
EXPLORER_PERMISSION_VIEW = lambda request: request.user.is_staff
EXPLORER_PERMISSION_CHANGE = lambda request: request.user.is_superuser

# myproject/urls.py
# from django.contrib import admin
# from django.urls import include, path
# 
# urlpatterns = [
#     path('admin/', admin.site.urls),
#     path('explorer/', include('explorer.urls')), # Add explorer URLs
# ]

# To run:
# 1. pip install django django-sql-explorer
# 2. Create a Django project and app (e.g., 'myproject')
# 3. Replace myproject/settings.py and myproject/urls.py with the relevant parts above
# 4. python manage.py migrate
# 5. python manage.py createsuperuser
# 6. python manage.py runserver
# 7. Navigate to http://127.0.0.1:8000/explorer/ and log in with your superuser account.

view raw JSON →