SQL Explainer
2 |SQL Explainer is a VS Code extension that uses the OpenAI API to translate SQL queries into English. With this extension, you can quickly understand what a query does and why it's important without having to spend time deciphering SQL code.
3 |Getting Started
4 |To use SQL Explainer, you'll need to get an API key from OpenAI. If you don't have one already, you can sign up for a free account at https://platform.openai.com/signup.
5 |Once you have an API key, you can install SQL Translator by following these steps:
6 |-
7 |
- Install the extension 8 |
- Open a file in VS Code and select the query you want to translate. 9 |
- Open the Command Palette by pressing
Ctrl+Shift+P(Windows, Linux) orCmd+Shift+P(macOS).
10 | - Type "SQL Explainer" in the search bar and select the "SQL Explainer: Translate Query" command. 11 |
- If prompted, enter your OpenAI API key and press Enter. (will be asked only the first time) 12 |
Once you've completed these steps, a window will open on the right side of the screen, showing you the translated query in English. You can also see a shorter explanation (tldr) of the query below the full explanation.
14 | 15 |
16 |
17 | Contributing
18 |If you encounter any bugs or have suggestions for new features, please feel free to open an issue or submit a pull request on GitHub. Contributions are always welcome!
19 |License
20 |SQL Translator is released under the GNU GENERAL PUBLIC License.
21 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "vscode-sql-explainer", 3 | "displayName": "sql-explainer", 4 | "publisher": "al366io", 5 | "description": "Translates SQL Queries and explains them", 6 | "version": "1.0.4", 7 | "engines": { 8 | "vscode": "^1.75.0" 9 | }, 10 | "categories": [ 11 | "Other" 12 | ], 13 | "activationEvents": [ 14 | "onCommand:vscode-sql-explainer.SQLExplainer" 15 | ], 16 | "main": "./dist/extension.js", 17 | "icon": "images/icon.png", 18 | "repository": { 19 | "url": "https://github.com/Al366io/vscode-sql-explainer" 20 | }, 21 | "contributes": { 22 | "commands": [ 23 | { 24 | "command": "vscode-sql-explainer.SQLExplainer", 25 | "title": "SQL Explainer: Translate Query" 26 | } 27 | ] 28 | }, 29 | "scripts": { 30 | "vscode:prepublish": "npm run package", 31 | "compile": "webpack", 32 | "watch": "webpack --watch", 33 | "package": "webpack --mode production --devtool hidden-source-map", 34 | "compile-tests": "tsc -p . --outDir dist", 35 | "watch-tests": "tsc -p . -w --outDir out", 36 | "pretest": "npm run compile-tests && npm run compile && npm run lint", 37 | "lint": "eslint src --ext ts", 38 | "test": "node ./out/test/runTest.js" 39 | }, 40 | "devDependencies": { 41 | "@types/glob": "^8.0.1", 42 | "@types/mocha": "^10.0.1", 43 | "@types/node": "16.x", 44 | "@types/vscode": "^1.75.0", 45 | "@typescript-eslint/eslint-plugin": "^5.49.0", 46 | "@typescript-eslint/parser": "^5.49.0", 47 | "@vscode/test-electron": "^2.2.2", 48 | "eslint": "^8.33.0", 49 | "glob": "^8.1.0", 50 | "mocha": "^10.1.0", 51 | "ts-loader": "^9.4.2", 52 | "typescript": "^4.9.4", 53 | "webpack": "^5.75.0", 54 | "webpack-cli": "^5.0.1" 55 | }, 56 | "dependencies": { 57 | "node-sql-parser": "^4.6.5" 58 | } 59 | } 60 | -------------------------------------------------------------------------------- /vsc-extension-quickstart.md: -------------------------------------------------------------------------------- 1 | # Welcome to your VS Code Extension 2 | 3 | ## What's in the folder 4 | 5 | * This folder contains all of the files necessary for your extension. 6 | * `package.json` - this is the manifest file in which you declare your extension and command. 7 | * The sample plugin registers a command and defines its title and command name. With this information VS Code can show the command in the command palette. It doesn’t yet need to load the plugin. 8 | * `src/extension.ts` - this is the main file where you will provide the implementation of your command. 9 | * The file exports one function, `activate`, which is called the very first time your extension is activated (in this case by executing the command). Inside the `activate` function we call `registerCommand`. 10 | * We pass the function containing the implementation of the command as the second parameter to `registerCommand`. 11 | 12 | ## Setup 13 | 14 | * install the recommended extensions (amodio.tsl-problem-matcher and dbaeumer.vscode-eslint) 15 | 16 | 17 | ## Get up and running straight away 18 | 19 | * Press `F5` to open a new window with your extension loaded. 20 | * Run your command from the command palette by pressing (`Ctrl+Shift+P` or `Cmd+Shift+P` on Mac) and typing `Hello World`. 21 | * Set breakpoints in your code inside `src/extension.ts` to debug your extension. 22 | * Find output from your extension in the debug console. 23 | 24 | ## Make changes 25 | 26 | * You can relaunch the extension from the debug toolbar after changing code in `src/extension.ts`. 27 | * You can also reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes. 28 | 29 | 30 | ## Explore the API 31 | 32 | * You can open the full set of our API when you open the file `node_modules/@types/vscode/index.d.ts`. 33 | 34 | ## Run tests 35 | 36 | * Open the debug viewlet (`Ctrl+Shift+D` or `Cmd+Shift+D` on Mac) and from the launch configuration dropdown pick `Extension Tests`. 37 | * Press `F5` to run the tests in a new window with your extension loaded. 38 | * See the output of the test result in the debug console. 39 | * Make changes to `src/test/suite/extension.test.ts` or create new test files inside the `test/suite` folder. 40 | * The provided test runner will only consider files matching the name pattern `**.test.ts`. 41 | * You can create folders inside the `test` folder to structure your tests any way you want. 42 | 43 | ## Go further 44 | 45 | * Reduce the extension size and improve the startup time by [bundling your extension](https://code.visualstudio.com/api/working-with-extensions/bundling-extension). 46 | * [Publish your extension](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) on the VS Code extension marketplace. 47 | * Automate builds by setting up [Continuous Integration](https://code.visualstudio.com/api/working-with-extensions/continuous-integration). 48 | -------------------------------------------------------------------------------- /src/helpers/translateQuery.ts: -------------------------------------------------------------------------------- 1 | /** 2 | fairly complex sql query to try: 3 | 4 | SELECT 5 | c.customer_id, 6 | c.first_name, 7 | c.last_name, 8 | COUNT(o.order_id) AS num_orders, 9 | SUM(oi.quantity * oi.price) AS total_spent 10 | FROM 11 | customers c 12 | LEFT JOIN orders o ON c.customer_id = o.customer_id 13 | LEFT JOIN order_items oi ON o.order_id = oi.order_id 14 | WHERE 15 | o.order_date BETWEEN '2022-01-01' AND '2022-12-31' 16 | GROUP BY 17 | c.customer_id 18 | HAVING 19 | num_orders > 0 20 | ORDER BY 21 | total_spent DESC, num_orders DESC 22 | LIMIT 10; 23 | 24 | */ 25 | 26 | import fetch from 'node-fetch'; 27 | import { Parser } from 'node-sql-parser'; 28 | const parser = new Parser(); 29 | 30 | // check if the SQL query is valid by trying to parse it 31 | const isSqlQueryValid = (sqlQuery: string) => { 32 | try { 33 | parser.parse(sqlQuery); 34 | return true; 35 | } catch (error) { 36 | return false; 37 | } 38 | }; 39 | 40 | // translate the SQL query using OpenAI's davinci model 41 | export default async function translateSQL(sqlQuery: string, OPENAI_KEY: string) { 42 | 43 | // check if the SQL query is valid 44 | if (!isSqlQueryValid(sqlQuery)) { 45 | return { fullTranslation: null, tldrTranslation: null, error: 'Invalid SQL query'}; 46 | } 47 | 48 | try { 49 | const response = await fetch(`https://api.openai.com/v1/completions`, { 50 | method: 'POST', 51 | headers: { 52 | 'Content-Type': 'application/json', 53 | Authorization: `Bearer ${OPENAI_KEY}`, 54 | }, 55 | body: JSON.stringify({ 56 | model: 'text-davinci-003', 57 | prompt: `Explain in detail and in English, the following SQL query: ${sqlQuery} \n`, 58 | temperature: 0.1, 59 | max_tokens: 1024, 60 | top_p: 0.1, 61 | frequency_penalty: 0, 62 | presence_penalty: 0, 63 | }), 64 | }); 65 | const data: any = await response.json(); 66 | 67 | // if the response has "error" in it, it means the API key is invalid 68 | if(data.error) { 69 | return { fullTranslation: null, tldrTranslation: null, error: 'Invalid API key'}; 70 | } 71 | 72 | const tldrResponse = await queryTldr(sqlQuery, OPENAI_KEY); 73 | 74 | return { 75 | fullTranslation: data.choices[0].text, 76 | tldrTranslation: tldrResponse, 77 | error: null, 78 | }; 79 | } catch (error) { 80 | return { fullTranslation: null, tldrTranslation: null, error: 'Generic error'}; 81 | } 82 | } 83 | 84 | async function queryTldr(sqlQuery: string, OPENAI_KEY: string) { 85 | try { 86 | const response = await fetch(`https://api.openai.com/v1/completions`, { 87 | method: 'POST', 88 | headers: { 89 | 'Content-Type': 'application/json', 90 | Authorization: `Bearer ${OPENAI_KEY}`, 91 | }, 92 | body: JSON.stringify({ 93 | model: 'text-davinci-003', 94 | prompt: `Explain shortly in less than 200 characters and in English, the following SQL query: ${sqlQuery} \n`, 95 | temperature: 0.1, 96 | max_tokens: 500, 97 | top_p: 0.1, 98 | frequency_penalty: 0, 99 | presence_penalty: 0, 100 | }), 101 | }); 102 | const data: any = await response.json(); 103 | return data.choices[0].text; 104 | } catch (error) { 105 | return null; 106 | } 107 | } 108 | -------------------------------------------------------------------------------- /src/extension.ts: -------------------------------------------------------------------------------- 1 | import * as vscode from 'vscode'; 2 | import translateSQL from './helpers/translateQuery'; 3 | import { getApiKey, loadPages } from './helpers/helpers'; 4 | 5 | // define the webview panel, so we can check if it is already open 6 | let panel: vscode.WebviewPanel | undefined; 7 | 8 | // This method is called when the extension is activated 9 | export function activate(context: vscode.ExtensionContext) { 10 | // context.globalState.update('OpenAiApiKey', undefined); 11 | // load pages from the views folder 12 | const { loadingHtmlContent, errorHtmlContent, noKeyHtmlContent } = 13 | loadPages(context); 14 | 15 | let disposable = vscode.commands.registerCommand( 16 | 'vscode-sql-explainer.SQLExplainer', 17 | async () => { 18 | // get the API key from the user's settings 19 | let OpenAiApiKey = await getApiKey(context); 20 | 21 | // get the active text editor 22 | const editor = vscode.window.activeTextEditor; 23 | 24 | if (editor) { 25 | // get the selected text 26 | const selection = editor.selection; 27 | const selectedText = editor.document.getText(selection); 28 | 29 | // if the panel is not open, create it. Else just show it 30 | if (!panel) { 31 | panel = vscode.window.createWebviewPanel( 32 | 'webviewPanel', 33 | 'SQL Explainer', 34 | vscode.ViewColumn.Two, // set the view column to position the panel on the right 35 | {} 36 | ); 37 | panel.onDidDispose(() => { 38 | panel = undefined; 39 | }); 40 | } else { 41 | panel.webview.html = ''; 42 | panel.reveal(); 43 | } 44 | 45 | // if there is no API key, show the error message 46 | if (!OpenAiApiKey) return (panel.webview.html = noKeyHtmlContent); 47 | 48 | // if there is no text selected, show the error message 49 | if (!selectedText) return (panel.webview.html = errorHtmlContent); 50 | 51 | // while the translation is being done, show a loading spinner 52 | panel.webview.html = loadingHtmlContent; 53 | 54 | // translate the SQL query 55 | let { fullTranslation, tldrTranslation, error } = await translateSQL( 56 | selectedText, 57 | OpenAiApiKey 58 | ); 59 | 60 | // if there is an error, show the error message 61 | if (error) { 62 | switch (error) { 63 | case 'Invalid SQL query': 64 | return (panel.webview.html = errorHtmlContent); 65 | 66 | case 'Invalid API key': 67 | return (panel.webview.html = noKeyHtmlContent); 68 | } 69 | } 70 | 71 | // return content to the webview panel 72 | panel.webview.html = ` 73 | 74 | 75 | 76 | 77 |SQL Explainer
79 |
81 |
84 |
87 |
88 | `;
89 | }
90 | }
91 | );
92 | context.subscriptions.push(disposable);
93 | }
94 |
95 | // This method is called when the extension is deactivated
96 | export function deactivate() {
97 | // Close the webview panel when the extension is deactivated
98 | if (panel) {
99 | // This closes the panel if it showing and disposes of the resources owned by the webview
100 | panel.dispose();
101 | panel = undefined;
102 | }
103 | }
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | GNU GENERAL PUBLIC LICENSE
2 | Version 3, 29 June 2007
3 |
4 | Copyright (C) 2007 Free Software Foundation, Inc. Full Explanation:
82 |${fullTranslation}
83 |
84 |
TLDR
85 |${tldrTranslation}
86 |