Page History: Poor Man's T-SQL Formatter

Compare Page Revisions

164 163 162 161 160 159 158 157 156 155 154 153 152 151 150 149 148 147 146 145 144 143 142 141 140 139 138 137 136 135 134 133 132 131 130 129 128 127 126 125 124 123 122 121 120 119 118 117 116 115 114 113 112 111 110 109 108 107 106 105 104 103 102 101 100 99 98 97 96 95 94 93 92 91 90 89 88 87 86 85 84 83 82 81 80 79 78 77 76 75 74 73 72 71 70 69 68 67 66 65 64 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Current 164 163 162 161 160 159 158 157 156 155 154 153 152 151 150 149 148 147 146 145 144 143 142 141 140 139 138 137 136 135 134 133 132 131 130 129 128 127 126 125 124 123 122 121 120 119 118 117 116 115 114 113 112 111 110 109 108 107 106 105 104 103 102 101 100 99 98 97 96 95 94 93 92 91 90 89 88 87 86 85 84 83 82 81 80 79 78 77 76 75 74 73 72 71 70 69 68 67 66 65 64 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

« Older Revision - Back to Page History - Newer Revision »

Page Revision: 2019-07-28 05:18

Overview

This is a free and open-source SQL (T-SQL) formatter:

• Handles complete multi-batch scripts, including object definition scripts such as stored procedures, triggers, etc.
• Provides formatting options to cater to different common formatting styles/standards
• Optionally outputs "colorized" html code rather than just the formatted SQL
• Also provides "minifier" option to strip out comments and whitespace, to obfuscate rather than pretty-print your code
• Available ready-to-use in a variety of forms
  • SSMS (SQL Server Management Studio) and Visual Studio Addin/Extension that allows you to format the current file or selected text with a single hotkey - supports any version of SSMS or SSMS Express, and any Full (not Express) version of Visual Studio.
  • Notepad++ plugin, for quick single-key formatting in your favorite general-purpose text editor.
  • Command-line utility that lets you format any number of files in bulk, or format from some other arbitrary program - for windows (.Net) or any environment (node/npm)
  • Winforms app for easy offline formatting (also lets you look at the token stream and parse tree)
  • WinMerge plugin, for automatically formatting SQL files before comparison, allowing WinMerge to display content changes only, ignoring formatting differences.
  • JS library that exposes the same functionality in any browser or other Javascript-based context, used in the demo/online formatting site http://poorsql.com
• Also available as a .Net 2.0/3.5 library, downloadable here or through NuGet
• Written in C# using a pluggable design that should allow for other SQL dialects to be supported in future
  

This formatter does implement a high-level SQL tokenizer and parser, but the granularity of the parser is not very high. It does not distinguish between different types of DML, it does not parse full expression trees, etc - there's a lot it doesn't do, it just does the bare minimum to support the target formatting.

The library is largely complete, but undocumented. For the list of known issues, please see the issue tracker on github. As there is only as much parsing detail as necessary to support the desired formatting, the parse tree format is still not finalized; many formatting enhancements require new elements in the parse tree.

The code is hosted on GitHub at https://github.com/TaoK/PoorMansTSqlFormatter; I'm always very grateful for any feedback on the functionality, the code or any other aspect of the project!

To keep an eye on new releases or other related news, Follow @PoorSQL

Tweets by @PoorSQL

I also send out occasional announcement emails to people who've contacted me - email me at if you'd like to get these announcements (this might eventually become a real mailing list).

Download

Ready-to-run:

• Extension for CURRENT VERSIONS of Visual Studio (2013-2019) (VSIX Package): Download from the Visual Studio Marketplace: https://marketplace.visualstudio.com/vsgallery/8ac2424b-80c9-431b-9049-6e7faa70c244
  

• Extension for CURRENT VERSIONS of SSMS (2014-18) (setup program): PoorMansTSqlFormatterSSMSPackage.Setup.1.6.13.msi (1375 downloads for this version, about 1600 for previous versions).
  

• Visual Studio Code extension: On the Visual Studio Marketplace: https://marketplace.visualstudio.com/items?itemName=TaoKlerks.poor-mans-t-sql-formatter-vscode
  

• Atom Editor plugin: In the Atom Package Manager: https://atom.io/packages/poor-mans-t-sql-formatter
  

• Notepad++ plugin: It's recommended to use the Notepad++ plugin manager if available (Notepad++ is an amazing free GPL-licensed text editor, available at notepad-plus-plus.org; it has a very rich plugin community available. Historically this was accessed through the "Plugin Manager" plugin, but this is no longer installed by default. The new Plugin -> Admin feature doesn't yet support Poor Man's T-SQL Formatter, but should soon).
  • If you need to install the plugin manually, you can get it from here: SqlFormatterNppPlugin.1.6.13.zip (28372 downloads for the latest version, about 410000 for previous versions).
    • For Notepad++ 7.5.9 and earlier, unzip the entire contents of the ZIP file (1 DLL + 1 folder containing other DLLs and stuff) into your Notepad++ install folder's "plugins" subfolder, eg "C:\Program Files\Notepad++\plugins".
    • For Notepad++ 7.6 to 7.6.2, upgrade. These versions had inconsistent plugin-loading folders (flip-flopping all over the place).
    • For Notepad++ 7.6.3 and later, if properly installed via installer, create a new folder called "PoorMansTSqlFormatterNppPlugin" in your Notepad++ install folder's "plugins" subfolder, eg "C:\Program Files\Notepad++\plugins\PoorMansTSqlFormatterNppPlugin", and unzip the entire contents of the ZIP file (1 DLL + 1 folder containing other DLLs and stuff) into this new subfolder. It's almost the same as before 7.6, except now the contents of the ZIP file ned to be in a correctly-named subfolder, not directly in the plugins folder.
      • If you've got a "portable" Notepad++ setup, then the old approach (unzip the entire contents of the ZIP file (1 DLL + 1 folder containing other DLLs and stuff) into your Notepad++ install folder's "plugins" subfolder) should still be the right thing.
    • If you get an error about the plugin not supporting unicode, then the wrong DLL is in the plugins folder, simply delete the incorrect DLLs and start again (please contact me for help if you have any issues with this).
  • 64-bit version : SqlFormatterNppPlugin.x64.1.6.13.zip (22601 downloads for the latest version, about 4350 for previous versions)
    

• Add-In for OLD VERSIONS of SSMS (2005-2012) and Visual Studio (2005-2012) (setup program): PoorMansTSqlFormatterSSMSAddIn.Setup.1.6.10.msi (11799 downloads for this version, about 130000 for previous versions).
  

• WinForms App (simple exe): SqlFormatterWinforms.1.6.13.zip (12331 downloads this version, about 32000 for previous versions)
  

• Command-line bulk formatting utility
  • Windows / .Net exe file: SqlFormatter.1.6.10.zip (16744 downloads for this version, about 14000 for previous versions)
  • Linux (and others) node-based commandline tool: Installable via npm - https://www.npmjs.com/package/poor-mans-t-sql-formatter-cli
    

• WinMerge Plugin for SQL Script comparison (setup program): PoorMansTSqlFormatterWinMergePlugin.Setup.1.5.1.msi (4759 downloads for this version, about 2000 for previous versions) (WinMerge is a free GPL-licensed file comparison tool, available at winmerge.org)
  

Compiled Library to use in other GPL/AGPL projects or internal non-distributed projects:

• SqlFormatterLibrary.1.6.13.zip - .Net 2.0 version (558 downloads for this version, about 1200 for previous versions)
• SqlFormatterLibrary35.1.6.13.zip - .Net 3.5 and later version (2938 downloads for this version, about 1700 for previous versions)
• (there's also a NuGet package, kindly set up and maintained by Adam Pawsey - but now quite outdated)
  

JS Library to use in other GPL/AGPL projects or internal non-distributed projects:

• NPM library: https://www.npmjs.com/package/poor-mans-t-sql-formatter
  

Source:

• Please download from github at https://github.com/TaoK/PoorMansTSqlFormatter. If this is impractical for whatever reason please contact me, and I'll make the source available by some other mechanism.
  

Latest Changes

1.6.13 - 2019-07-27

Added

• SSMS 18 and VS 2019
  

1.6.11 - 2017-11-24

Added

• Appveyor build configuration, as per proposal in Pull Request #178 from chcg
  

Changed

• Fixed newly split SSMS Extension Installer to set correct registry key at install time.
• Restructured changelog to follow Keep a Changelog(http://keepachangelog.com/)
  

Full Change Log:

• See the changelog on github
  

Known / Open Issues:

• See the issue tracker on github
  

License / Redistribution

The library and accompanying programs are released under the Affero GPL. This means that you are allowed to make any changes you want, there are restrictions/requirements attached only if you choose to redistribute the original or modified code: If you choose to redistribute/expose the functionality, then you must make the source available to the recipients/users (even of a web service). For private usage, you can make any changes you want and never need to tell anyone; if you distribute the app/functionality or a service that relies on it, then you must also distribute the source. For more details, please see the AGPL article on wikipedia or at the source, the FSF (free software foundation).

At least for the moment (as I'm the only one who has contributed to the project so far), the project could be dual-licensed if you really, really wanted to use it in a commercial program. If so please contact me, I'm sure we could work something out.

Tips & Tricks

• If you don't want a certain block of code to be reformatted, then just put a comment containing [noformat] before and [/noformat] after, like this:
  

  SELECT 1,
  2,
  3
  -- [noformat] don't want any formatting here, I like it with spaces before AND after the commas here.
  SELECT 4 , 5 , 6 , 7 , 8 , 9
  --[/noformat] 
  SELECT 1,
  2,
  3
  

• If you want to minimize the space taken by a chunk of SQL, and don't care about legibility, you can minify it with a comment containing [minify] before and [/minify] after, like this:
  

  SELECT 1,
  2,
  3
  --[minify] 
  SELECT 4AS[Four],5AS Five,6,7,8,9
  --[/minify] 
  SELECT 1,
  2,
  3
  

• Loren Halvorson pointed out you can use the command-line formatter to pre-format SQL files in Beyond Compare, with a command like this:

  SqlFormatter –o "%t" "%s"
  

• Paul Kohler shared a registry change he uses to format files from the Windows Explorer context menu (save as something.reg and run it):

  Windows Registry Editor Version 5.00
  [HKEY_CLASSES_ROOT\*\shell\Reformat SQL]
  [HKEY_CLASSES_ROOT\*\shell\Reformat SQL\command]
  @="C:\\Tools\\SqlFormatter.1.2.1\\SqlFormatter.exe \"%1\" /is:\"  \" /tc+"
  

• If you're the author of a SQL-related tool and you want to make use of the formatting library, but you don't want to release your project under the AGPL license, then you can always use the command-line formatter as an optional external tool. If you then redistribute the command-line tool you need to publish/provide the source of the formatter tool, but you don't need to relicense your project to match. Even simpler, you can suggest that users download the formatter separately to enable formatting functionality.
  

Feedback & Known Issues

For general feedback please email me at .

To browse existing / known issues or add new ones to be tracked, please use the GitHub issue tracker.

Instant Demo

The demo has been moved to poorsql.com - check it out and contact me with any issues!

Contributing

So far I many contributions, but contributing is easy with GitHub! Just fork the project, make your changes, and create a Pull Request for me to take a look and I will (if I agree with the changes of course) happily incorporate them!

https://github.com/TaoK/PoorMansTSqlFormatter

I need to formulate a "Contributor Agreement" to be able to accept any significant contributions, but that should be quick enough to do as the need arises, please let me know if you're interested.

Or if you just want to show your support, you can report your use of the project on Ohloh:

Background

Other Products and Projects

There is a comparison of all the SQL Formatting products that I know of, in wiki (editable) form, in the project wiki at https://github.com/TaoK/PoorMansTSqlFormatter/wiki/SQL-Formatter-comparisons.

(Previously there was a comparison table here, but it was years out of date and not editable by anyone but me. That was silly.)

Your Formatting preferences? Who are you?

The only reason my personal preferences are important here, is that I'm the one writing this :).

What I can do, however, is explain the rationale behind my preferences, in the hope that I might sway someone's opinion:

• I find that too much whitespace in the body/joins distracts from the structure of the query, especially if you end up having to scroll to find parts of the query. This is why I'm not fond of indenting the "ON" portion of a join clause
• I find that logical expressions are easiest to read (and write) when each portion is on its own line. This applies regardless of whether it's in a join clause's "ON" conditions, or the "WHERE" clause
• I find it very important to be able to write SQL (in a variety of editors) in the target format, without needing something to clean up after you. This is the main reason I don't like "Aligned" SQL formatting. I understand it can be more legible, but it's too much of a pain to maintain (esp. in embedded/ad-hoc SQL queries). It also breaks when you use tabs (in different editors with different tab stops), and I like tabs! They're easy-to-navigate whitespace!
  

What if I want my SQL formatted differently?

I am completely open to providing additional formatting options, obviously within the time I have available to devote to this project. Existing open requests are tracked on the GitHub issue tracker, with prefix "Option: ". As the project is open source and hosted on github, it's also trivial to fork the project, download to your local machine and get cracking on any changes you'd like to see!