Install#

  • Requires Python 3.10 or higher.

  • Requires Django 3.2 or higher.

Set up a Django project with the following:

$ pip install django
$ django-admin startproject project

More information in the django tutorial.

Install with pip from pypi:

$ pip install django-sql-explorer

If you would also like to support downloading Excel files install with the dependency using:

$ pip install django-sql-explorer[xls]

Add to your INSTALLED_APPS, located in the settings.py file in your project folder:

INSTALLED_APPS = (
    'explorer',
)

Configure your settings to something like:

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

The first setting lists the connections you want to allow Explorer to use. The keys of the connections dictionary are friendly names to show Explorer users, and the values are the actual database aliases used in settings.DATABASES. It is highly recommended to setup read-only roles in your database, add them in your project’s DATABASES setting and use these read-only connections in the EXPLORER_CONNECTIONS.

Add the following to your urls.py (all Explorer URLs are restricted via the EXPLORER_PERMISSION_VIEW and EXPLORER_PERMISSION_CHANGE settings. See Settings section below for further documentation.):

from django.urls import path, include

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

If you want to quickly use django-sql-explorer with the existing default connection and know what you are doing (or you are on development), you can use the following settings:

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

Run migrate to create the tables:

python manage.py migrate

Create a superuser:

python manage.py createsuperuser

And run the server:

python manage.py runserver

You can now browse to http://127.0.0.1:8000/explorer/ and get exploring!

Note that Explorer expects STATIC_URL to be set appropriately. This isn’t a problem with vanilla Django setups, but if you are using e.g. Django Storages with S3, you must set your STATIC_URL to point to your S3 bucket (e.g. s3_bucket_url + ‘/static/’)

AI SQL Assistant#

To enable AI features, you must install the OpenAI SDK and Tiktoken library from requirements/optional.txt. By default the Assistant is configured to use OpenAI and the gpt-4-0125-preview model. To use those settings, set an OpenAI API token in your project’s settings.py file:

EXPLORER_AI_API_KEY = 'your_openai_api_key'

Or, more likely:

EXPLORER_AI_API_KEY = os.environ.get("OPENAI_API_KEY")

If you would prefer to use a different provider and/or different model, you can also override the AI API URL root and default model. For example, this would configure the Assistant to use OpenRouter and 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")

Other Parameters#

The default behavior when viewing a parameterized query is to autorun the associated SQL with the default parameter values. This may perform poorly and you may want a chance for your users to review the parameters before running. If so you may add the following setting which will allow the user to view the query and adjust any parameters before hitting “Save & Run”

EXPLORER_AUTORUN_QUERY_WITH_PARAMS = False

There are a handful of features (snapshots, emailing queries) that rely on Celery and the dependencies in optional-requirements.txt. If you have Celery installed, set EXPLORER_TASKS_ENABLED=True in your settings.py to enable these features.

Installing From Source#

Because the front-end assets must be built, installing SQL Explorer via pip from github is not supported. The package will be installed, but the front-end assets will be missing and will not be able to be built, as the necessary configuration files are not included when github builds the wheel for pip.

To run from source, clone the repository and follow the Running Locally (quick start) instructions.