treffynnon / sqlstyle.guide

A consistent code style guide for SQL to ensure legible and maintainable projects

SQL style guide

☛ Read the guide

---

General

The guide is written in Markdown and uses Jekyll via GitHub's Pages facility to render itself upon pushing to the gh-pages branch.

Sources

The markdown source for the guide can be found in _includes/sqlstyle.guide.md

Installing for local development

There is a Gemfile supplied so you just need to follow the GitHub Pages documentation to install the dependencies.

To then run it locally bundle exec jekyll serve

Translations of the guide

If you would like to translate the guide then please open a pull request or open an issue if you need some help getting it setup.

• German/Deutsch by AStasyK
• French/Français by IdrissaD
• Italian/Italiano by robertopauletto
• Japanese/日本語 by nkurigit
• Korean/한국어 by Dokyeongyun
• Polish/Polski by andre-wojtowicz
• Portuguese (Brazil)/Português (BR) by pmarcus93
• Russian/Русский by denpatin
• Simplified Chinese/简体中文 by wontoncoder
• Traditional Chinese/正體中文 by Leon0824
• Turkish/Türkçe by mrfade
• Ukrainian/Українська by yar-lukomsky
• Vietnamese/Tiếng Việt by Vũ Phượng Hoàng

Projects known to be implementing the guide

If your project uses this styleguide and you'd like to be mentioned in this readme then please open a pull request adding it below in alphabetical order with a URL and short description.

You can also add a badge () to your projects readme with the following markdown code if you like:

[![sqlstyle.guide](https://img.shields.io/badge/style-sqlstyle.guide-brightgreen.svg)](https://www.sqlstyle.guide/)

• BEdita - a Symfony based PHP CMF
• SQLQuery.jl - A Julia lang package for representing sql queries, and converting them to valid SQL statements
• Stock Talk - a realtime dashboard that displays the stock data of the most Tweeted Nasdaq companies.

Notable forks of the guide

These are based on, but deviate in some way from sqlstyle.guide.

If you have forked this styleguide and you'd like to be mentioned in this readme then please open a pull request adding it below in alphabetical order with a URL and short description of your deviance.

• Lumos Labs - removed the river, Redshift, etc. www
• Mozilla - removed the river, heavily modified www
• Ricardo.ch
• Scout24

sqlstyle.guide's Issues

ISO Date/Time Format

Hey folks,

the guide states

Store ISO 8601 compliant time and date information (YYYY-MM-DD HH:MM:SS.SSSSS).

I read that as "store it in this format" - but as far as I know, ISO either requires a T between date and time or having nothing there, but not a space.

See https://stackoverflow.com/questions/9531524/in-an-iso-8601-date-is-the-t-character-mandatory

Maybe the T should be included in the ISO string?
Or maybe my reading was wrong and it does not mean "store in that format"?

Reconsider JOIN Style

I do not like your style in the JOIN area.
The goal of a JOIN Style is to fast recognize tables you use for joining and the ON conditions.

Dutch translation

I've been missing a Code Styling Guide for SQL for many years. Great project and exactly the style I like. I'd like to translate it to a Dutch version. Let me know if there is any interest.

Comma before the column field?

I haven't read the book, but shouldn't you insert commas before the column name?

 SELECT tableID
      , first_name
      , last_name 
     --, middle_name

If you need to comment out the last line, you don't have to implement a new comma. And as a plus, all of the commas are neatly lined up.

Add list of linters / editor plugins implementing the styleguide to the readme

Hi,
I'm creating this issue as a follow-up to a question on twitter.
The idea is to be able to follow this issue to be notified, when there are plugins/linters available.

Ideas for implementation:

• Eslint plugin like gajus/eslint-plugin-sql
• php-cs-fixer plugin
• standalone linter like sqllint

Backticks (backquotes?) in style.

Hello,

The guide isn't particularly clear as to the use of backticks/backquotes (`) in SQL. SQL-92 makes no statement regarding the use of backticks encapsulating column identifiers, however many MySQL tools produce formatted queries with backticks to avoid reserved word collisions in column titles.

Whilst the guide states quite clearly that reserved words should not be used for identifiers, without clarification it seems as though it would be an optional component.

My personal take is: It's visual pollution, don't do it unless it is absolutely necessary and then only keep it to where necessary (around reserved identifiers in legacy data structures). But my preference likely does not represent the wider community 😄

Style guide web link is not reachable.

Hi,

I loved your SQL style guide and used to refer it every time I am not sure about formatting something in SQL. Today, I found that http://www.sqlstyle.guide and https://www.sqlstyle.guide/ are not reachable. I tried from chrome and IE 11.

So I just wanted to check if you moved it or something is being worked on. Another possibility I could think of is the security certificate. Recently few other sites I used to refer for technical stuff also had problems because of security certificate settings.

I would love to keep visiting it every time I am not sure how to format something in SQL.

Thank you for creating such a nice content.

Regards.

How are you aligning the first word on each line?

I came across your style guide and wasn't sure how you align the first word of every line to the length of the first word? I thought maybe you were using VIM but I couldn't find any key combinations to accomplish this style. Can you give me some tips? or are you just simply pressing spacebar on every line?

clicking link doesn't update fragment in URL

Clicked on 'reserved keyword reference' but instead of browser URL updating to https://www.sqlstyle.guide/#reserved-keyword-reference it remains https://www.sqlstyle.guide.

Fixing this would more easily allow sharing link to point someone at a specific item from the guide instead of having to dig around dev tools to grab the URL.

Some additional uniform-suffixes for consideration

Hi Simon,
Below are some additional uniform-suffixes for consideration:

• _dtime—denotes a column that contains the DATETIME for something.
• _dtime_utc—denotes a column that contains the DATETIME in the UTC timezone.
• _time—denotes a column that contains the TIME for something.
• is_—a boolean column (this is a prefix).
• can_—a boolean column (this is a prefix).
• has_—a boolean column (this is a prefix).

References:

• https://towardsdatascience.com/10-sql-standards-to-make-your-code-more-readable-in-2021-4410dc50b909
• #74

regards

JOIN in Aliasing or correlations example not indented right

Here is the example found at (https://www.sqlstyle.guide/#aliasing-or-correlations)[https://www.sqlstyle.guide/#aliasing-or-correlations] :

SELECT first_name AS fn
  FROM staff AS s1
  JOIN students AS s2
    ON s2.mentor_id = s1.staff_num;

and you wrote below, at (https://www.sqlstyle.guide/#joins)[https://www.sqlstyle.guide/#aliasing-or-correlations]:
Joins should be indented to the other side of the river

GROUP BY, UNION ALL, etc. incompatible with "river"

  SELECT one,
         two,
         three,
         five
    FROM some_table
         INNER JOIN (SELECT five,
                            six,
                            seven
                       FROM another_table
                      WHERE field = 'special'
                   GROUP BY 1

                  UNION ALL

                     SELECT five,
                            eight,
                            nine
                       FROM third_table
                      WHERE something > 2
                   GROUP BY 1)
         USING (five)
   WHERE field = 'default'
GROUP BY 1, 2

Please see the inner GROUP BY statements and the UNION ALL: is this the recommended style? It preserves the river, but at the cost of the GROUP BY and UNION ALL "overflowing" left of the open parentheses, violating the alignment. One possible fix is to add space to the left side of the subquery:

  SELECT one,
         two,
         three,
         five
    FROM some_table
         INNER JOIN (   SELECT five,
                               six,
                               seven
                          FROM another_table
                         WHERE field = 'special'
                      GROUP BY 1

                     UNION ALL

                        SELECT five,
                               eight,
                               nine
                          FROM third_table
                         WHERE something > 2
                      GROUP BY 1)
         USING (five)
   WHERE field = 'default'
GROUP BY 1, 2

Another fix is to simply move the entire subquery left, breaking alignment with the parentheses:

  SELECT one,
         two,
         three,
         five
    FROM some_table
         INNER JOIN (
             SELECT five,
                    six,
                    seven
               FROM another_table
              WHERE field = 'special'
           GROUP BY 1

          UNION ALL

             SELECT five,
                    eight,
                    nine
               FROM third_table
              WHERE something > 2
           GROUP BY 1)
         USING (five)
   WHERE field = 'default'
GROUP BY 1, 2

Is CC BY-SA 4.0 the proper license for sqlstyle.guide?

In addition to #43 and #44 in order to increase popularity and adaptability. It might be more attractive for developers to adapt, when another licensing model is used. The currently used CC BY-SA 4.0 is discouraged because of the common problem with "license proliferation".

Even while this isn't code but text, I'm thinking about the MIT license but probably others have more experience with this. Also see: https://opensource.stackexchange.com/questions/1717/why-is-cc-by-sa-discouraged-for-code?utm_medium=organic&utm_source=google_rich_qa&utm_campaign=google_rich_qa

Japanese translation

A work in progress.

[just suggestion] from gitlab style (indentation 2 spaces)

suggestion

• I like sql, I use sql every day.
• I think indentation meaningful in sql style.
• but, this repository guide hasn't union indent style.
• so, I suggest 2 spaces indentation.
• Please, check my idea.
• P.S.
  • I respect another style. (everything has each by each style.)
  • but, if we can make good rule possibly (for readability, common unity)
  • indentation is powerful tool. (for readability, maintainability)
• thx for reading.

reference

• http://firstclassthoughts.co.uk/Articles/Readability/OptimalIndentSizeForCodeReadability.html
• https://stackoverflow.com/questions/272210/sql-statement-indentation-good-practice
• https://about.gitlab.com/handbook/business-technology/data-team/platform/sql-style-guide/

example

SELECT file_hash  -- stored ssdeep hash
FROM file_system
WHERE file_name = '.vimrc';

/* Updating the file record after writing to the file */
UPDATE file_system
SET
  file_modified_date = '1980-02-22 13:19:01.00000',
  file_size = 209732
WHERE file_name = '.vimrc';

SELECT first_name
FROM staff;

SELECT first_name AS fn
FROM staff AS s1
  JOIN students AS s2
    ON s2.mentor_id = s1.staff_num;

SELECT SUM(s.monitor_tally) monitor_total
FROM staff s;

SELECT model_num
FROM phones p
WHERE p.release_date > '2014-09-30';

SELECT
  f.species_name,
  AVG(f.height) AS average_height, 
  AVG(f.diameter) AS average_diameter
FROM flora f
WHERE f.species_name = 'Banksia'
  OR f.species_name = 'Sheoak'
  OR f.species_name = 'Wattle'
GROUP BY f.species_name, f.observation_date)
UNION ALL
SELECT 
  b.species_name,
  AVG(b.height) AS average_height, 
  AVG(b.diameter) AS average_diameter
FROM botanic_garden_flora AS b
WHERE b.species_name = 'Banksia'
  OR b.species_name = 'Sheoak'
  OR b.species_name = 'Wattle'
GROUP BY b.species_name, b.observation_date);

SELECT
  a.title,
  a.release_date,
  a.recording_date
FROM albums AS a
WHERE a.title = 'Charcoal Lane'
  OR a.title = 'The New Danger';

INSERT INTO albums (title, release_date, recording_date)
VALUES
('Charcoal Lane', '1990-01-01 01:01:01.00000', '1990-01-01 01:01:01.00000'),
('The New Danger', '2008-01-01 01:01:01.00000', '1990-01-01 01:01:01.00000');

UPDATE albums
SET release_date = '1990-01-01 01:01:01.00000'
WHERE title = 'The New Danger';

SELECT 
  a.title,
  a.release_date, 
  a.recording_date, 
  a.production_date -- grouped dates together
FROM albums AS a
WHERE a.title = 'Charcoal Lane'
  OR a.title = 'The New Danger';

SELECT r.last_name
FROM riders AS r
  INNER JOIN bikes AS b
    ON r.bike_vin_num = b.vin_num
      AND b.engine_tally > 2
  INNER JOIN crew AS c
    ON r.crew_chief_last_name = c.last_name
      AND c.chief = 'Y';

SELECT
  r.last_name,
  (
    SELECT MAX(YEAR(championship_date))
    FROM champions AS c
    WHERE 1=1
      AND c.last_name = r.last_name
      AND c.confirmed = 'Y'
  ) last_championship_year
FROM riders r
WHERE 1=1
  AND r.last_name IN
  (
    SELECT c.last_name
    FROM champions AS c
    WHERE YEAR(championship_date) > '2008'
      AND c.confirmed = 'Y'
  );

SELECT 
  CASE postcode
    WHEN 'BN1' THEN 'Brighton'
    WHEN 'EH1' THEN 'Edinburgh'
  END city
FROM office_locations
WHERE 1=1
  AND country = 'United Kingdom'
  AND opening_time BETWEEN 8 AND 9
  AND postcode IN ('EH1', 'BN1', 'NN1', 'KW1');

CREATE TABLE staff (
  PRIMARY KEY (staff_num),
  staff_num INT(5) NOT NULL,
  first_name VARCHAR(100) NOT NULL,
  pens_in_drawer INT(2) NOT NULL,
  CONSTRAINT pens_in_drawer_range
  CHECK(pens_in_drawer BETWEEN 1 AND 99)
);

cc

• @shaunBucketplace

Badges for sqlstyle.guide

In order to possibly gain popularity (be found easier) and raise the changes of adoption, I'd suggest to ask the projects you listed under https://github.com/treffynnon/sqlstyle.guide#projects-known-to-be-implementing-the-guide along with other users of this standard to mention sqlstyle.guide using this badge (or a variation of it):

using for example: [![sqlstyle.guide](https://img.shields.io/badge/style-sqlstyle.guide-brightgreen.svg)](https://www.sqlstyle.guide/)

I used the generated badge (the first in the list above) also in a recent training I gave for a group of webdevelopers, along with similar badges mentioning PEP, PSR and JS-STANDARD.

Last but not least I'd really like to see (sombody creating) a plug-in, add-on for Atom or Notepad++ or other IDE's to perform sqlstyle.guide-compliance testing. That'd likely help to adopt this standard as well.

Let's be honest, developers like badges

aliasing example conflicts with join indentation guideline

The guide says "Joins should be indented to the other side of the river" but the earlier example doesn't follow this:

SELECT first_name AS fn
  FROM staff AS s1
  JOIN students AS s2
    ON s2.mentor_id = s1.staff_num;

Table and Column naming conventions violated in many examples

Hi Simon,

I really like this write up. It summarizes a lot of very useful guidelines in a succinct, well-written manner. One source of confusion I had while reading the guidline was that many of the SQL examples you list violate the 'singular over plural rule' that is laid out in the table and column naming section. For example office_locations, riders, albums, engines, champions, et cetera. This may sound nitpicky, so my apologies in advance, but I think this document would improve a lot if practiced what it preached. Also, it might be nice to touch on schema naming conventions as well, but this is more of a feature request than an issue.

-Alex

Italian translation

Hi,

I would like to perform the italian translation.

Could you please tell me if it's OK, and what should I do, beside translating index.md obviously.

Thank you

Add suggested data types section

Currently designing a Sqlite schema for an university assignment, wanted a few pointers on writing SQL scripts when I found this nice website.

After reading the "Create table" section, concretly:

Where possible do not use vendor specific data types—these are not portable and may not be available in older versions of the same vendor’s software.

I wondered which data types are vendor specific and which are *not*, as I've worked in the past with MySQL, MS SQL, Sqlite and now also PostgreSQL, and understood about "int, char, varchar" but now I've learned about "Numeric", "Decimal", geospatial types and the like.

So, maybe someone with greater experise could redact a list, or better, a table of which datatypes are the most supported in general and which keyword do they use? It could be added as a new HTML page rather than in the main document.

Regard,
Alejandro

pt-BR translation

Hello, @treffynnon. I'm using your guide for a while and I'm loving it. Just started the pt-BR (Brazilian Portuguese) translation.

I'm new on github and I just want to clarify if I'm doing right.

1. forked your repo.
2. cloned to my machine.
3. created a new branch for the translation.

When I finish, I need to create a pull request and send for approvation, right?
Thanks in advance. :)

Add advice for boolean columns?

I looked through the style guide and couldn't see advice on columns that contain booleans. Do you have a preference for this, and would you be interested in adding it to the style guide?

add link for OOP design vs. SQL

A few places in the guide you mention the incompatibility of object-oriented design vs. database design:

• https://www.sqlstyle.guide/#avoid
• https://www.sqlstyle.guide/#designs-to-avoid

Can you throw in a link here to an article/blog describing in more detail how this can go wrong?

Also, maybe update the text to include 'impedance mismatch'?

Be happy to open PR if amenable.

Grammer error in German translation

diff --git a/_includes/sqlstyle.guide.de.md b/_includes/sqlstyle.guide.de.md
index 31082a2..813ab86 100644
--- a/_includes/sqlstyle.guide.de.md
+++ b/_includes/sqlstyle.guide.de.md
@@ -200,7 +200,7 @@ Leerzeichen sollten verwendet werden, um den Code so auszurichten, dass die
Hauptschlüsselwörter alle rechtsbündig ausgerichtet werden. Dies erstellt
Gießbäche in der Mitte, die es dem Leser leichter macht, den Code zu lesen und
die Schlüsselwörter von den Implementierungsdetails zu trennen.
-[Gießbäche][gießbäche] sind schlecht in der Typografie [schlecht][rivers],
+[Gießbäche][gießbäche] sind [schlecht][rivers] in der Typografie,
aber hier sind sie hilfreich.

Audit columns

The guide does not speak about columns like modified_at or created_at.

On top of that, these columns are normally suffixed with _at, which violates the guide using _date as a suffix for a point in time.

Avoid plurals but...

You are saying to avoid plural names, aren't you?

But... http://screencast.com/t/8KGCwRvu6BM

Regards, Nicholls

Ambiguous INNER JOIN syntax

INNER JOIN syntax is given with the example:

SELECT r.last_name
  FROM riders AS r
       INNER JOIN bikes AS b
       ON r.bike_vin_num = b.vin_num
          AND b.engines > 2

       INNER JOIN crew AS c
       ON r.crew_chief_last_name = c.last_name
          AND c.chief = 'Y';

Please provide a more formal definition. The current format leaves room for interpretation:

1. Why is AND indented?
2. How much is AND indented?
3. Why is INNER JOIN different than JOIN?

Warning while `jekyll serve`

Hi,

there's a weird build warning pursuing me any time I'm running the jekyll serve command.

Configuration file: /Users/denpatin/Repos/sqlstyle.guide/_config.yml
Configuration file: /Users/denpatin/Repos/sqlstyle.guide/_config.yml
            Source: /Users/denpatin/Repos/sqlstyle.guide
       Destination: /Users/denpatin/Repos/sqlstyle.guide/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
     Build Warning: Layout 'nil' requested in scripts.js does not exist.
     Build Warning: Layout 'nil' requested in style.css does not exist.
                    done in 1.119 seconds.

It doesn't affect the serving of the pages, however it still strings a bit up. Could you please check or explain, if you already know, what's going on here.

Thanks!

Order of foreign key?

Under the header "Layout and order" we have the rule:

Specify the primary key first right after the CREATE TABLE statement.

Is there any recommendation for the order of foreign keys? Such as if they go after the primary key but before the rest of the columns or if they go at the end of the table after all the other columns.

Versioning and changelog?

I'm fan of the Markdown variant that you point out in the text at the bottom of the Style Guide. But, when I add a copy to my git as a developer. How do I know when to update it?

I'd like to add some kind of version number to the versions to keep track of changes. Possibly adding a CHANGELOG as well, describing the (tiny) improvements or changes overtime. Also, the version number probably makes it a lot easier for translators to know which version is translated. To avoid different versions in different languages in the future.

Typo: it's -> its

"it's opening partner" is incorrect and should be "its opening partner".

Naming convention for boolean columns

How should boolean columns be named?

Should they have any prefix or suffix such as "has", "can", "is" or should that be avoided?

Example "admin" could be "is_admin".

Psychology of colors

In addition of #43 regarding popularity and adoption. and although I personally like red as much as any other color: Webdevelopers are also humans where consciously or unconsciously, psychology (of colors) also applies on, obviously.

As far as red is (at least in the context of information technology) mostly is associated with "error", "danger", "problem" et cetera. I'd suggest to use the more positive color green instead. 💚

Check the difference:

I used the green, as used by the popular Bootstrap #5cb85c.

What does mean colors in some Reserved Keywords?

What does blue and red mean for a reserved keyword?
IMO it should exist a legend.

Out Parameter location

While the style does cover the naming of stored procedures it does not cover the location of out parameters. Obvious places are at the start or the end of the parameter list. Subjectively at the end seems to be more common. However I can't give a good argument for this.

Possible indent typo on sqlstyle.guide website

Thank you for maintaining this! We're adopting this style guide for our software engineering team, and I noticed what looks to be a slight indentation error in the "Aliasing or correlations" at https://www.sqlstyle.guide/#aliasing-or-correlations. I think the JOIN and ON keywords should be on the right side of the river. I mention this because it's the first example of formatting a JOIN, so junior people may skim to that and incorrectly use it.

Could you please update (or show me how to update) https://www.sqlstyle.guide/#aliasing-or-correlations from:

SELECT first_name AS fn
  FROM staff AS s1
  JOIN students AS s2
    ON s2.mentor_id = s1.staff_num;

to:

SELECT first_name AS fn
  FROM staff AS s1
       INNER JOIN students AS s2
       ON s2.mentor_id = s1.staff_num;

(I also made the type of join explicit as a best practice)

Indenting parenthesized table references

The guide does not appear to have an opinion on indenting parenthesized table references.

SELECT pmt_courses.course_name, pmt_tokens.token, pmt_orders.order_id, wp_users.user_email
  FROM wp_pmt_order_token
  JOIN pmt_tokens
    ON pmt_tokens.id = wp_pmt_order_token.fk_token_id
  JOIN pmt_courses
    ON pmt_courses.course_id = pmt_tokens.course_id
       LEFT JOIN (
                 pmt_orders
            JOIN wp_users
              ON wp_users.ID = pmt_orders.user_id
       ) ON pmt_orders.order_token = pmt_tokens.token
 WHERE wp_pmt_order_token.fk_order_id = 28997

Could this matter please be adjudicated?

Note to self: https://dev.mysql.com/doc/refman/5.7/en/join.html

German translation

Hi,

I'd better extract the mentioning regarding the German translation from Issue #14 into a separate (this) one so that you could close #14 after checking and merging.

The German version is coming very soon, as Russian today did.

CHECK pens_in_drawer violates "preferred formalisms" re. BETWEEN

The "Preferred Formalisms" section advises

Make use of BETWEEN where possible instead of combining multiple statements with AND.

but the example in the "Defining Constraints" section has

CHECK(pens_in_drawer >= 1 AND pens_in_drawer < 100)

which should likely be

CHECK(pens_in_drawer BETWEEN 1 AND 99)

(though I'd also posit that it might make sense not to have any pens in the drawer and thus it should be BETWEEN 0 and 99)

[English translation] Complement misspelling

Please see https://en.wiktionary.org/wiki/compliment

Inconsistency in JOIN indentation

Problem
There is an inconsistency in the way JOIN statements are indented here:

Aliasing or Correlations
Indentation, Joins

At first I thought it might be because the second is an INNER JOIN, but isn't a JOIN considered INNER by default?

Suggested Fix
I suggest that the section "Indentation -> Joins" be considered as the source of truth and the other example (as shown under "Aliasing or Correlations") be modified to match it. I'd like to hear your opinions and then would be happy to send a PR with a fix.

Add formatter

Please add a javascript formatter to make existing queries compliant with the proposed standard.

Mine

Ukrainian translation suggestion

#88

Subqueries

Please address subqueries.

Here is a query that otherwise follows the prescribed format:

http://stackoverflow.com/a/37300770/300224

Code is not mono-spaced on Firefox?

On Firefox, the code blocks are not truly mono-spaced. See the image below.

• First code block: it is difficult to see, but the file_system on second line is not quite at the same horizontal alignment.
• Second code block: it is more obvious here: file_size on the fourth line is noticeably shifted to the left.

With the more complex examples later in the document, it becomes quite difficult to see the intended alignment.

I do not know what is causing this. Are the spaces narrower than the other characters? Perhaps this is a Firefox problem (I tested this with Firefox 52.7.3)?

This guide is fantastic

It goes deep into the everyday work of an SQL developer.

Thank you.

Russian translation

Hi @treffynnon,

thank you for your great work! I do admire this style guide.

I'd like to perform a translation of it into Russian so that these well-favored rules become more available and googleable among Russian SQL developers. Do I get it right that I need to translate only the file sqlstyle.guide.md inside the _includes folder, don't I?

Best,
Den