Gleipnir/jet
4
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

Update wiki pages.

Browse source
This commit is contained in:
go-jet 2019-07-15 13:06:06 +02:00
parent 518ff49a77
commit c78ca8a876
17 changed files with 105 additions and 81 deletions
Download patch file Download diff file Expand all files Collapse all files

13
wiki/Expressions.md
View file

@ -7,14 +7,14 @@ Jet sql builder supports following expression types:
- String expressions
- Date expressions
- Time expressions
- Timez expressions (with time zone)
- Timez expressions (Time with time zone)
- Timestamp expressions
- Timestampz expressions (with time zone)
- Timestampz expressions (Timestamp with time zone)
_This list might be extended with feature Jet releases._
### Literal Types
For every expression type there is a method to create one expression literal type .
For every expression type there is a method to create one expression literal type.
Literal type examples:
```
@ -27,9 +27,12 @@ jet.Time(23, 6, 6, 1)
jet.Timez(23, 6, 6, 222, +200)
jet.Timestamp(2010, 10, 21, 15, 30, 12, 333)
jet.Timestampz(2010, 10, 21, 15, 30, 12, 444, 0)
```
There is also:
```
jet.NULL
jet.STAR (alias for *)
jet.STAR (alias for *)
```
### Column Types
@ -105,7 +108,7 @@ Following operators are only available on integer expressions:
| 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 |
| BIT_XOR | jet.Int(11).BIT_XOR(table.Film.Length) | 11 # film.length |
| BIT_NOT | jet.Int(11).BIT_NOT(table.Film.Length) | ~ 11 |
| BIT_NOT | BIT_NOT(table.Film.Length) | ~ film.length |
| BIT_SHIFT_LEFT | jet.Int(11).BIT_SHIFT_LEFT(table.Film.Length) | 11 >> film.length |
| BIT_SHIFT_RIGHT | jet.Int(11).BIT_SHIFT_RIGHT(table.Film.Length) | 11 >> film.length |

26
wiki/Generator.md
View file

@ -14,7 +14,7 @@ go install github.com/go-jet/jet/cmd/jet
Make sure GOPATH bin folder is added to the PATH environment variable.
Test jet can be found in the PATH.
Test jet generator can be found in the PATH.
```sh
jet -h
Usage of jet:
@ -38,15 +38,19 @@ Usage of jet:
Additional connection string parameters(optional)
```
Now to generate sample database:
To generate jet SQL Builder and Data Model files from postgres database we need to call `jet` generator with postgres
connection parameters and root destination folder path for generated files.
Assuming we are running local postgres database, with user `jet`, database `jetdb` and schema `dvds` we will use this command:
```sh
jet -host=localhost -port=5432 -user=jet -password=jet -dbname=jetdb -schema dvds -path ./gen
jet -host=localhost -port=5432 -user=jet -password=jet -dbname=jetdb -schema=dvds -path=./gen
```
```sh
Connecting to postgres database: host=localhost port=5432 user=jet password=jet dbname=jetdb sslmode=disable
Retrieving schema information...
FOUND 15 table(s), 1 enum(s)
Cleaning up destination directory...
FOUND 15 table(s), 1 enum(s)
Destination directory: ./gen/jetdb/dvds
Cleaning up schema destination directory...
Generating table sql builder files...
Generating table model files...
Generating enum sql builder files...
@ -55,6 +59,8 @@ Done
```
#### 2) Generating from code
The same files can be generated manually from code.
```
import "github.com/go-jet/jet/generator/postgres"
@ -71,10 +77,10 @@ err = postgres.Generate("./gen", postgres.DBConnection{
})
```
In both ways, generator will:
- connect to postgres database and retrieve information about the tables and enums of `dvds` schema
- delete everything in destination folder `./gen`,
- generate sql builder and model Go files for each schema tables and enums into destination folder `./gen`.
In both ways, generator will:
- connect to postgres database and retrieve information about the _tables_ and _enums_ of `dvds` schema
- delete everything in schema destination folder - `./gen/jetdb/dvds`,
- and finally generate sql builder and model files for each schema tables and enums.
Generated files folder structure will look like this:
```
@ -98,4 +104,4 @@ 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 - used to write type safe SQL statements in Go (`enum` and `table` package)
* Model files - used to store result from database queries (`model` package)
* Model files - used to combine and store result from database queries (`model` package)

3
wiki/INSERT.md
View file

@ -1,6 +1,6 @@
The PostgreSQL INSERT statement is used to insert a single record or multiple records
INSERT statement is used to insert a single record or multiple records
into a table. More about PostgreSQL INSERT statement can be found here: https://www.postgresql.org/docs/11/sql-insert.html
Following clauses are supported:
@ -121,7 +121,6 @@ insertStmt := Link.INSERT(Link.ID, Link.URL, Link.Name, Link.Description).
dest := []model.Link{}
err := insertStmt.Query(db, &dest)
```
Use `ExecContext` and `QueryContext` to provide context object to execution.

17
wiki/Model-data.md
View file

@ -1,21 +1,21 @@
## Model
Model files are simple data files used to store result of SQL queries. They are
Model files are simple Go struct types used to combine and store result of SQL queries. They are
autogenerated from database tables and enums.
### Table model files
Following rules are applied to generate model files from database tables:
Following rules are applied to generate model types from database tables:
- for every table there is one Go file generated. File name is in snake case of the table name.
- every model file contains one struct type.
Type name is a camel case of table name.
- for every column of table there is a field in model struct. Field name is camel case of column name.
- every model file contains one struct type. Type name is a camel case of table name. Package name
is always `model`.
- for every column of table there is a field in model struct type. Field name is camel case of column name.
See below table for type mapping.
- fields are pointer types, if they relate to column that can be NULL.
- fields corresponds to primary key columns are tagged with `sql:"primary_key"`.
_This tag is used during query execution to group row results into desired arbitrary structure.
See more at [Execution](https://github.com/go-jet/jet/wiki/Execution):_
See more at [Execution](https://github.com/go-jet/jet/wiki/Execution)_
##### Mappings of database types to Go types
@ -79,12 +79,13 @@ type Address struct {
Following rules are applied to generate model files from database enums:
- for every enum there is one Go file generated. File name is a snake case of enum name.
- every file contains one renamed string type. Type name is a camel case of enum name.
- every file contains one renamed string type. Type name is a camel case of enum name.
Package name is always `model`.
Enum type has two helper methods to:
- initialize correctly from database query result
- easily convert enum to string.
- for every enum value there is one constant defined.
Name of the constant is in format [camel case of enum_name]_[camel case of enum_value_name].
Name of the constant is in format `{CamelCase(enum_name)}_{CamelCase(enum_value_name)}`.
#### Example

8
wiki/SELECT.md
View file

@ -1,7 +1,7 @@
SELECT statement is used to retrieve records from one or more tables in PostgreSQL.
More about SELECT statement in postgres can be found at: https://www.postgresql.org/docs/11/sql-select.html
Following clauses are supported:
- SELECT(expressions...) - expressions to form output rows of the SELECT statement.
- DISTINCT() - remove all duplicate rows from result set
@ -26,7 +26,7 @@ Following clauses are supported:
- UNION(select) / UNION_ALL(select) - computes the set union of the rows returned by the involved SELECT statements
- INTERSECT(select) / INTERSECT_ALL(select) - computes the set intersection of the rows returned by the involved SELECT statements
- EXCEPT(select) / EXCEPT_ALL(select) - computes the set of rows that are in the result of the left SELECT statement but not in the result of the right one
_This list might be extended with feature Jet releases._
### Examples per clause
@ -57,7 +57,7 @@ Above SQL clause written in go will produce following raw SQL:
```
SELECT 1 + 12 - 21,
film.name AS "film.name", --
film.name AS "film.name",
customer.first_name || customer.last_name AS "FullName"
```
`film.name AS "film.name"` - column names are aliased by default. Alias is used during execution to map row result to
@ -211,7 +211,7 @@ of interest, and than about the columns.
## Sub-queries
How to write SELECT statement with sub-queries?
__How to write SELECT statement with sub-queries?__
Sub-queries are composed first:
```

2
wiki/SQL-Builder.md
View file

@ -2,7 +2,7 @@
## 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. File names are snake case of the table name or enum name.
autogenerated from database tables and enums. File names is always snake case of the table or enum name.
### Table SQL Builder files

2
wiki/Scan-to-arbitrary-destination.md
View file

@ -76,7 +76,7 @@ For instance `city.city_id` -> `City.CityID`. This is being used to find appropr
It is not an error if there is not a column for each destination model field. Table and column names does not have
to be in snake case.
`Query` uses reflection to introspect destination type structure, and result set column names(aliases), to be able to map result set data to destination object.
`Query` uses reflection to introspect destination type structure, and result set column names(aliases), to find appropriate destination field for result set column.
Every new destination struct object is cached by his and all the parents primary key. So grouping to work correctly at least table primary keys has to appear in query result set. If there is no primary key in a result set
row number is used as grouping condition(which is always unique).
For instance, after row 1 is processed, two objects are stored to cache:

28
wiki/Statements.md
View file

@ -9,16 +9,16 @@ Following statements are supported:
_This list might be extended with feature Jet releases._
Statements SQL can be debugged in two ways:
### Executing statements
- `Sql() (query string, args []interface{}, err error)` - retrieves parametrized sql query with list of arguments
- `DebugSql() (query string, err error)` - retrieves debug query where every parametrized placeholder is replaced with its argument.
Statements can be executed by following methods:
- `Query(db execution.DB, destination interface{}) error` - executes statements over database connection db and stores row result in destination.
- `QueryContext(db execution.DB, context context.Context, destination interface{}) error` - executes statement with a context over database connection db and stores row result in destination.
- `Exec(db execution.DB) (sql.Result, error)` - executes statement over db connection without returning any rows.
- `ExecContext(db execution.DB, context context.Context) (sql.Result, error)` - executes statement with context over db connection without returning any rows.
Statements can be executed with following methods:
- `Query(db execution.DB, destination interface{}) error` - executes statements over database connection db and maps
row result result set to destination.
- `QueryContext(db execution.DB, context context.Context, destination interface{}) error` - executes statement with a
context over database connection db and maps row result result set to destination.
- `Exec(db execution.DB) (sql.Result, error)` - executes statement over db connection and returns `sql.Result`.
- `ExecContext(db execution.DB, context context.Context) (sql.Result, error)` - executes statement with context over
db connection and returns `sql.Result`.
Each execution method first creates parametrized sql query with list of arguments and then initiates query on database connection.
Exec and ExecContext are just a wrappers around database `Exec` and `ExecContext`.
@ -40,4 +40,12 @@ type DB interface {
These include but are not limited to:
- `sql.DB`
- `sql.Tx`
- `sql.Conn`
- `sql.Conn`
### Debugging statements
Statements SQL can be debugged in two ways:
- `Sql() (query string, args []interface{}, err error)` - retrieves parametrized sql query with list of arguments
- `DebugSql() (query string, err error)` - retrieves debug query where every parametrized placeholder is replaced with its argument.

5
wiki/UPDATE.md
View file

@ -28,7 +28,7 @@ SET (name, url) = ('Yahoo', 'http://yahoo.com')
WHERE link.name = 'Bing';
```
Short-hand notation to extract model data for column values:
Short-hand notation to update values from model data:
```
yahoo := model.Link{
@ -70,8 +70,7 @@ updateStmt := Link.
dest := []model.Link{}
err := updateStmt.Query(db, &dest)
err := updateStmt.Query(db, &dest)
```
Use `ExecContext` and `QueryContext` to provide context object to execution.