From 1ab3ee4be67d8af1284565f833495cffb7546521 Mon Sep 17 00:00:00 2001 From: go-jet Date: Thu, 4 Jul 2019 19:10:31 +0200 Subject: [PATCH] Add SQL-Builder.md wiki page. --- wiki/Expressions.md | 12 ++--- wiki/Generator.md | 86 +------------------------------- wiki/Model-data.md | 4 +- wiki/SQL-Builder.md | 117 ++++++++++++++++++++++++++++++++++++++++++++ wiki/_Sidebar.md | 2 +- 5 files changed, 128 insertions(+), 93 deletions(-) create mode 100644 wiki/SQL-Builder.md diff --git a/wiki/Expressions.md b/wiki/Expressions.md index 811b01f..2fe97b8 100644 --- a/wiki/Expressions.md +++ b/wiki/Expressions.md @@ -66,7 +66,7 @@ jet.Int(11).LIKE(jet.Float(22.2)) // integer expressions doesn't have LIKE Jet supports following comparison operators for all expression types: -| Method | Sample | Generated sql | +| Method | Example | Generated sql | | ------------------------------ | ------------------------------------------------ |---------------------------- | | EQ | jet.Int(1).EQ(table.Film.Length) | 1 = film.length | | NOT_EQ | jet.Int(1).EQ(table.Film.Length) | 1 != film.length | @@ -86,7 +86,7 @@ Following arithmetic operators are supported for integer and float expressions. If the first argument is float expression, second argument can be integer or float expression. If the first argument is integer expression second argument can only be integer expression. -| Method | Sample | Generated sql | +| Method | Example | Generated sql | | ------------------------------ | ------------------------------------------------ |---------------------------- | | ADD | jet.Int(1).ADD(table.Film.Length) | 1 + film.length | | SUB | jet.Float(1.11).SUB(Int(1)) | 1.11 + 1 | @@ -100,7 +100,7 @@ If the first argument is integer expression second argument can only be integer Following operators are only available on integer expressions: -| Method | Sample | Generated sql | +| Method | Example | Generated sql | | ------------------------------ | ------------------------------------------------ |---------------------------- | | BIT_AND | jet.Int(11).BIT_AND(table.Film.Length) | 11 & film.length | | BIT_OR | jet.Int(11).BIT_OR(table.Film.Length) | 11 \| film.length | @@ -114,7 +114,7 @@ Following operators are only available on integer expressions: Following operators are only available on boolean expressions: -| Method | Sample | Generated sql | +| Method | Example | Generated sql | | ------------------------------ | ---------------------------------------------------------|---------------------------- | | IS_TRUE | table.Staff.Active.IS_TRUE() | staff.active IS TRUE | | IS_NOT_TRUE | (table.Staff.Active.AND(jet.Bool(true))).IS_NOT_TRUE() | (staff.active AND true) IS NOT TRUE | @@ -128,7 +128,7 @@ Following operators are only available on boolean expressions: Following operators are only available on string expressions: -| Method | Sample | Generated sql | +| Method | Example | Generated sql | | ------------------------------ | ---------------------------------------------------------|---------------------------- | | CONCAT | table.Film.Name.CONCAT(table.Film.Description) | film.name \|\| film.description | | LIKE | table.Film.Name.LIKE(String("%Wind%")) | film.name LIKE %Wind% | @@ -142,7 +142,7 @@ Following operators are only available on string expressions: Cast operators allow expressions to be casted to some other database type. SQL builder expression type changes accordingly to database type. -| Method | Sample | Generated sql | +| Method | Example | Generated sql | | ------------------------------ | -------------------------------------------|---------------------------- | | TO_BOOL | table.Film.Description.TO_BOOL() | film.description::boolean | | TO_SMALLINT | table.Film.Description.TO_SMALLINT() | film.description::smallint | diff --git a/wiki/Generator.md b/wiki/Generator.md index 45be3db..e5052e4 100644 --- a/wiki/Generator.md +++ b/wiki/Generator.md @@ -97,87 +97,5 @@ Generated files folder structure will look like this: ``` Table and enums from database schema are used as a template to generate two types of Go files: -* SQL builder files: Files used to write type safe SQL statements in Go (enum and table package) -* Model files: Files used to store result from database queries (model package) - -#### SQL builder files -Part of the sample sql builder file for table `film`. - -``` -package table - -import ( - "github.com/go-jet/jet" -) -var Film = newFilmTable() - -type FilmTable struct { - jet.Table - - //Columns - FilmID jet.ColumnInteger - Title jet.ColumnString - Description jet.ColumnString - ReleaseYear jet.ColumnInteger - LanguageID jet.ColumnInteger - RentalDuration jet.ColumnInteger - RentalRate jet.ColumnFloat - Length jet.ColumnInteger - ReplacementCost jet.ColumnFloat - Rating jet.ColumnString - LastUpdate jet.ColumnTimestamp - SpecialFeatures jet.ColumnString - Fulltext jet.ColumnString - - AllColumns jet.ColumnList -} - -// creates new FilmTable with assigned alias -func (a *FilmTable) AS(alias string) *FilmTable { - aliasTable := newFilmTable() - - aliasTable.Table.AS(alias) - - return aliasTable -} -``` -Table name and column names are camelized inside sql builder type. -`AllColumns` is used as shorthand notation for list of all columns `FilmID, Title, Description,...`. - -Mappings of database types to sql builder column types are following: - -| Database type(postgres) | Sql builder column type | -| ----------------------------------------------- | -------------------------------------------------- | -| boolean | ColumnBool | -| smallint, integer, bigint | ColumnInteger | -| real, numeric, decimal, double precision | ColumnFloat | -| date | ColumnDate | -| timestamp without time zone | ColumnTimestamp | -| timestamp with time zone | ColumnTimestampz | -| time without time zone | ColumnTime | -| time with time zone | ColumnTimez | -| enums, text, character, character varying | | -| bytea, uuid | | -| and all remaining types | ColumnString | - -Sql builder file for enum type `mpaa_rating`: -``` -package enum - -import "github.com/go-jet/jet" - -var MpaaRating = &struct { - G jet.StringExpression - PG jet.StringExpression - PG13 jet.StringExpression - R jet.StringExpression - NC17 jet.StringExpression -}{ - G: jet.NewEnumValue("G"), - PG: jet.NewEnumValue("PG"), - PG13: jet.NewEnumValue("PG-13"), - R: jet.NewEnumValue("R"), - NC17: jet.NewEnumValue("NC-17"), -} - -``` +* SQL Builder files - used to write type safe SQL statements in Go (`enum` and `table` package) +* Model files - used to store result from database queries (`model` package) diff --git a/wiki/Model-data.md b/wiki/Model-data.md index c0678cf..c20a650 100644 --- a/wiki/Model-data.md +++ b/wiki/Model-data.md @@ -1,7 +1,7 @@ -## Model files +## Model Model files are simple data files used to store result of SQL queries. They are -autogenerated from to database tables and enums. +autogenerated from database tables and enums. ### Table model files diff --git a/wiki/SQL-Builder.md b/wiki/SQL-Builder.md new file mode 100644 index 0000000..b3d40db --- /dev/null +++ b/wiki/SQL-Builder.md @@ -0,0 +1,117 @@ + +## SQL Builder + +SQL Builder files are Go files, containing types necessary to write type safe SQL queries in Go. They are +autogenerated from database tables and enums. + +### Table SQL Builder files + +Following rules are applied to generate table SQL Builder files: + +- for every table there is one Go SQL Builder file generated. File name is in snake case of the table name. +- every file contains one type - struct with nested jet.Table. Type name is a camel case of table name. +- for every column of table there is a field column in SQL Builder table type. Field name is camel case of column name. +See below table for type mapping. +- `AllColumns` is used as shorthand notation for list of all columns. +- `MutableColumns` are all columns minus primary key columns _(Useful in INSERT or UPDATE statements)_. + +##### Mappings of database types to sql builder column types: + +| Database type(postgres) | Sql builder column type | +| ----------------------------------------------- | -------------------------------------------------- | +| boolean | ColumnBool | +| smallint, integer, bigint | ColumnInteger | +| real, numeric, decimal, double precision | ColumnFloat | +| date | ColumnDate | +| timestamp without time zone | ColumnTimestamp | +| timestamp with time zone | ColumnTimestampz | +| time without time zone | ColumnTime | +| time with time zone | ColumnTimez | +| enums, text, character, character varying | | +| bytea, uuid | | +| and all remaining types | ColumnString | + +### Example + +Sql table `address`: +``` +CREATE TABLE dvds.address +( + address_id serial NOT NULL DEFAULT, + address character varying(50) NOT NULL, + address2 character varying(50), + district character varying(20) NOT NULL, + city_id smallint NOT NULL, + postal_code character varying(10), + phone character varying(20) NOT NULL, + last_update timestamp without time zone NOT NULL DEFAULT now(), + CONSTRAINT address_pkey PRIMARY KEY (address_id) +) +``` + +Part of the table sql builder file for table `address`. + +``` +package table + +import ( + "github.com/go-jet/jet" +) + +var Address = newAddressTable() + +type AddressTable struct { + jet.Table + + //Columns + AddressID jet.ColumnInteger + Address jet.ColumnString + Address2 jet.ColumnString + District jet.ColumnString + CityID jet.ColumnInteger + PostalCode jet.ColumnString + Phone jet.ColumnString + LastUpdate jet.ColumnTimestamp + + AllColumns jet.ColumnList + MutableColumns jet.ColumnList +} +``` + +### Enum SQL Builder files + +Following rules are applied to generate enum SQL Builder files: + +- for every enum there is one Go SQL Builder file generated. File name is in snake case of the enum name. +- every file contains one type. Type name is a camel case of enum name. +- for every enum value there is a field in SQL Builder enum struct. Field name is camel case of enum value. Type is +jet.StringExpression, meaning it can be used by string expressions methods. + +#### Example + +Enum `mpaa_rating`: +``` +CREATE TYPE dvds.mpaa_rating AS ENUM + ('G', 'PG', 'PG-13', 'R', 'NC-17'); +``` + +Enum SQL Builder file for `mpaa_rating`: +``` +package enum + +import "github.com/go-jet/jet" + +var MpaaRating = &struct { + G jet.StringExpression + PG jet.StringExpression + PG13 jet.StringExpression + R jet.StringExpression + NC17 jet.StringExpression +}{ + G: jet.NewEnumValue("G"), + PG: jet.NewEnumValue("PG"), + PG13: jet.NewEnumValue("PG-13"), + R: jet.NewEnumValue("R"), + NC17: jet.NewEnumValue("NC-17"), +} +``` diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index b3e0fc5..169e2d7 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -2,7 +2,7 @@ * [Installation](https://github.com/go-jet/jet/wiki/Installation) * [Generator](https://github.com/go-jet/jet/wiki/Generator) * [Model files](https://github.com/go-jet/jet/wiki/Model-data.md) -* [Writing SQL in Go]() +* [SQL Builder](https://github.com/go-jet/jet/wiki/SQL-Builder.md) * [Expressions](https://github.com/go-jet/jet/wiki/Expressions) * [Statements](https://github.com/go-jet/jet/wiki/Statements) * [SELECT](https://github.com/go-jet/jet/wiki/SELECT)