Press "Enter" to skip to content

Category: Documentation

Production Code by Audience

Published 2022-11-14 by Kevin Feasel

Kenneth Fisher thinks about the audience:

I’ll be honest, all of that is pretty variable. It depends. There are lots of different types of code used in production.

For example, if your code is something you’ll be using yourself, you may not care about how robust it is. I mean you need to make sure it won’t do any harm if it fails, either through restartable steps, rolling back transactions, etc. But if it fails you’re right there to fix whatever went wrong and move on. You can almost think of it as a set of notes on how to do a process. Maintenance is also less of an issue because no one else is likely to be looking at it but you. You still probably want some documentation in case it’s been a while since you used the code and you’ve forgotten how that tricky bit works. And performance? Well, how patient are you? I’m not overly patient so performance is pretty important for code I’m running manually.

Read on for Kenneth’s take but also check out Jeff Moden’s response in the comments for the contrary view.

Comments closed

Commenting on Actions in Production

Published 2022-11-11 by Kevin Feasel

Andy Leonard wants to know whodunnit:

While “Commands completed successfully” is helpful to know – and definitely better than an error message – it does not inform the person executing the command precisely what just happened. Rather, “Commands completed successfully” informs the user that “something happened,” and as far as SQL Server Management Studio is concerned, whatever it was succeeded.

I prefer more details.

Andy also casually drops the concept of idempotence, which I define as saying that the end state is the same no matter how many times you run a specific process. My phrasing of the term is a little different though we get to the same point. Which is itself kind of an explanation of idempotence if you squint a little bit.

Comments closed

Power BI Model Documenter Version 2.1.0

Published 2022-11-08 by Kevin Feasel

Marc Lelijveld has a new version of the Power BI Model Documenter:

It is long overdue, but time for a new updated version for the Power BI Model Documenter external tool! The latest release lasts from the first week of 2022 and since then close to 6000 people have downloaded the Model Documenter installer directly from the website, excluding the downloads and clones from the GitHub repository. I can’t share enough how happy I am with all the interactions I’ve had with people from all over the world providing feedback, asking questions and willing to contribute to the Model Documenter.

Read on to see what’s changed since the last release.

Comments closed

Database Lineage with Extended Properties

Published 2022-10-19 by Kevin Feasel

Garry Bargsley shows a use for extended properties on databases:

Databases listed with 1, 2, 3, 4? What do those databases represent? Where did those databases come from?

Would you believe me if I told you there was a way to identify where the databases were sourced from?

A setting that can be used in SQL Server would allow the person who built these databases or restored them from another system to add a note.

Extended properties are very useful but also very easy to forget and difficult to manage. I’ve seen a few vendor products make great use of them but in-house development tends to ignore them.

Comments closed

Finding Guidance on Power BI

Published 2022-08-10 by Kevin Feasel

James Serra puts together a compendium:

Recently there has been a number of great articles published on Power BI that I wanted to make you aware of that go beyond the features descriptions found in the Power BI documentation. These new articles fall under the Power BI guidance documentation and are designed to address common strategic patterns.  Below is my summary of the articles, and check out Power BI guidance from the CAT by Matthew Roach for a more detailed summary.

If you’re interested in Power BI administration and strategic deployment, there’s a lot of good information here.

Comments closed

Power BI CAT Guidance

Published 2022-08-03 by Kevin Feasel

Matthew Roche advises customers:

I’ve written previously about some of what the Power BI CAT team does, but the Power BI guidance documentation only gets a passing mention… and it’s worth going into more deeply.

A lot of what the Power BI CAT team does involves working with large enterprise customers. These customers are often trying to achieve difficult goals that often involve complex data architectures, and Power BI is often a significant part of their end-to-end information supply chain. We get involved when these enterprise customers need help achieving their strategic goals, and this help often includes helping them effectively use the existing capabilities of Power BI.

Read on to learn more about this guidance documentation.

Comments closed

Running Diagnostic Notebooks via Powershell

Published 2022-07-27 by Kevin Feasel

Tracy Boggiano kicks off a notebook:

As part of starting a new job you need a way to get a good inventory of basic information of SQL Server instances.  Once you have done what I outlined in this blog post.  I find it helpful to run Glenn Alan Berry’s Diagnostic Notebooks against all the instances to get a static point in time snapshot of all the properties and some performance information.  While dbatools has commands under the Community Tools section for running the data into spreadsheets and creating notebooks for the newest queries I like to go get Glenn’s because he has all the comments in there of what the mean and links to resources about things.  So you can explore that route if you like but I’ll be manually downloading them from Glenn’s site for that reason.  To able to open the notebooks successfully in ADS look for the tip on my blog post on Tools I Use on My Jumpbox for opening large notebooks.

Click through for a script Tracy uses to kick off the notebook regardless of the SQL Server version.

Comments closed

Finding and Documenting SQL Server Instances

Published 2022-07-06 by Kevin Feasel

Tracy Boggiano continues a series on things to do at a new job as a DBA:

In my previous post, I expounded on my first 30 days I had at four jobs in the last four years. and how to setup your jobs box. I commented and got quoted on the fact that if it’s documented I don’t support it. So, these are methods of getting things documented, some including just having to have meetings, others running code.

One I believe in having a Central Management Server (CMS) where you can register your servers. Put them in as many groups as you desire but have core group such as Dev, Test, QA, UAT, Prod, Prod Sec, etc. The rest could be by application name if needed. I always have a set of names that are for the DBAs to use to do our work, other teams can have theirs for their work, i.e., deploying code.

If you aren’t using dbatools yet you should be. While not every shop can use to manage everything it is works every well for most tasks and that includes scanning the network for SQL Instances. Because unless you could into a well oiled machine there will be instances they don’t know about and one day someone will come knocking asking to fix it. Warn your security team before you run this.

Read on for examples of how you can find instances (assuming the security team is okay with it!), some of the information you’d want to document, and more. I would also recommend the most recent episode of the SQL Data Partners podcast, in which we talk to Jen and Sean McCown about documenting and managing your SQL Server inventory.

Comments closed

Searching Database Metadata in SQL Server

Published 2022-07-06 by Kevin Feasel

Phil Factor has a lookup function:

Finding things in databases isn’t always straightforward. You might think that you can just search the database objects in SQL Server. No, because user types, for example are stored elsewhere, despite being schema-bound. You might want to search in the scheduled jobs too, but there is no way of working out whether the code in a job step relates to a particular database. You might think that the information_schema represented a consistent industry standard, providing a rational logical layer over the seething reality underneath. You might be wrong.

Click through for the script and explanation.

Comments closed

Building a “Solution Summary” Card for Developers

Published 2022-07-05 by Kevin Feasel

Ben Brown gets the new developers up to speed:

Solution Summary cards are the name I have given to simple 1-page documents we provide to developers to get up-to-speed on a particular solution.

The primary use-case for these cards is to provide better on-boarding for new team members.

An additional benefit is that crafting these short summaries forces people to review how your teams are working and you will often start seeing areas which would benefit from standardization or simplification.   

Click through for an example. I like this idea a lot for a few reasons, which I’ll enumerate here because I’m feeling it:

  1. Developers often won’t read really long documents. They might scan through the documents, Ctrl+F a few words, and refer back to it on occasion but rarely will they read through a document in its entirety.
  2. Long documents get out of date too quickly, as developers are typically bad at keeping documentation up to date, especially as deadlines loom.
  3. An artificial constraint like “Your summary must fit on one printed page” (either front-only or front-and-back) helps focus the mind. It makes you think about what the most important things to include are.
  4. If you are a consultant or just work on a lot of different projects, it can be painful trying to remember the details. Which jump box do you need to go to? Which were the most important bits of code? How do you run the unit tests and deploy the app locally? Even if nobody else ever sees the card, it can help you in the future.
Comments closed