From ed0207054424c3feb2dc0997e2046f55b221d875 Mon Sep 17 00:00:00 2001 From: Pankaj Patil Date: Tue, 1 Jun 2021 21:48:20 +0530 Subject: [PATCH 1/2] Restructure Documents --- docs/settings.rst | 253 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 224 insertions(+), 29 deletions(-) diff --git a/docs/settings.rst b/docs/settings.rst index e887c0c4..f7eb3c53 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -1,30 +1,225 @@ +******** Settings -======== - -======================================= =============================================================================================================== ================================================================================================================================================ -Setting Description Default -======================================= =============================================================================================================== ================================================================================================================================================ -EXPLORER_SQL_BLACKLIST Disallowed words in SQL queries to prevent destructive actions. ('ALTER', 'RENAME ', 'DROP', 'TRUNCATE', 'INSERT INTO', 'UPDATE', 'REPLACE', 'DELETE', 'ALTER', 'CREATE TABLE', 'SCHEMA', 'GRANT', 'OWNER TO') -EXPLORER_SQL_WHITELIST These phrases are allowed, even though part of the phrase appears in the blacklist. ('CREATED', 'UPDATED', 'DELETED','REGEXP_REPLACE') -EXPLORER_DEFAULT_ROWS The number of rows to show by default in the preview pane. 1000 -EXPLORER_SCHEMA_INCLUDE_TABLE_PREFIXES If not None, show schema only for tables starting with these prefixes. "Wins" if in conflict with EXCLUDE None # shows all tables -EXPLORER_SCHEMA_EXCLUDE_TABLE_PREFIXES Don't show schema for tables starting with these prefixes, in the schema helper. ('django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.admin') -EXPLORER_SCHEMA_INCLUDE_VIEWS Include database views False -EXPLORER_ASYNC_SCHEMA Generate DB schema asynchronously. Requires Celery and EXPLORER_TASKS_ENABLED False -EXPLORER_DEFAULT_CONNECTION The name of the Django database connection to use. Ideally set this to a connection with read only permissions None # Must be set for the app to work, as this is required -EXPLORER_CONNECTIONS A dictionary of { 'Friendly Name': 'django_db_alias'}. {} # At a minimum, should be set to something like { 'Default': 'readonly' } or similar. See connections.py for more documentation. -EXPLORER_PERMISSION_VIEW Callback to check if the user is allowed to view and execute stored queries lambda r: r.user.is_staff -EXPLORER_PERMISSION_CHANGE Callback to check if the user is allowed to add/change/delete queries lambda r: r.user.is_staff -EXPLORER_TRANSFORMS List of tuples like [('alias', 'Template for {0}')]. See features section of this doc for more info. [] -EXPLORER_RECENT_QUERY_COUNT The number of recent queries to show at the top of the query listing. 10 -EXPLORER_GET_USER_QUERY_VIEWS A dict granting view permissions on specific queries of the form {userId:[queryId, ...], ...} {} -EXPLORER_TOKEN_AUTH_ENABLED Bool indicating whether token-authenticated requests should be enabled. See "Power Tips", above. False -EXPLORER_TOKEN Access token for query results. "CHANGEME" -EXPLORER_TASKS_ENABLED Turn on if you want to use the snapshot_queries celery task, or email report functionality in tasks.py False -EXPLORER_S3_ACCESS_KEY S3 Access Key for snapshot upload None -EXPLORER_S3_SECRET_KEY S3 Secret Key for snapshot upload None -EXPLORER_S3_BUCKET S3 Bucket for snapshot upload None -EXPLORER_FROM_EMAIL The default 'from' address when using async report email functionality "django-sql-explorer@example.com" -EXPLORER_DATA_EXPORTERS The export buttons to use. Default includes Excel, so xlsxwriter from optional-requirements.txt is needed [('csv', 'explorer.exporters.CSVExporter'), ('excel', 'explorer.exporters.ExcelExporter'), ('json', 'explorer.exporters.JSONExporter')] -EXPLORER_UNSAFE_RENDERING Disable autoescaping for rendering values from the database. Be wary of XSS attacks if querying unknown data... False -======================================= =============================================================================================================== ================================================================================================================================================ +******** + +EXPLORER_SQL_BLACKLIST +********************** + +Disallowed words in SQL queries to prevent destructive actions. + +**Default Value:** + +('ALTER', 'RENAME ', 'DROP', 'TRUNCATE', 'INSERT INTO', 'UPDATE', 'REPLACE', 'DELETE', 'ALTER', 'CREATE TABLE', 'SCHEMA', 'GRANT', 'OWNER TO') + + +EXPLORER_SQL_WHITELIST +********************** + +These phrases are allowed, even though part of the phrase appears in the blacklist. + +Default Values: + +('CREATED', 'UPDATED', 'DELETED','REGEXP_REPLACE') + +EXPLORER_DEFAULT_ROWS +********************* + +The number of rows to show by default in the preview pane. + +**Default Value:** + +1000 + +EXPLORER_SCHEMA_INCLUDE_TABLE_PREFIXES +************************************** + +If not None, show schema only for tables starting with these prefixes. "Wins" if in conflict with EXCLUDE + +**Default Value:** + +None # shows all tables + +EXPLORER_SCHEMA_EXCLUDE_TABLE_PREFIXES +************************************** + +Don't show schema for tables starting with these prefixes, in the schema helper. + +**Default Value:** + +('django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.admin') + + +EXPLORER_SCHEMA_INCLUDE_VIEWS +***************************** + +Include database views + +**Default Value:** + +False + + +EXPLORER_ASYNC_SCHEMA +********************* +Generate DB schema asynchronously. Requires Celery and EXPLORER_TASKS_ENABLED + +**Default Value:** + +False + + +EXPLORER_DEFAULT_CONNECTION +*************************** + +The name of the Django database connection to use. Ideally set this to a connection with read only permissions + +**Default Value:** + +None # Must be set for the app to work, as this is required + + +EXPLORER_CONNECTIONS +******************** + +A dictionary of { 'Friendly Name': 'django_db_alias'}. + +**Default Value:** + +{} # At a minimum, should be set to something like { 'Default': 'readonly' } or similar. See connections.py for more documentation. + + +EXPLORER_PERMISSION_VIEW +************************ +Callback to check if the user is allowed to view and execute stored queries + +**Default Value:** + +lambda r: r.user.is_staff + + +EXPLORER_PERMISSION_CHANGE +************************** + +Callback to check if the user is allowed to add/change/delete queries + +**Default Value:** + +lambda r: r.user.is_staff + +EXPLORER_TRANSFORMS +******************* + +List of tuples like [('alias', 'Template for {0}')]. See features section of this doc for more info. + +**Default Value:** + +[] + + + +EXPLORER_RECENT_QUERY_COUNT +*************************** + +The number of recent queries to show at the top of the query listing. + +**Default Value:** + +10 + + +EXPLORER_GET_USER_QUERY_VIEWS +***************************** + +A dict granting view permissions on specific queries of the form {userId:[queryId, ...], ...} + +**Default Value:** + +{} + + +EXPLORER_TOKEN_AUTH_ENABLED +*************************** + +Bool indicating whether token-authenticated requests should be enabled. See "Power Tips", above. + +**Default Value:** + +False + + +EXPLORER_TOKEN +************** + +Access token for query results. + +**Default Value:** + +"CHANGEME" + + +EXPLORER_TASKS_ENABLED +********************** + +Turn on if you want to use the snapshot_queries celery task, or email report functionality in tasks.py + +**Default Value:** + +False + +EXPLORER_S3_ACCESS_KEY +********************** + +S3 Access Key for snapshot upload + +**Default Value:** + +None + + +EXPLORER_S3_SECRET_KEY +********************** + +S3 Secret Key for snapshot upload + +**Default Value:** + +None + + +EXPLORER_S3_BUCKET +****************** + +S3 Bucket for snapshot upload + +**Default Value:** + +None + + +EXPLORER_FROM_EMAIL +******************* + +The default 'from' address when using async report email functionality + +**Default Value:** + +"django-sql-explorer@example.com" + + +EXPLORER_DATA_EXPORTERS +*********************** + +The export buttons to use. Default includes Excel, so xlsxwriter from optional-requirements.txt is needed + +**Default Value:** + +[('csv', 'explorer.exporters.CSVExporter'), ('excel', 'explorer.exporters.ExcelExporter'), ('json', 'explorer.exporters.JSONExporter')] + +EXPLORER_UNSAFE_RENDERING +************************* + +Disable auto escaping for rendering values from the database. Be wary of XSS attacks if querying unknown data... + +**Default Value:** + +False From 3dde651731e5c46a929f4eb73fcefe38b44c239b Mon Sep 17 00:00:00 2001 From: Pankaj Patil Date: Sun, 6 Jun 2021 20:15:41 +0530 Subject: [PATCH 2/2] Implement feedback --- docs/settings.rst | 191 +++++++++++++++++++++++++++++----------------- 1 file changed, 119 insertions(+), 72 deletions(-) diff --git a/docs/settings.rst b/docs/settings.rst index f7eb3c53..c65cde4b 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -2,65 +2,80 @@ Settings ******** -EXPLORER_SQL_BLACKLIST -********************** +``EXPLORER_SQL_BLACKLIST`` +************************** Disallowed words in SQL queries to prevent destructive actions. **Default Value:** - -('ALTER', 'RENAME ', 'DROP', 'TRUNCATE', 'INSERT INTO', 'UPDATE', 'REPLACE', 'DELETE', 'ALTER', 'CREATE TABLE', 'SCHEMA', 'GRANT', 'OWNER TO') +.. code-block:: python -EXPLORER_SQL_WHITELIST -********************** + ('ALTER', 'RENAME ', 'DROP', 'TRUNCATE', 'INSERT INTO', 'UPDATE', 'REPLACE', 'DELETE', 'ALTER', 'CREATE TABLE', 'SCHEMA', 'GRANT', 'OWNER TO') + + + +``EXPLORER_SQL_WHITELIST`` +************************** These phrases are allowed, even though part of the phrase appears in the blacklist. -Default Values: - -('CREATED', 'UPDATED', 'DELETED','REGEXP_REPLACE') +**Default Value:** + +.. code-block:: python -EXPLORER_DEFAULT_ROWS -********************* + ('CREATED', 'UPDATED', 'DELETED','REGEXP_REPLACE') + + + +``EXPLORER_DEFAULT_ROWS`` +************************* The number of rows to show by default in the preview pane. **Default Value:** - -1000 -EXPLORER_SCHEMA_INCLUDE_TABLE_PREFIXES -************************************** +.. code-block:: python + + 1000 + +``EXPLORER_SCHEMA_INCLUDE_TABLE_PREFIXES`` +****************************************** If not None, show schema only for tables starting with these prefixes. "Wins" if in conflict with EXCLUDE **Default Value:** -None # shows all tables +.. code-block:: python + + None # shows all tables -EXPLORER_SCHEMA_EXCLUDE_TABLE_PREFIXES -************************************** +``EXPLORER_SCHEMA_EXCLUDE_TABLE_PREFIXES`` +****************************************** Don't show schema for tables starting with these prefixes, in the schema helper. **Default Value:** + +.. code-block:: python -('django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.admin') + ('django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.admin') -EXPLORER_SCHEMA_INCLUDE_VIEWS -***************************** +``EXPLORER_SCHEMA_INCLUDE_VIEWS`` +********************************* Include database views **Default Value:** -False +.. code-block:: python + + False -EXPLORER_ASYNC_SCHEMA -********************* +``EXPLORER_ASYNC_SCHEMA`` +************************* Generate DB schema asynchronously. Requires Celery and EXPLORER_TASKS_ENABLED **Default Value:** @@ -68,132 +83,158 @@ Generate DB schema asynchronously. Requires Celery and EXPLORER_TASKS_ENABLED False -EXPLORER_DEFAULT_CONNECTION -*************************** +``EXPLORER_DEFAULT_CONNECTION`` +******************************* The name of the Django database connection to use. Ideally set this to a connection with read only permissions **Default Value:** + +.. code-block:: python -None # Must be set for the app to work, as this is required + None # Must be set for the app to work, as this is required -EXPLORER_CONNECTIONS -******************** +``EXPLORER_CONNECTIONS`` +************************ A dictionary of { 'Friendly Name': 'django_db_alias'}. **Default Value:** + +.. code-block:: python -{} # At a minimum, should be set to something like { 'Default': 'readonly' } or similar. See connections.py for more documentation. + {} # At a minimum, should be set to something like { 'Default': 'readonly' } or similar. See connections.py for more documentation. -EXPLORER_PERMISSION_VIEW -************************ +``EXPLORER_PERMISSION_VIEW`` +**************************** Callback to check if the user is allowed to view and execute stored queries **Default Value:** + +.. code-block:: python -lambda r: r.user.is_staff + lambda r: r.user.is_staff -EXPLORER_PERMISSION_CHANGE -************************** +``EXPLORER_PERMISSION_CHANGE`` +****************************** Callback to check if the user is allowed to add/change/delete queries **Default Value:** + +.. code-block:: python -lambda r: r.user.is_staff + lambda r: r.user.is_staff -EXPLORER_TRANSFORMS -******************* +``EXPLORER_TRANSFORMS`` +*********************** List of tuples like [('alias', 'Template for {0}')]. See features section of this doc for more info. **Default Value:** -[] +.. code-block:: python + [] -EXPLORER_RECENT_QUERY_COUNT -*************************** + +``EXPLORER_RECENT_QUERY_COUNT`` +******************************* The number of recent queries to show at the top of the query listing. -**Default Value:** +**Default Value:** + +.. code-block:: python -10 + 10 -EXPLORER_GET_USER_QUERY_VIEWS -***************************** +``EXPLORER_GET_USER_QUERY_VIEWS`` +********************************* A dict granting view permissions on specific queries of the form {userId:[queryId, ...], ...} **Default Value:** - -{} +.. code-block:: python + + {} -EXPLORER_TOKEN_AUTH_ENABLED -*************************** + +``EXPLORER_TOKEN_AUTH_ENABLED`` +******************************* Bool indicating whether token-authenticated requests should be enabled. See "Power Tips", above. **Default Value:** + +.. code-block:: python -False + False -EXPLORER_TOKEN -************** +``EXPLORER_TOKEN`` +****************** Access token for query results. **Default Value:** -"CHANGEME" +.. code-block:: python + + "CHANGEME" -EXPLORER_TASKS_ENABLED -********************** +``EXPLORER_TASKS_ENABLED`` +************************** Turn on if you want to use the snapshot_queries celery task, or email report functionality in tasks.py **Default Value:** + +.. code-block:: python -False + False -EXPLORER_S3_ACCESS_KEY -********************** +``EXPLORER_S3_ACCESS_KEY`` +************************** S3 Access Key for snapshot upload **Default Value:** + +.. code-block:: python -None + None -EXPLORER_S3_SECRET_KEY -********************** +``EXPLORER_S3_SECRET_KEY`` +************************** S3 Secret Key for snapshot upload **Default Value:** + +.. code-block:: python -None + None -EXPLORER_S3_BUCKET -****************** +``EXPLORER_S3_BUCKET`` +********************** S3 Bucket for snapshot upload **Default Value:** -None +.. code-block:: python + + None EXPLORER_FROM_EMAIL @@ -203,23 +244,29 @@ The default 'from' address when using async report email functionality **Default Value:** -"django-sql-explorer@example.com" +.. code-block:: python + "django-sql-explorer@example.com" -EXPLORER_DATA_EXPORTERS -*********************** + +``EXPLORER_DATA_EXPORTERS`` +*************************** The export buttons to use. Default includes Excel, so xlsxwriter from optional-requirements.txt is needed **Default Value:** + +.. code-block:: python -[('csv', 'explorer.exporters.CSVExporter'), ('excel', 'explorer.exporters.ExcelExporter'), ('json', 'explorer.exporters.JSONExporter')] + [('csv', 'explorer.exporters.CSVExporter'), ('excel', 'explorer.exporters.ExcelExporter'), ('json', 'explorer.exporters.JSONExporter')] -EXPLORER_UNSAFE_RENDERING -************************* +``EXPLORER_UNSAFE_RENDERING`` +***************************** Disable auto escaping for rendering values from the database. Be wary of XSS attacks if querying unknown data... **Default Value:** -False +.. code-block:: python + + False