Expanded SQL Documentation Per Issue #7604

Expanded SQL documentation, basing terminology and level of detail on the assumption of an audience that is nearly or mostly new to SQL.

Author: expliKate

Gemfile.lock

@@ -38,6 +38,7 @@ GEM
     faraday-net_http (3.1.0)
       net-http
     ffi (1.16.3)
+    ffi (1.16.3-x64-mingw-ucrt)
     forwardable-extended (2.6.0)
     gemoji (4.1.0)
     github-pages (231)
@@ -233,6 +234,8 @@ GEM
       uri
     nokogiri (1.16.3-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.16.3-x64-mingw-ucrt)
+      racc (~> 1.4)
     nokogiri (1.16.3-x86_64-linux)
       racc (~> 1.4)
     octokit (4.25.1)
@@ -270,19 +273,23 @@ GEM
     unf (0.1.4)
       unf_ext
     unf_ext (0.0.9.1)
+    unf_ext (0.0.9.1-x64-mingw-ucrt)
     unicode-display_width (1.8.0)
     uri (0.13.0)
+    wdm (0.1.1)
     webrick (1.8.1)
     yell (2.2.2)
 
 PLATFORMS
   arm64-darwin-22
+  x64-mingw-ucrt
   x86_64-linux
 
 DEPENDENCIES
   github-pages (= 231)
   html-proofer (~> 3.19.4)
   json
+  wdm (>= 0.1.1)
   webrick (~> 1.8)
 
 BUNDLED WITH

_docs/instructor/course_management/sql_toolbox.md

@@ -5,12 +5,39 @@ redirect_from:
   - /instructor/sql_toolbox
 ---
 
-While Submitty provides mechanisms of getting information about a course, or grades, an
-instructor may wish to run one-off queries against their database. To facilitate this,
+While Submitty already provides information about courses and grades, an
+instructor may wish to run one-off queries against Submitty's database in order to see 
+information in a format of their own choosing. To facilitate this,
 Submitty provides for each course a "SQL Toolbox" that can be accessed from the
 sidebar. Within the toolbox, instructors may run a `SELECT` query and see the results
 in tabular format.
 
+![](/images/sql_toolbox.png)
+### Basic Use
+The button labeled "Database Schema Documentation" at the top of the SQL Toolbox page
+contains details of all the information stored by Submitty and how these different
+pieces of information relate to one another.
+
+One simple query you can use the SQL toolbox for is to check what assignment IDs you've already used when trying to decide on a new one. The code for that looks like:
+```TSQL
+SELECT g_id from gradeable
+```
+If you have a lot of gradeables, it might help to sort the output of that code like so:
+```TSQL
+SELECT g_id from gradeable ORDER BY g_id
+```
+### Outside Learning Sources
+If you're brand new to writing SQL queries, here are a couple of popular resources for learning:
+
+[SQL Bolt](https://sqlbolt.com/)
+
+[w3 Schools](https://www.w3schools.com/sql/sql_intro.asp)
+### Advanced Use
+Once you're comfortable with writing SQL and have explored the database schema documentation some, you can start to write more complex queries. The query below shows all comments that have been written on all submissions from one student (username dents5 for this example):
+```TSQL
+SELECT comm.*, g.g_grade_due_date FROM gradeable_data_overall_comment comm INNER JOIN gradeable g ON comm.g_id = g.g_id WHERE comm.goc_user_id = 'dents5' ORDER BY comm.g_id
+```
+### Limitations
 The toolbox does come with a number of important limitations, put in place to help
 prevent accidental data loss and general security. As such, the toolbox will:
 
@@ -19,5 +46,3 @@ prevent accidental data loss and general security. As such, the toolbox will:
 * only run one query at a time. Attempting to run two queries separated by `;` will
   return an error.
 * run each query inside of a transaction that is rolled back and never committed.
-
-![](/images/sql_toolbox.png)