diff --git a/_includes/head.html b/_includes/head.html index 74181ce..e69de29 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -1,3 +0,0 @@ -
-

SQL Style Guide

-
diff --git a/_includes/sqlstyle.guide.md b/_includes/sqlstyle.guide.md new file mode 100644 index 0000000..829306f --- /dev/null +++ b/_includes/sqlstyle.guide.md @@ -0,0 +1,1005 @@ +# SQL style guide + +## Overview + +You can use this set of guidelines, [fork them](#) or make your own - the +key here is that you pick a style and stick to it. To suggest changes +or fix bugs please open an [issue](#) or [pull request](#) on Git Hub. + +## General + +### Avoid the use of + +* CamelCase—it is difficult to scan quickly +* Descriptive prefixes or Hungarian notation such as `sp_` or `tbl` +* Plurals—use the more natural collective term instead +* Quoted identifiers—if you must use them then stick to SQL92 double quotes for + portability + +```sql +SELECT first_name + FROM staff; +``` + +## Syntax + +### Reserved words + +Always use uppercase for the [reserved keywords](#keyword-reference) like +`SELECT` and `WHERE`. + +It is best to avoid the abbreviated keywords and use the full length ones where +available (prefer `ABSOLUTE` to `ABS`). + +Do not use database server specific keywords where an ANSI SQL keyword already +exists performing the same function. This helps to make code more portable. + +```sql +SELECT model_num + FROM phones AS p + WHERE p.release_date > '2014-09-30'; +``` + +### Indentation + +Use four (4) spaces all the way through all the time. This makes the most sense +where there is a sub query. + +```sql +-- TODO: need an example +``` + +### White space + +To make the code easier to read it is important that the correct compliment of +spaces is used. Do not crowd code or remove natural spaces. + +Always include spaces (this is not an exhaustive list): + +* before and after equals (`=`) +* after commas (`,`) +* surrounding apostrophes (`'`) where not within parentheses or with a trailing + comma or semicolon + +Always include newlines/vertical space: + +* after semicolons to separate queries for easier reading +* after each keyword definition +* after the comma of each column in the list +* before `AND` or `OR` + +Keeping all the keywords aligned to the righthand side and the values left aligned +creates a uniform gap down the middle of query. It makes it much easier to scan +the query definition over quickly too. + +```sql +-- No +SELECT a.release_date,a.title +FROM albums AS a +WHERE a.title='Charcoal Lane'OR + a.title='The New Danger'; + + +-- Yes +SELECT a.release_date, + a.title + FROM albums AS a + WHERE a.title = 'Charcoal Lane' + OR a.title = 'The New Danger'; +``` + +## Naming conventions + +### General + +* Ensure the name is unique and does not exist as a + [reserved keyword](#keyword-reference) +* Keep the length to a maximum of 30 bytes—in practice this is 30 characters + unless you are using multibyte charset +* Names must begin with a letter and may not end with an underscore +* Only use letters, numbers and underscores in names +* Avoid the use of multiple consecutive underscores—these can be hard to read +* Use underscores where you would naturally include a space in name (first name + becomes `first_name`) +* Avoid abbreviations and if you have to use them make sure they are commonly + understood + +```sql +SELECT first_name + FROM staff; +``` + +### Tables + +* Use a collective name or, less ideally, a plural form. For example (in order of + preference) staff and employees. +* Do not prefix with `tbl` or any other such descriptive prefix or Hungarian + notation +* Never give a table the same name as one of its columns +* Avoid, where possible, concatenating two table names together to create the name + of a relationship table. Rather than `car_mechanic` prefer `service` + +```sql +SELECT first_name + FROM staff; +``` + +### Columns + +* Always use the singular name +* Avoid simply using `id` as the primary identifier for the table +* Do not add a column with the same name as its table +* Always use lowercase except where it may make sense not to such as proper nouns + +### Aliasing or correlations + +* Should relate in some way to the object or expression they are aliasing +* As rule of thumb the correlation name should be the first letter of each word + in the object's name +* If there is already a correlation with same name then append a number +* Always include the `AS` keyword—makes it easier to read as it is explicit +* For computed data (`SUM()` or `AVG()`) use the name you would give it were it + a column defined in the schema + +```sql +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) AS monitor_total + FROM staff AS s; +``` + +### Stored procedures + +* The name must contain a verb +* Do not prefix with `sp_` or any other such descriptive prefix or Hungarian + notation + +### Uniform postfixes + +* `_id`—a unique identifier such as a column that is a primary key +* `_status`—flag value or some other status of any type such as + `publication_status` +* `_total`—the total or sum of a collection of values +* `_name`—signifies a name such as `first_name` +* `_seq`—contains a contiguous sequence of values +* `_date`—denotes a column that contains the date of something +* `_tally`—a count +* `_size`—the size of something such as a file size or clothing +* `_addr`—an address for the record could be physical or intangible such as `ip_addr` + +## Appendices + +### Reserved keyword reference + +A list of ANSI SQL 92, ANSI SQL 99, ANSI SQL 2003, MySQL 3.23.x, MySQL 4.x, MySQL 5.x, PostGreSQL 8.1, MS SQL Server 2000, MS ODBC, Oracle 10.2 reserved keywords. + +```sql +A +ABORT +ABS +ABSOLUTE +ACCESS +ACTION +ADA +ADD +ADMIN +AFTER +AGGREGATE +ALIAS +ALL +ALLOCATE +ALSO +ALTER +ALWAYS +ANALYSE +ANALYZE +AND +ANY +ARE +ARRAY +AS +ASC +ASENSITIVE +ASSERTION +ASSIGNMENT +ASYMMETRIC +AT +ATOMIC +ATTRIBUTE +ATTRIBUTES +AUDIT +AUTHORIZATION +AUTO_INCREMENT +AVG +AVG_ROW_LENGTH +BACKUP +BACKWARD +BEFORE +BEGIN +BERNOULLI +BETWEEN +BIGINT +BINARY +BIT +BIT_LENGTH +BITVAR +BLOB +BOOL +BOOLEAN +BOTH +BREADTH +BREAK +BROWSE +BULK +BY +C +CACHE +CALL +CALLED +CARDINALITY +CASCADE +CASCADED +CASE +CAST +CATALOG +CATALOG_NAME +CEIL +CEILING +CHAIN +CHANGE +CHAR +CHAR_LENGTH +CHARACTER +CHARACTER_LENGTH +CHARACTER_SET_CATALOG +CHARACTER_SET_NAME +CHARACTER_SET_SCHEMA +CHARACTERISTICS +CHARACTERS +CHECK +CHECKED +CHECKPOINT +CHECKSUM +CLASS +CLASS_ORIGIN +CLOB +CLOSE +CLUSTER +CLUSTERED +COALESCE +COBOL +COLLATE +COLLATION +COLLATION_CATALOG +COLLATION_NAME +COLLATION_SCHEMA +COLLECT +COLUMN +COLUMN_NAME +COLUMNS +COMMAND_FUNCTION +COMMAND_FUNCTION_CODE +COMMENT +COMMIT +COMMITTED +COMPLETION +COMPRESS +COMPUTE +CONDITION +CONDITION_NUMBER +CONNECT +CONNECTION +CONNECTION_NAME +CONSTRAINT +CONSTRAINT_CATALOG +CONSTRAINT_NAME +CONSTRAINT_SCHEMA +CONSTRAINTS +CONSTRUCTOR +CONTAINS +CONTAINSTABLE +CONTINUE +CONVERSION +CONVERT +COPY +CORR +CORRESPONDING +COUNT +COVAR_POP +COVAR_SAMP +CREATE +CREATEDB +CREATEROLE +CREATEUSER +CROSS +CSV +CUBE +CUME_DIST +CURRENT +CURRENT_DATE +CURRENT_DEFAULT_TRANSFORM_GROUP +CURRENT_PATH +CURRENT_ROLE +CURRENT_TIME +CURRENT_TIMESTAMP +CURRENT_TRANSFORM_GROUP_FOR_TYPE +CURRENT_USER +CURSOR +CURSOR_NAME +CYCLE +DATA +DATABASE +DATABASES +DATE +DATETIME +DATETIME_INTERVAL_CODE +DATETIME_INTERVAL_PRECISION +DAY +DAY_HOUR +DAY_MICROSECOND +DAY_MINUTE +DAY_SECOND +DAYOFMONTH +DAYOFWEEK +DAYOFYEAR +DBCC +DEALLOCATE +DEC +DECIMAL +DECLARE +DEFAULT +DEFAULTS +DEFERRABLE +DEFERRED +DEFINED +DEFINER +DEGREE +DELAY_KEY_WRITE +DELAYED +DELETE +DELIMITER +DELIMITERS +DENSE_RANK +DENY +DEPTH +DEREF +DERIVED +DESC +DESCRIBE +DESCRIPTOR +DESTROY +DESTRUCTOR +DETERMINISTIC +DIAGNOSTICS +DICTIONARY +DISABLE +DISCONNECT +DISK +DISPATCH +DISTINCT +DISTINCTROW +DISTRIBUTED +DIV +DO +DOMAIN +DOUBLE +DROP +DUAL +DUMMY +DUMP +DYNAMIC +DYNAMIC_FUNCTION +DYNAMIC_FUNCTION_CODE +EACH +ELEMENT +ELSE +ELSEIF +ENABLE +ENCLOSED +ENCODING +ENCRYPTED +END +END-EXEC +ENUM +EQUALS +ERRLVL +ESCAPE +ESCAPED +EVERY +EXCEPT +EXCEPTION +EXCLUDE +EXCLUDING +EXCLUSIVE +EXEC +EXECUTE +EXISTING +EXISTS +EXIT +EXP +EXPLAIN +EXTERNAL +EXTRACT +FALSE +FETCH +FIELDS +FILE +FILLFACTOR +FILTER +FINAL +FIRST +FLOAT +FLOAT4 +FLOAT8 +FLOOR +FLUSH +FOLLOWING +FOR +FORCE +FOREIGN +FORTRAN +FORWARD +FOUND +FREE +FREETEXT +FREETEXTTABLE +FREEZE +FROM +FULL +FULLTEXT +FUNCTION +FUSION +G +GENERAL +GENERATED +GET +GLOBAL +GO +GOTO +GRANT +GRANTED +GRANTS +GREATEST +GROUP +GROUPING +HANDLER +HAVING +HEADER +HEAP +HIERARCHY +HIGH_PRIORITY +HOLD +HOLDLOCK +HOST +HOSTS +HOUR +HOUR_MICROSECOND +HOUR_MINUTE +HOUR_SECOND +IDENTIFIED +IDENTITY +IDENTITY_INSERT +IDENTITYCOL +IF +IGNORE +ILIKE +IMMEDIATE +IMMUTABLE +IMPLEMENTATION +IMPLICIT +IN +INCLUDE +INCLUDING +INCREMENT +INDEX +INDICATOR +INFILE +INFIX +INHERIT +INHERITS +INITIAL +INITIALIZE +INITIALLY +INNER +INOUT +INPUT +INSENSITIVE +INSERT +INSERT_ID +INSTANCE +INSTANTIABLE +INSTEAD +INT +INT1 +INT2 +INT3 +INT4 +INT8 +INTEGER +INTERSECT +INTERSECTION +INTERVAL +INTO +INVOKER +IS +ISAM +ISNULL +ISOLATION +ITERATE +JOIN +K +KEY +KEY_MEMBER +KEY_TYPE +KEYS +KILL +LANCOMPILER +LANGUAGE +LARGE +LAST +LAST_INSERT_ID +LATERAL +LEADING +LEAST +LEAVE +LEFT +LENGTH +LESS +LEVEL +LIKE +LIMIT +LINENO +LINES +LISTEN +LN +LOAD +LOCAL +LOCALTIME +LOCALTIMESTAMP +LOCATION +LOCATOR +LOCK +LOGIN +LOGS +LONG +LONGBLOB +LONGTEXT +LOOP +LOW_PRIORITY +LOWER +M +MAP +MATCH +MATCHED +MAX +MAX_ROWS +MAXEXTENTS +MAXVALUE +MEDIUMBLOB +MEDIUMINT +MEDIUMTEXT +MEMBER +MERGE +MESSAGE_LENGTH +MESSAGE_OCTET_LENGTH +MESSAGE_TEXT +METHOD +MIDDLEINT +MIN +MIN_ROWS +MINUS +MINUTE +MINUTE_MICROSECOND +MINUTE_SECOND +MINVALUE +MLSLABEL +MOD +MODE +MODIFIES +MODIFY +MODULE +MONTH +MONTHNAME +MORE +MOVE +MULTISET +MUMPS +MYISAM +NAME +NAMES +NATIONAL +NATURAL +NCHAR +NCLOB +NESTING +NEW +NEXT +NO +NO_WRITE_TO_BINLOG +NOAUDIT +NOCHECK +NOCOMPRESS +NOCREATEDB +NOCREATEROLE +NOCREATEUSER +NOINHERIT +NOLOGIN +NONCLUSTERED +NONE +NORMALIZE +NORMALIZED +NOSUPERUSER +NOT +NOTHING +NOTIFY +NOTNULL +NOWAIT +NULL +NULLABLE +NULLIF +NULLS +NUMBER +NUMERIC +OBJECT +OCTET_LENGTH +OCTETS +OF +OFF +OFFLINE +OFFSET +OFFSETS +OIDS +OLD +ON +ONLINE +ONLY +OPEN +OPENDATASOURCE +OPENQUERY +OPENROWSET +OPENXML +OPERATION +OPERATOR +OPTIMIZE +OPTION +OPTIONALLY +OPTIONS +OR +ORDER +ORDERING +ORDINALITY +OTHERS +OUT +OUTER +OUTFILE +OUTPUT +OVER +OVERLAPS +OVERLAY +OVERRIDING +OWNER +PACK_KEYS +PAD +PARAMETER +PARAMETER_MODE +PARAMETER_NAME +PARAMETER_ORDINAL_POSITION +PARAMETER_SPECIFIC_CATALOG +PARAMETER_SPECIFIC_NAME +PARAMETER_SPECIFIC_SCHEMA +PARAMETERS +PARTIAL +PARTITION +PASCAL +PASSWORD +PATH +PCTFREE +PERCENT +PERCENT_RANK +PERCENTILE_CONT +PERCENTILE_DISC +PLACING +PLAN +PLI +POSITION +POSTFIX +POWER +PRECEDING +PRECISION +PREFIX +PREORDER +PREPARE +PREPARED +PRESERVE +PRIMARY +PRINT +PRIOR +PRIVILEGES +PROC +PROCEDURAL +PROCEDURE +PROCESS +PROCESSLIST +PUBLIC +PURGE +QUOTE +RAID0 +RAISERROR +RANGE +RANK +RAW +READ +READS +READTEXT +REAL +RECHECK +RECONFIGURE +RECURSIVE +REF +REFERENCES +REFERENCING +REGEXP +REGR_AVGX +REGR_AVGY +REGR_COUNT +REGR_INTERCEPT +REGR_R2 +REGR_SLOPE +REGR_SXX +REGR_SXY +REGR_SYY +REINDEX +RELATIVE +RELEASE +RELOAD +RENAME +REPEAT +REPEATABLE +REPLACE +REPLICATION +REQUIRE +RESET +RESIGNAL +RESOURCE +RESTART +RESTORE +RESTRICT +RESULT +RETURN +RETURNED_CARDINALITY +RETURNED_LENGTH +RETURNED_OCTET_LENGTH +RETURNED_SQLSTATE +RETURNS +REVOKE +RIGHT +RLIKE +ROLE +ROLLBACK +ROLLUP +ROUTINE +ROUTINE_CATALOG +ROUTINE_NAME +ROUTINE_SCHEMA +ROW +ROW_COUNT +ROW_NUMBER +ROWCOUNT +ROWGUIDCOL +ROWID +ROWNUM +ROWS +RULE +SAVE +SAVEPOINT +SCALE +SCHEMA +SCHEMA_NAME +SCHEMAS +SCOPE +SCOPE_CATALOG +SCOPE_NAME +SCOPE_SCHEMA +SCROLL +SEARCH +SECOND +SECOND_MICROSECOND +SECTION +SECURITY +SELECT +SELF +SENSITIVE +SEPARATOR +SEQUENCE +SERIALIZABLE +SERVER_NAME +SESSION +SESSION_USER +SET +SETOF +SETS +SETUSER +SHARE +SHOW +SHUTDOWN +SIGNAL +SIMILAR +SIMPLE +SIZE +SMALLINT +SOME +SONAME +SOURCE +SPACE +SPATIAL +SPECIFIC +SPECIFIC_NAME +SPECIFICTYPE +SQL +SQL_BIG_RESULT +SQL_BIG_SELECTS +SQL_BIG_TABLES +SQL_CALC_FOUND_ROWS +SQL_LOG_OFF +SQL_LOG_UPDATE +SQL_LOW_PRIORITY_UPDATES +SQL_SELECT_LIMIT +SQL_SMALL_RESULT +SQL_WARNINGS +SQLCA +SQLCODE +SQLERROR +SQLEXCEPTION +SQLSTATE +SQLWARNING +SQRT +SSL +STABLE +START +STARTING +STATE +STATEMENT +STATIC +STATISTICS +STATUS +STDDEV_POP +STDDEV_SAMP +STDIN +STDOUT +STORAGE +STRAIGHT_JOIN +STRICT +STRING +STRUCTURE +STYLE +SUBCLASS_ORIGIN +SUBLIST +SUBMULTISET +SUBSTRING +SUCCESSFUL +SUM +SUPERUSER +SYMMETRIC +SYNONYM +SYSDATE +SYSID +SYSTEM +SYSTEM_USER +TABLE +TABLE_NAME +TABLES +TABLESAMPLE +TABLESPACE +TEMP +TEMPLATE +TEMPORARY +TERMINATE +TERMINATED +TEXT +TEXTSIZE +THAN +THEN +TIES +TIME +TIMESTAMP +TIMEZONE_HOUR +TIMEZONE_MINUTE +TINYBLOB +TINYINT +TINYTEXT +TO +TOAST +TOP +TOP_LEVEL_COUNT +TRAILING +TRAN +TRANSACTION +TRANSACTION_ACTIVE +TRANSACTIONS_COMMITTED +TRANSACTIONS_ROLLED_BACK +TRANSFORM +TRANSFORMS +TRANSLATE +TRANSLATION +TREAT +TRIGGER +TRIGGER_CATALOG +TRIGGER_NAME +TRIGGER_SCHEMA +TRIM +TRUE +TRUNCATE +TRUSTED +TSEQUAL +TYPE +UESCAPE +UID +UNBOUNDED +UNCOMMITTED +UNDER +UNDO +UNENCRYPTED +UNION +UNIQUE +UNKNOWN +UNLISTEN +UNLOCK +UNNAMED +UNNEST +UNSIGNED +UNTIL +UPDATE +UPDATETEXT +UPPER +USAGE +USE +USER +USER_DEFINED_TYPE_CATALOG +USER_DEFINED_TYPE_CODE +USER_DEFINED_TYPE_NAME +USER_DEFINED_TYPE_SCHEMA +USING +UTC_DATE +UTC_TIME +UTC_TIMESTAMP +VACUUM +VALID +VALIDATE +VALIDATOR +VALUE +VALUES +VAR_POP +VAR_SAMP +VARBINARY +VARCHAR +VARCHAR2 +VARCHARACTER +VARIABLE +VARIABLES +VARYING +VERBOSE +VIEW +VOLATILE +WAITFOR +WHEN +WHENEVER +WHERE +WHILE +WIDTH_BUCKET +WINDOW +WITH +WITHIN +WITHOUT +WORK +WRITE +WRITETEXT +X509 +XOR +YEAR +YEAR_MONTH +ZEROFILL +ZONE +``` diff --git a/index.md b/index.md new file mode 100644 index 0000000..390a152 --- /dev/null +++ b/index.md @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{% include sqlstyle.guide.md %} \ No newline at end of file