yosql-website/content/sql/sql-files.md

   1 ---
   2 title: SQL Files
   3 date: 2019-07-07T14:27:54+02:00
   4 menu:
   5   main:
   6     parent: SQL
   7 categories:
   8   - SQL
   9 tags:
  10   - sql
  11   - files
  12 ---
  13
  14 Writing `.sql` files is the essential work that needs to be done in order to use `YoSQL`. Each file can contain multiple SQL statements. Each statement has its own configuration and metadata attached to it.
  15
  16 ## Statement Type
  17
  18 `YoSQL` supports the tree types of SQL statements and is able to generate code for them: `READING` for SQL statements that read data, `WRITING` for SQL statements that write data, and `CALLING` for SQL statements that call stored procedures.
  19
  20 In order to correctly guess which type your statement is, `YoSQL` does not parse your SQL code, but uses the file name of your `.sql` files or the `name` front matter. It applies the following rules to determine the statement type from its name:
  21
  22 - All names that start with the [configured read prefixes](/configuration/repositories/allowedreadprefixes/) are assigned the `READING` type.
  23 - All names that start with the [configured write prefixes](/configuration/repositories/allowedwriteprefixes/) are assigned the `WRITING` type.
  24 - All names that start with the [configured call prefixes](/configuration/repositories/allowedcallprefixes/) are assigned the `CALLING` type.
  25
  26 SQL statements that cannot be mapped to one of the available types **are not considered** while generating code! You can always overwrite that guess with a specific [type](/configuration/sql/type/) value in your front matter. This can be useful if you want to use a special name for your statement, but don't want to adhere to the configured prefixes. On the other hand, enable [validateMethodNamePrefixes](/configuration/repositories/validatemethodnameprefixes/) to enforce that all statements are named accordingly to the configured prefixes.
  27
  28 ## Front Matter
  29
  30 Each SQL statement can have an optional front matter section written in YAML that is placed inside an SQL comment. Configuration options that are specified in a front matter of an SQL statement overwrite the same option that was specified globally, e.g. in a `pom.xml`/`build.gradle` file.
  31
  32 ```sql
  33 -- name: someName
  34 -- description: Retrieves a single user
  35 -- repository: com.example.persistence.YourRepository
  36 -- vendor: H2
  37 -- parameters:
  38 --   - name: userId
  39 --     type: int
  40 -- type: reading
  41 -- returning: one
  42 -- catchAndRethrow: true
  43 SELECT  *
  44 FROM    users
  45 WHERE   id = :userId
  46 ```
  47
  48 While parsing your `.sql` files, `YoSQL` will strip the SQL comment prefix (`--`) and read the remaining text as a YAML object. The available configuration options that can be used in the front matter, can be seen [here](/configuration/sql/).
  49
  50 ## File Extension
  51
  52 By default, `YoSQL` only considers files that end in `.sql`, but this can be configured using the [sqlFilesSuffix](/configuration/files/sqlfilessuffix) option. Lots of editors have built-in syntax support for SQL and they auto-enable that once you open an `.sql` file, so we recommend to stick to the default and only change if it necessary.
  53
  54 ## File Charset
  55
  56 By default, `YoSQL` uses the **UTF-8** charset. In order to change this, use the [sqlFilesCharset](/configuration/files/sqlfilescharset) option.
  57
  58 ## Statement Separator
  59
  60 By default, `YoSQL` uses `;` to separate multiple SQL statements within a single file. In order to change this, use the [sqlStatementSeparator](/configuration/files/sqlstatementseparator) option.
  61
  62 ```sql
  63 -- name: firstStatement
  64 SELECT  *
  65 FROM    users
  66 WHERE   id = :userId
  67 ;
  68
  69 -- name: secondStatement
  70 SELECT  *
  71 FROM    customers
  72 WHERE   id = :customerId
  73 ;
  74 ```
  75
  76 ## License Headers
  77
  78 In case your `.sql` files contain a license header, use the [skipLines](/configuration/files/skiplines) option to skip those initial lines. Otherwise `YoSQL` will consider those lines to be part of the first statement in your `.sql` file.