From a023f49bc33764263eab23b6def9a323f39b06e3 Mon Sep 17 00:00:00 2001 From: Kate Tyrol Date: Wed, 3 Jul 2024 15:01:52 -0400 Subject: [PATCH 1/6] 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. --- Gemfile.lock | 7 ++++ .../course_management/sql_toolbox.md | 33 ++++++++++++++++--- 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index 47e66c36..b69bb55e 100644 --- a/Gemfile.lock +++ b/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 diff --git a/_docs/instructor/course_management/sql_toolbox.md b/_docs/instructor/course_management/sql_toolbox.md index e22f9131..7a29c098 100644 --- a/_docs/instructor/course_management/sql_toolbox.md +++ b/_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) From 60e46d48eacb576faa5769f6b6ac0c01adb7bb75 Mon Sep 17 00:00:00 2001 From: Barb Cutler Date: Thu, 19 Jun 2025 00:46:35 -0400 Subject: [PATCH 2/6] Update Gemfile.lock --- Gemfile.lock | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index ce19ec80..1414ac5f 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -39,8 +39,8 @@ GEM logger faraday-net_http (3.1.1) net-http - ffi (1.16.3) - ffi (1.16.3-x64-mingw-ucrt) + ffi (1.17.0-arm64-darwin) + ffi (1.17.0-x86_64-linux-gnu) forwardable-extended (2.6.0) gemoji (4.1.0) github-pages (232) From 84b1b220a65b4821c404999f1509da9aade3c3a4 Mon Sep 17 00:00:00 2001 From: Barb Cutler Date: Thu, 19 Jun 2025 00:48:04 -0400 Subject: [PATCH 3/6] Update Gemfile.lock --- Gemfile.lock | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index 1414ac5f..5aa2138c 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -238,9 +238,7 @@ GEM mutex_m (0.2.0) net-http (0.4.1) uri - nokogiri (1.16.7-arm64-darwin) - racc (~> 1.4) - nokogiri (1.16.3-x64-mingw-ucrt) + nokogiri (1.16.7-x86_64-linux) racc (~> 1.4) nokogiri (1.16.3-x86_64-linux) racc (~> 1.4) From ca9040b34d0d78adb49540067e89b3f45ea204e1 Mon Sep 17 00:00:00 2001 From: Barb Cutler Date: Thu, 19 Jun 2025 00:50:14 -0400 Subject: [PATCH 4/6] Update Gemfile.lock --- Gemfile.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Gemfile.lock b/Gemfile.lock index 5aa2138c..aef44dcd 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -238,7 +238,7 @@ GEM mutex_m (0.2.0) net-http (0.4.1) uri - nokogiri (1.16.7-x86_64-linux) + nokogiri (1.16.3-x86_64-linux) racc (~> 1.4) nokogiri (1.16.3-x86_64-linux) racc (~> 1.4) From 7cc9ea310650ca5908e5093ee35b92a16ccbcf8f Mon Sep 17 00:00:00 2001 From: Barb Cutler Date: Thu, 19 Jun 2025 00:51:43 -0400 Subject: [PATCH 5/6] Update Gemfile.lock --- Gemfile.lock | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index aef44dcd..b72622f9 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -238,9 +238,9 @@ GEM mutex_m (0.2.0) net-http (0.4.1) uri - nokogiri (1.16.3-x86_64-linux) + nokogiri (1.16.7-arm64-darwin) racc (~> 1.4) - nokogiri (1.16.3-x86_64-linux) + nokogiri (1.16.7-x86_64-linux) racc (~> 1.4) octokit (4.25.1) faraday (>= 1, < 3) @@ -270,16 +270,11 @@ GEM simpleidn (0.2.3) strscan (3.1.0) terminal-table (1.8.0) - unicode-display_width (~> 1.1, >= - 1.1.1) + unicode-display_width (~> 1.1, >= 1.1.1) typhoeus (1.4.1) ethon (>= 0.9.0) tzinfo (2.0.6) concurrent-ruby (~> 1.0) - 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) From 8cfb76951827d987062027369a473a37d8917bb3 Mon Sep 17 00:00:00 2001 From: Barb Cutler Date: Thu, 19 Jun 2025 00:53:13 -0400 Subject: [PATCH 6/6] Update Gemfile.lock --- Gemfile.lock | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index b72622f9..3032b006 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -277,21 +277,19 @@ GEM concurrent-ruby (~> 1.0) unicode-display_width (1.8.0) uri (0.13.0) - wdm (0.1.1) - webrick (1.8.1) + webrick (1.9.1) yell (2.2.2) PLATFORMS arm64-darwin-22 - x64-mingw-ucrt + arm64-darwin-23 x86_64-linux DEPENDENCIES github-pages (= 232) html-proofer (~> 3.19.4) json - wdm (>= 0.1.1) - webrick (~> 1.8) + webrick (~> 1.9) BUNDLED WITH 2.5.6