Page History: Poor Man's T-SQL Formatter
Compare Page Revisions
Page Revision: 2017-11-24 04:20
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,
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:
- 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 through the "Plugin Manager" plugin. This is no longer installed by default, but adding it is very easy, and some replacement will presumably be made available shortly).
- If you need to install the plugin manually, you can get it from here: SqlFormatterNppPlugin.1.6.10.zip (15367 downloads for the latest version, about 400000 for previous versions) and 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". 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.10.zip (5297 downloads for the latest version, about 350 for previous versions)
- Command-line bulk formatting utility
Compiled Library to use in other GPL/AGPL projects or internal non-distributed projects:
JS Library to use in other GPL/AGPL projects or internal non-distributed projects:
Source:
Latest Changes
FORMATTER ERROR (Malformed List)
FORMATTER ERROR (Malformed List)
- Appveyor build configuration, as per proposal in Pull Request #178 from chcg
FORMATTER ERROR (Malformed List)
- 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:
Known / Open Issues:
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/PoorMansTSqlFormatterI 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!