From 117a1243f7d48667511ef9aadd4f3e7ee383ff3c Mon Sep 17 00:00:00 2001 From: tbollinger Date: Fri, 16 Mar 2018 16:02:50 -0400 Subject: [PATCH] Updating style guide to remove keywords and fix some spelling/grammatical issues --- README.md | 968 +----------------------------------------------------- 1 file changed, 6 insertions(+), 962 deletions(-) diff --git a/README.md b/README.md index 029890e..6690090 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,10 @@ WHERE ### Aliasing or correlations #### Aliasing Column Names -* Avoid unnessisary aliases at all times +* Avoid unnecessary aliases at all times * Must always alias `COUNT(*)` columns -* Must always alias computed data (`SUM()` or `AVG()` or `IF()`) use the name you would give it were it a column defined in the schema. -* Must always include the `AS` keyword, which makes it easier to read as it is explicit. +* Must always alias computed data (`SUM()` or `AVG()` or `IF()`). Use the name you would give it were it a column defined in the schema. +* Must always include the `AS` keyword, which makes it easier to read since it is explicit. * Should relate in some way to the object or expression they are aliasing. #### Aliasing Table Names @@ -63,7 +63,7 @@ WHERE * Table aliases will be made up of the first letter of every word in the table name unless * unless the alias is a reseverd word ie. `FROM INTERNATIONAL_FILINGS AS IF` will cause an error in SQL * in this case us an abbreviated name for the table ie. `FROM INTERNATIONAL_FILINGS AS IFILINGS` - * if the aliases for two table will be the same, or the same table is used more then once, append a number in order of apperance in the query + * if the aliases for two tables will be the same, or the same table is used more than once, append a number in order of apperance in the query * When a query contains multiple databases the first letter of the database, in lower case will be prepended to the table alias ie. `FROM international.ENTITY_MAP AS iEM INNER JOIN secdocs.COMPANY AS sC` ```sql @@ -96,8 +96,6 @@ and understood easily from SQL code. Use the correct suffix where appropriate. * `_name`—signifies a name such as `first_name`. * `_date`—denotes a column that contains the date of something. * `_count`—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`. ## Query syntax @@ -236,7 +234,7 @@ are followed. * A Join type must be indicated `LEFT OUTER`, `RIGHT OUTER`, `INNER` * Joins should be indented one indent under their tables or sub-queries * ON clauses should be indented to be left justified with the JOINs -* Multiple ON clauses should be indented to be indented benieth the ON and JOIN keywords +* Multiple ON clauses should be indented to be vertically aligned with the ON and JOIN keywords ```sql SELECT @@ -295,9 +293,7 @@ WHERE * Similarly use `IN()` instead of multiple `OR` clauses. * Where a value needs to be interpreted before leaving the database use the `CASE` expression. `CASE` statements can be nested to form more complex logical structures. -* Avoid the use of `UNION` clauses and temporary tables where possible. If the - schema can be optimised to remove the reliance on these features then it most - likely should be. +* Avoid the use of `UNION` clauses and temporary tables where possible. If the schema can be optimised to remove the reliance on these features then it most likely should be. ```sql SELECT @@ -315,958 +311,6 @@ WHERE postcode IN ('EH1', 'BN1', 'NN1', 'KW1') ``` -## Create syntax - -
-
-I do not think that this is a nessisary part of a style guide since we generally should not be creating tables in production -
-
-When declaring schema information it is also important to maintain human -readable code. To facilitate this ensure the column definitions are ordered and -grouped where it makes sense to do so. - -Indent column definitions by four (4) spaces within the `CREATE` definition. - -### Choosing data types - -* 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. -* Only use `REAL` or `FLOAT` types where it is strictly necessary for floating - point mathematics otherwise prefer `NUMERIC` and `DECIMAL` at all times. Floating - point rounding errors are a nuisance! - -### Specifying default values - -* The default value must be the same type as the column—if a column is declared - a `DECIMAL` do not provide an `INTEGER` default value. -* Default values must follow the data type declaration and come before any - `NOT NULL` statement. - -### Constraints and keys - -Constraints and their subset, keys, are a very important component of any -database definition. They can quickly become very difficult to read and reason -about though so it is important that a standard set of guidelines are followed. - -#### Choosing keys - -Deciding the column(s) that will form the keys in the definition should be a -carefully considered activity as it will effect performance and data integrity. - -1. The key should be unique to some degree. -2. Consistency in terms of data type for the value across the schema and a lower - likelihood of this changing in the future. -3. Can the value be validated against a standard format (such as one published by - ISO)? Encouraging conformity to point 2. -4. Keeping the key as simple as possible whilst not being scared to use compound - keys where necessary. - -It is a reasoned and considered balancing act to be performed at the definition -of a database. Should requirements evolve in the future it is possible to make -changes to the definitions to keep them up to date. - -#### Defining constraints - -Once the keys are decided it is possible to define them in the system using -constraints along with field value validation. - -##### General - -* Tables must have at least one key to be complete and useful. -* Constraints should be given a custom name excepting `UNIQUE`, `PRIMARY KEY` - and `FOREIGN KEY` where the database vendor will generally supply sufficiently - intelligible names automatically. - -##### Layout and order - -* Specify the primary key first right after the `CREATE TABLE` statement. -* Constraints should be defined directly beneath the column they correspond to. - Indent the constraint so that it aligns to the right of the column name. -* If it is a multi-column constraint then consider putting it as close to both - column definitions as possible and where this is difficult as a last resort - include them at the end of the `CREATE TABLE` definition. -* If it is a table level constraint that applies to the entire table then it - should also appear at the end. -* Use alphabetical order where `ON DELETE` comes before `ON UPDATE`. -* If it make senses to do so align each aspect of the query on the same character - position. For example all `NOT NULL` definitions could start at the same - character position. This is not hard and fast, but it certainly makes the code - much easier to scan and read. - -##### Validation - -* Use `LIKE` and `SIMILAR TO` constraints to ensure the integrity of strings - where the format is known. -* Where the ultimate range of a numerical value is known it must be written as a - range `CHECK()` to prevent incorrect values entering the database or the silent - truncation of data too large to fit the column definition. In the least it - should check that the value is greater than zero in most cases. -* `CHECK()` constraints should be kept in separate clauses to ease debugging. - -##### Example - -```sql -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 >= 1 AND pens_in_drawer < 100) -); -``` - -### Designs to avoid - -* Object oriented design principles do not effectively translate to relational - database designs—avoid this pitfall. -* Placing the value in one column and the units in another column. The column - should make the units self evident to prevent the requirement to combine - columns again later in the application. Use `CHECK()` to ensure valid data is - inserted into the column. -* [EAV (Entity Attribute Value)][eav] tables—use a specialist product intended for - handling such schema-less data instead. -* Splitting up data that should be in one table across many because of arbitrary - concerns such as time-based archiving or location in a multi-national - organisation. Later queries must then work across multiple tables with `UNION` - rather than just simply querying one table. - - -## Appendix - -### Reserved keyword reference - -A list of ANSI SQL (92, 99 and 2003), MySQL 3 to 5.x, PostgreSQL 8.1, MS SQL Server 2000, MS ODBC and 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 -``` - [simon]: https://www.simonholywell.com/?utm_source=sqlstyle.guide&utm_medium=link&utm_campaign=md-document "SimonHolywell.com" [issue]: https://github.com/treffynnon/sqlstyle.guide/issues