yosql-website/content/sql/frontmatter.md

   1 ---
   2 title: Front Matter
   3 date: 2019-06-16T18:53:54+02:00
   4 menu:
   5   main:
   6     parent: SQL
   7 categories:
   8   - SQL
   9 tags:
  10   - front matter
  11   - YAML
  12 ---
  13
  14 Each SQL statement can have an optional front matter section written in YAML that is placed inside an SQL comment.
  15
  16 ```sql
  17 -- name: someName
  18 -- description: Retrieves a single user
  19 -- repository: com.example.persistence.YourRepository
  20 -- vendor: H2
  21 -- parameters:
  22 --   - name: userId
  23 --     type: int
  24 -- type: READING
  25 -- returningMode: ONE
  26 -- generateStandardApi: true
  27 -- generateBatchApi: false
  28 -- generateStreamEagerApi: false
  29 -- generateStreamLazyApi: false
  30 -- generateRxJavaApi: false
  31 -- catchAndRethrow: true
  32 SELECT  *
  33 FROM    users
  34 WHERE   id = :userId
  35 ```
  36
  37 While parsing your `.sql` files, `YoSQL` will strip the SQL comment prefix (`--`) and read the remaining text as a YAML object. Its available fields are explained below.
  38
  39 ## name
  40
  41 The `name` field can be used to change the name of an SQL statement. Typically, the name is auto-detected from the `.sql` file name, however if you want to place multiple SQL statements in one file, use `name` to give each statement a unique name instead of relying on the auto-numbering `YoSQL` is using by default.
  42
  43 ```sql
  44 -- name: someName
  45 SELECT  *
  46 FROM    users
  47 WHERE   id = :userId
  48 ```
  49
  50 ## description
  51
  52 The `description` field can be used to add a description to your SQL statements that will be part of generated Javadocs.
  53
  54 ```sql
  55 -- description: Retrieves a single user
  56 SELECT  *
  57 FROM    users
  58 WHERE   id = :userId
  59 ```
  60
  61 ## repository
  62
  63 The `repository` field can be used to change which repository will contain the SQL statement. By default, `YoSQL` will auto-detect the repository based on the location of the `.sql` file. In case you want to structure your `.sql` files in a specific way, but move some SQL statements to specific repositories, use `repository` together with the fully-qualified name of the target repository.
  64
  65 ```sql
  66 -- repository: com.example.persistence.YourRepository
  67 SELECT  *
  68 FROM    users
  69 WHERE   id = :userId
  70 ```
  71
  72 The `repository` field takes the [basePackageName](../../configuration/repositories/basepackagename/) into account, e.g. you could shorten the above example to just `YourRepository` if your base package is `com.example.persistence`. If your repository starts with the base package already, it won't be added twice. Likewise, it is possible to add any number of subpackages in front of your repository, e.g. `your.own.domain.YourRepository`.
  73
  74 ## vendor
  75
  76 The `vendor` field can be used to assign a SQL statement to a specific database vendor. Use `vendor` in case you are writing SQL statements that are different for each database. We recommend, to provide a vendor-less statement as a fallback, in order to support as many databases as possible.
  77
  78 ```sql
  79 -- vendor: H2
  80 SELECT  *
  81 FROM    users
  82 WHERE   id = :userId
  83 ;
  84
  85 -- vendor: Microsoft SQL Server
  86 SELECT  *
  87 FROM    users
  88 WHERE   id = :userId
  89 ;
  90
  91 SELECT  *
  92 FROM    users
  93 WHERE   id = :userId
  94 ;
  95 ```
  96
  97 With the above configuration in place, the first statement will be executed when running against a H2 database, the second one when using Microsoft SQL Server and the last one for every other database.
  98
  99 ## parameters
 100
 101 The `parameters` field can be used to change the type of input parameters. We recommend to use `parameters` on all statements that expect user inputs to improve the type-safety of your code.
 102
 103 ```sql
 104 -- parameters:
 105 --   - name: userId
 106 --     type: int
 107 SELECT  *
 108 FROM    users
 109 WHERE   id = :userId
 110 ```
 111
 112 The above configuration will generate code that use the primitive `int` type instead of `java.lang.Object` for the parameter `userId` in generated code.
 113
 114 ## type
 115
 116 The `type` field can be used to change the type of your SQL statement. By default, `YoSQL` will [auto-detect the type based on the name](../sql-files/) of your SQL statement. Possibles types are `READING`, `WRITING`, `CALLING`.
 117
 118 ```sql
 119 -- type: READING
 120 SELECT  *
 121 FROM    users
 122 WHERE   id = :userId
 123 ```
 124
 125 ## returningMode
 126
 127 The `returningMode` field can be used to change what the generated methods are returning. By default, `LIST` is used which can contain zero-to-many entities. Use `FIRST` in order to get just the first result (zero-to-one) or `ONE` to get the one result, while failing if there are more than one.
 128
 129 ```sql
 130 -- returningMode: ONE
 131 SELECT  *
 132 FROM    users
 133 WHERE   id = :userId
 134 ```
 135
 136 ## generateStandardApi
 137
 138 The `generateStandardApi` field can be used to overwrite the globally configured `generateStandardApi` option. Use `generateStandardApi` in case you want to enable/disable generating *standard* methods.
 139
 140 ```sql
 141 -- generateStandardApi: true
 142 SELECT  *
 143 FROM    users
 144 WHERE   id = :userId
 145 ```
 146
 147 ## generateBatchApi
 148
 149 The `generateBatchApi` field can be used to overwrite the globally configured `generateBatchApi` option. Use `generateBatchApi` in case you want to enable/disable generating batch methods.
 150
 151 ```sql
 152 -- generateBatchApi: false
 153 SELECT  *
 154 FROM    users
 155 WHERE   id = :userId
 156 ```
 157
 158 ## generateStreamEagerApi
 159
 160 The `generateStreamEagerApi` field can be used to overwrite the globally configured `generateStreamEagerApi` option. Use `generateStreamEagerApi` in case you want to enable/disable generating eager stream methods.
 161
 162 ```sql
 163 -- generateStreamEagerApi: false
 164 SELECT  *
 165 FROM    users
 166 WHERE   id = :userId
 167 ```
 168
 169 ## generateStreamLazyApi
 170
 171 The `generateStreamLazyApi` field can be used to overwrite the globally configured `generateStreamLazyApi` option. Use `generateStreamLazyApi` in case you want to enable/disable generating lazy stream methods.
 172
 173 ```sql
 174 -- generateStreamLazyApi: false
 175 SELECT  *
 176 FROM    users
 177 WHERE   id = :userId
 178 ```
 179
 180 ## generateRxJavaApi
 181
 182 The `generateRxJavaApi` field can be used to overwrite the globally configured `generateRxJavaApi` option. Use `generateRxJavaApi` in case you want to enable/disable generating rxjava2 based methods.
 183
 184 ```sql
 185 -- generateRxJavaApi: false
 186 SELECT  *
 187 FROM    users
 188 WHERE   id = :userId
 189 ```
 190
 191 ## catchAndRethrow
 192
 193 The `catchAndRethrow` field can be used to overwrite the globally configured `catchAndRethrow` option. Use `catchAndRethrow` in case you want to enable/disable catching checked exceptions and rethrowing them as runtime exceptions.
 194
 195 ```sql
 196 -- catchAndRethrow: true
 197 SELECT  *
 198 FROM    users
 199 WHERE   id = :userId
 200 ```