From c76a671828e9882149a215c0c28b2622732e2afa Mon Sep 17 00:00:00 2001 From: Chris Clark Date: Thu, 20 Jun 2024 22:04:24 -0400 Subject: [PATCH] docs improvements --- docs/development.rst | 11 ++++----- docs/features.rst | 57 +++++++++++++++++++++++--------------------- docs/settings.rst | 11 +++++++++ 3 files changed, 46 insertions(+), 33 deletions(-) diff --git a/docs/development.rst b/docs/development.rst index ba943e24..f1779cce 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -14,10 +14,10 @@ Installing From Source If you are installing SQL Explorer from source (by cloning the repository), you may want to first look at simply running test_project/start.sh. -If you want to install into an existing project, you can do so by following -the install instructions, and then additionally building the front-end dependencies. - -After cloning, simply run: +If you want to install SQL Explorer from source, into an existing project, +you can do so by cloning the repository and following the usual +:doc:`development` instructions, and then additionally building the front-end +dependencies: :: @@ -33,8 +33,7 @@ phase. Copy the /explorer directory into site-packages and you're ready to go. Tests ----- -Factory Boy is needed if you'd like to run the tests, which can you do -easily: +Factory Boy is needed if you'd like to run the tests. They can be run with: ``python manage.py test --settings=tests.settings`` diff --git a/docs/features.rst b/docs/features.rst index 457497b1..d1220443 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -1,43 +1,19 @@ Features ======== -Security --------- -- It's recommended you setup read-only roles for each of your database - connections and only use these particular connections for your queries through the - ``EXPLORER_CONNECTIONS`` setting -- or set up userland connections via DatabaseConnections in - the Django admin, or the SQL Explorer front-end. -- SQL Explorer supports two different permission checks for users of - the tool. Users passing the ``EXPLORER_PERMISSION_CHANGE`` test can - create, edit, delete, and execute queries. Users who do not pass - this test but pass the ``EXPLORER_PERMISSION_VIEW`` test can only - execute queries. Other users cannot access any part of - SQL Explorer. Both permission groups are set to is_staff by default - and can be overridden in your settings file. -- Enforces a SQL blacklist so destructive queries don't get - executed (delete, drop, alter, update etc). This is not - a substitute for using a readonly connection -- but is better - than nothing for certain use cases where a readonly connection - may not be available. - Easy to get started ------------------- - Built on Django's ORM, so works with MySQL, Postgres, Oracle, SQLite, Snowflake, MS SQL Server, RedShift, and MariaDB. - Small number of dependencies. -- Just want to get in and write some ad-hoc queries? Go nuts with - the Playground area. +- MIT licensed (except for functionality in the /ee/ directory, + which is still free for commercial use, but can't be resold). SQL Assistant ------------- - Built in integration with OpenAI (or the LLM of your choosing) to quickly get help with your query, with relevant schema - automatically injected into the prompt. - -Configurable Connections ------------------------- -- Configure connections via the settings.py file, or via the SQL Explorer UI. -- Supports drag-and-drop uploading of CSV files or SQLite databases for instant SQL access to your data. + automatically injected into the prompt. Simple, effective. Snapshots --------- @@ -189,6 +165,9 @@ Multiple Connections to contain any Django schema, or be related to Django in any way. See connections.py for more documentation on multi-connection setup. +- SQL Explorer also supports user-provided connections in the form + of standard database connection details, or uploading CSV or SQLite + files. See the 'User uploads' section of :doc:`settings`. Power tips ---------- @@ -230,3 +209,27 @@ You can also pass the token with a query parameter like this: .. code-block:: console curl https://www.your-site.com/explorer//stream?format=csv&token= + + +Security +-------- +- It's recommended you setup read-only roles for each of your database + connections and only use these particular connections for your queries + through the ``EXPLORER_CONNECTIONS`` setting -- or set up userland + connections via DatabaseConnections in the Django admin, or the SQL + Explorer front-end. +- SQL Explorer supports three different permission checks for users of + the tool. Users passing the ``EXPLORER_PERMISSION_CHANGE`` test can + create, edit, delete, and execute queries. Users who do not pass + this test but pass the ``EXPLORER_PERMISSION_VIEW`` test can only + execute queries. Other users cannot access any part of + SQL Explorer. Both permission groups are set to is_staff by default + and can be overridden in your settings file. Lastly, the permission + ``EXPLORER_PERMISSION_CONNECTIONS`` controls which users can manage + connections via the UI (if enabled). This is also set to is_staff by + default. +- Enforces a SQL blacklist so destructive queries don't get + executed (delete, drop, alter, update etc). This is not + a substitute for using a readonly connection -- but is better + than nothing for certain use cases where a readonly connection + may not be available. diff --git a/docs/settings.rst b/docs/settings.rst index 653b002c..7e409ebe 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -367,3 +367,14 @@ User-Configured DB Connections ****************************** Set `EXPLORER_DB_CONNECTIONS_ENABLED` to `True` to enable DB connections to get configured in the browser (e.g. not just in settings.py). This also allows uploading of CSV or SQLite files for instant querying. + + +User Uploads +************ +With `EXPLORER_DB_CONNECTIONS_ENABLED` set to `True`, you can also set `EXPLORER_USER_UPLOADS_ENABLED` to allow users +to upload their own CSV and SQLite files directly to explorer as new connections. + +Go to connections->Add New and scroll down to see the upload interface. The uploaded files are limited in size by the +`EXPLORER_MAX_UPLOAD_SIZE` setting which is set to 500mb by default (500 * 1024 * 1024). SQLite files (in either .db or +.sqlite) will simple appear as connections. CSV files get run through a parser that infers the type of each field. +