Database Documentation extension: generates mermaid diagrams for databases, schemas, and tables #23409

laurennathan · 2023-06-16T23:38:36Z

Starting code for the database documentation extension. Code generates mermaid diagrams for databases, schemas and tables

Charles-Gagnon · 2023-06-17T01:17:45Z

extensions/database-documentation/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+ "root": true,


Remove this and use the same eslintrc we have in other extensions (except with different project path) so we get all the default eslint stuff for extensions automatically

Charles-Gagnon · 2023-06-17T01:18:12Z

extensions/database-documentation/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change Log


Remove this for now - we don't usually have a changelog for extensions

extensions/database-documentation/README.md

Charles-Gagnon · 2023-06-17T01:19:45Z

extensions/database-documentation/installTypings.js

+ * Licensed under the Source EULA. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+var https = require('https');


Remove this, not needed for extensions living in the ADS repo. The refs.d.ts will point directly to them instead.

extensions/database-documentation/package-lock.json

Charles-Gagnon · 2023-06-17T01:23:39Z

extensions/database-documentation/src/extension.ts

+ // The commandId parameter must match the command field in package.json
+ context.subscriptions.push(vscode.commands.registerCommand('database-documentation.generateDocumentation', async (context: azdata.ObjectExplorerContext) => {
+ // The code you place here will be executed every time your command is executed
+ vscode.window.showInformationMessage("Generating Documentation... ");


This (and all other user-visible messages) should be localized (see other extensions for an example using the localize function)

Charles-Gagnon · 2023-06-17T01:24:17Z

extensions/database-documentation/src/extension.ts

+ // Use the console to output diagnostic information (console.log) and errors (console.error)
+ // This line of code will only be executed once when your extension is activated
+ console.log('Congratulations, your extension "database-documentation" is now active!');
+
+


Suggested change

// Use the console to output diagnostic information (console.log) and errors (console.error)

// This line of code will only be executed once when your extension is activated

console.log('Congratulations, your extension "database-documentation" is now active!');

Charles-Gagnon · 2023-06-17T01:24:48Z

extensions/database-documentation/src/test/suite/extension.test.ts

+import * as vscode from 'vscode';
+// import * as myExtension from '../../extension';
+
+suite('Extension Test Suite', () => {


Remove these test files for now if you aren't going to add any real tests to start with

Charles-Gagnon · 2023-06-17T01:26:25Z

extensions/database-documentation/vsc-extension-quickstart.md

@@ -0,0 +1,37 @@
+# Welcome to your Azure Data Studio Extension


Remove this

Charles-Gagnon · 2023-06-17T01:27:23Z

extensions/database-documentation/test.md

@@ -0,0 +1,20 @@
+```mermaid


What's this for?

Charles-Gagnon · 2023-06-18T17:00:57Z

There's some additional files that need to be updated as well, see #23260 for an example

Charles-Gagnon · 2023-06-20T21:38:55Z

extensions/database-documentation/.eslintrc.json

+ "project": "./extensions/database-documentation/tsconfig.json"
+ },
+ "rules": {
+ // Disabled until the issues can be fixed


Please don't disable this - all new extensions should be fixing issues right away instead

Charles-Gagnon · 2023-06-20T21:39:40Z

extensions/database-documentation/package.json

+ "Other"
+ ],
+ "activationEvents": [
+ "*"


Please make an issue to track finding a better activation event for this - we should have as few * activations as possible.

Charles-Gagnon · 2023-06-20T21:40:40Z

extensions/database-documentation/package.json

+ "mermaid": "^10.1.0",
+ "mocha": "^9.1.0",
+ "typescript": "^4.3.5",
+ "vscode-nls": "^4.0.0",


These are already in dependencies section

Charles-Gagnon · 2023-06-20T21:41:57Z

extensions/database-documentation/src/common/utils.ts

+
+const localize = nls.loadMessageBundle();
+
+export async function generateMarkdown(context: azdata.ObjectExplorerContext): Promise<string> {


@aasimkhan30 Please make sure someone is reviewing this code - I won't have time to spend on this at the moment

(and ideally this is actually done in a separate PR, but I'll leave that up to you two)

Charles-Gagnon · 2023-06-20T21:42:47Z

extensions/database-documentation/src/common/utils.ts

+ else {
+ const queryProvider = azdata.dataprotocol.getProvider<azdata.QueryProvider>("MSSQL", azdata.DataProviderType.QueryProvider);
+ const connectionUri = await azdata.connection.getUriForConnection(connection.connectionId);
+ let query = `SELECT TABLE_NAME FROM [${databaseName}].INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE = 'BASE TABLE'`;


Make sure you're escaping ] and ' whenever you manual create T-SQL statements like this to prevent SQL injection type issues. (easy way is to test with a DB that has both those characters in its name)

https://learn.microsoft.com/en-us/sql/relational-databases/security/sql-injection?view=sql-server-ver16

make sure this comment is addressed.

Charles-Gagnon · 2023-06-20T21:46:18Z

extensions/database-documentation/tsconfig.json

+ "strict": false,
+ "noImplicitAny": false,
+ "noImplicitReturns": false,
+ "noUnusedLocals": false,
+ "strictNullChecks": false,


Remove these and fix any issues - all new extensions shouldn't be disabling these

Suggested change

"strict": false,

"noImplicitAny": false,

"noImplicitReturns": false,

"noUnusedLocals": false,

"strictNullChecks": false,

kburtram · 2023-06-21T17:55:53Z

@laurennathan could you please rebase this PR to merge from one "feature branch" to another? We can take into main at the end of your project. This should allow you to create multiple PRs for changes incrementally without having to get the code into a production state upfront.

kburtram · 2023-06-21T18:41:34Z

extensions/database-documentation/src/common/utils.ts

+ let databaseName = context.connectionProfile.databaseName;
+
+ let tables: string[];
+ if (context.nodeInfo.nodeType === 'Table') {


are we also going to support views, sprocs, or other schema objects?

kburtram · 2023-06-21T18:44:08Z

extensions/database-documentation/src/common/utils.ts

+ tables = (await queryProvider.runQueryAndReturn(connectionUri, query)).rows.map(row => row[0].displayValue);
+ }
+
+ let diagram = '```mermaid\nclassDiagram\n';


have you tried using an erDiagram? I think that is the more appropriate chart for a db schema and wonder if there is any differences built in, such as displaying cardinalities on relationships, or something like that?

kburtram

Please rebase off a "feature branch" off main and let's iterate there for a few more weeks before going into main branch. This will enable you to send more frequent PRs for smaller bits of functionality through the project.

extensions/database-documentation/src/common/utils.ts

alanrenmsft · 2023-06-23T21:28:14Z

extensions/database-documentation/.vscodeignore

+out/test
+src
+.gitignore
+vsc-extension-quickstart.md


for this file and the .gitignore file, please only leave the entries that are relevant to your extension.

alanrenmsft · 2023-06-23T21:31:49Z

extensions/database-documentation/package.nls.json

@@ -0,0 +1,5 @@
+{
+ "displayName": "Database Documentation and Diagrams",
+ "description": "Generate Documentation and Diagrams for Database Schemas",


the description doesn't seem to be accurate.

Mention this is only for Microsoft SQL Server and SQL Database.

IIUC, this extension works with databases, schemas, tables and views.

alanrenmsft · 2023-06-23T21:34:48Z

extensions/database-documentation/src/common/utils.ts

+import * as azdata from 'azdata'
+import * as vscode from 'vscode';
+// Language localization features
+import * as nls from 'vscode-nls';


these comments are not needed

alanrenmsft · 2023-06-23T21:44:03Z

extensions/database-documentation/src/common/utils.ts

+ let query = `SELECT TABLE_NAME FROM [${databaseName}].INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE = 'BASE TABLE'`;
+
+ if (context.nodeInfo.nodeType === 'Schema') {
+ query += ` AND TABLE_SCHEMA = '${context.nodeInfo.metadata.name}'`;


potential sql injection risk.

laurennathan requested review from kburtram, aasimkhan30, alanrenmsft and Charles-Gagnon June 16, 2023 23:44

Charles-Gagnon reviewed Jun 17, 2023

View reviewed changes

laurennathan mentioned this pull request Jun 19, 2023

Update README.md for database documentation extension #23415

Closed

Charles-Gagnon reviewed Jun 20, 2023

View reviewed changes

kburtram reviewed Jun 21, 2023

View reviewed changes

kburtram approved these changes Jun 23, 2023

View reviewed changes

kburtram reviewed Jun 23, 2023

View reviewed changes

extensions/database-documentation/src/common/utils.ts Outdated Show resolved Hide resolved

alanrenmsft reviewed Jun 23, 2023

View reviewed changes

laurennathan closed this Jun 26, 2023

laurennathan force-pushed the laurennathan/database-documentation-PR branch from a02d845 to 5f7a182 Compare June 26, 2023 21:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Database Documentation extension: generates mermaid diagrams for databases, schemas, and tables #23409

Database Documentation extension: generates mermaid diagrams for databases, schemas, and tables #23409

laurennathan commented Jun 16, 2023

Charles-Gagnon Jun 17, 2023

Charles-Gagnon Jun 17, 2023

Charles-Gagnon Jun 17, 2023

Charles-Gagnon Jun 17, 2023

Charles-Gagnon Jun 17, 2023

Charles-Gagnon Jun 17, 2023

Charles-Gagnon Jun 17, 2023

Charles-Gagnon Jun 17, 2023

Charles-Gagnon commented Jun 18, 2023

Charles-Gagnon Jun 20, 2023

Charles-Gagnon Jun 20, 2023

Charles-Gagnon Jun 20, 2023

Charles-Gagnon Jun 20, 2023

Charles-Gagnon Jun 20, 2023

alanrenmsft Jun 23, 2023

Charles-Gagnon Jun 20, 2023

kburtram commented Jun 21, 2023

kburtram Jun 21, 2023

kburtram Jun 21, 2023

kburtram left a comment

alanrenmsft Jun 23, 2023

alanrenmsft Jun 23, 2023

alanrenmsft Jun 23, 2023

alanrenmsft Jun 23, 2023

	// Use the console to output diagnostic information (console.log) and errors (console.error)
	// This line of code will only be executed once when your extension is activated
	console.log('Congratulations, your extension "database-documentation" is now active!');

		@@ -0,0 +1,37 @@
		# Welcome to your Azure Data Studio Extension


		const localize = nls.loadMessageBundle();

		export async function generateMarkdown(context: azdata.ObjectExplorerContext): Promise<string> {

Database Documentation extension: generates mermaid diagrams for databases, schemas, and tables #23409

Database Documentation extension: generates mermaid diagrams for databases, schemas, and tables #23409

Conversation

laurennathan commented Jun 16, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Charles-Gagnon commented Jun 18, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kburtram commented Jun 21, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kburtram left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment