Skip to main content

Project Configurations

After creating a VulcanSQL project by vulcan init, you will see a file named vulcan.yaml under the root of the project directory. You can see VulcanSQL's project configurations like data source, authentication, API Documentation, etc. in the vulcan.yaml.

The project configuration file

Although we said that the vulcan.yaml is the main VulcanSQL project configuration file, but it is not mandatory. You could change its file name whatever you like by passing the option. However, vulcan.yaml is the default filename when you use commands like vulcan build, vulcan serve, or vulcan start. Therefore, if you rename vulcan.yaml to hello-world.yaml, then when you run the above commands, you should add the option -c or --config:

$ mv vulcan.yaml hello-world.yaml
$ vulcan start -c ./hello-world.yaml  # set the configuation filename to `hello-world.yaml`

The structure of the project configurations

When you run vulcan init, you will see some configurations you have pre-defined, below is a sample of the file content:

# The project name, description and version
name: my-first-vulcan-project
description: A starter VulcanSQL project
version: 0.2.0

# The configuration options of core features
template:
  provider: LocalFile
  folderPath: sqls
  codeLoader: InMemory
artifact:
  provider: LocalFile
  serializer: JSON
  filePath: result.json
schema-parser:
  reader: LocalFile
  folderPath: sqls
document-generator:
  specs:
    - oas3
types:
  - RESTFUL

# The configuration options of built-in extensions
profiles:
  - profile.yaml
rate-limit:
  options:
    interval:
      min: 1
    max: 10000
enforce-https:
  enabled: false
auth:
  enabled: false
response-format:
  enabled: true
  options:
    default: json
    formats:
      - json
      - csv

# The external extension modules you would like to use in your VulcanSQL project
extensions:
  duckdb: '@vulcan-sql/extension-driver-duckdb'

You will see four major sections in the vulcan.yaml, the sections consist of project information, configuration options of core features, built-in extensions, and external extensions.

Project information​

In the VulcanSQL project configuration, we will provide a section for you to define the project name and a description for the project's purpose. The version will record based on your API version, you should fill in this value when your API changes by following semver conventions.

name: my-first-vulcan-project
description: A starter VulcanSQL project
version: 0.2.0

Configuration options of core features​

VulcanSQL has some configuration options related to our core features:

template:
  provider: LocalFile
  folderPath: sqls
  codeLoader: InMemory
artifact:
  provider: LocalFile
  serializer: JSON
  filePath: result.json
schema-parser:
  reader: LocalFile
  folderPath: sqls
document-generator:
  specs:
    - oas3
types:
  - RESTFUL
profiles:
  - profile.yaml

Actually, the template, artifact, and document-generator options are related to the vulcan build and vulcan serve commands and we called them build phase and serving phase. The schema-parser, types and profiles are used in the serving phase.

Build phase and Serving phase​

In the build phase, VulcanSQL will use the template options to find where is the user-written SQL files and compile the SQL files to the compiled artifact file according to the artifact options.

In the serving phase, VulcanSQL will use the schema-parser options to find where is the user-written API schema files, then VulcanSQL will check the API protocol user would like to create as the API endpoints, according to the types option.

When API is created and users send requests to the API endpoints, VulcanSQL will use the template and artifact options again for translating the SQL files and send to data sources. VulcanSQL relies on profiles options to find each data source connection settings.

template options​

  • provider - The provider represents what is the provider used to read the SQL files. VulcanSQL uses the LocalFile type as a default value, which means the SQL files are put in local places.
  • codeLoader - The codeLoader option tells the compiler what code loader type we keep the data in, and the default value is InMemory .
  • folderPath - When the provider is LocalFile, we need to set the folderPath option. The folderPath indicates a folder location where your SQL files are located at.
template:
  provider: LocalFile
  folderPath: path/to/folder
  codeLoader: InMemory

If you provide the folder name directly, we will find the folder in the current project.

folderPath: sqls # path to ./sqls folder

artifact options​

  • provider - Similar to template options' provider, but it is used to save and read the artifact file. The default value is LocalFile.
  • serializer - It indicates the format the compiled artifact file is serialized to.
  • filePath - The location to the compiled artifact file.
artifact:
  provider: LocalFile
  serializer: JSON
  filePath: path/to/file.json

schema-parser options​

  • reader - Similar to template options' provider The default value is LocalFile.
  • folderPath - When the provider is LocalFile, we need to set the folderPath option. The folderPath indicates a folder location where your API schema files are located at.
schema-parser:
  reader: LocalFile
  folderPath: sqls # Path to ./sqls folder

We suggest you put each API schema file in the same folder as respsective SQL file and have the same name as the respective SQL file.

/sqls
  # Query order SQL file and its API schema file
  - orders.sql
  - orders.yaml
  # Query users SQL file and its API schema file
  - ursers.sql
  - users.yaml

For the API schema file configurations, we will talk more in API Schema.

document-generator options​

  • specs - It's the specification used in the API document. The document generator will generate the specifications and make our document server run it. The default is Open API 3.0 specification.
document-generator:
  specs:
    - oas3

Built-in and External Extensions​

You could set the VulcanSQL extension configurations. The Extensions grant users power to do powerful things. VulcanSQL also has some built-in extensions, and you can check out here.

Here is a configuration sample of VulcanSQL's built-in extensions, and these extensions work in the serving phase to privde the APIs with more restrictions when sending requests.

profiles:
  - profile.yaml
rate-limit:
  options:
    interval:
      min: 1
    max: 10000
enforce-https:
  enabled: false
auth:
  enabled: false
response-format:
  enabled: true
  options:
    default: json
    formats:
      - json
      - csv

Every built-in extension has its configuration, but you don't need to define all of them manually because we have default configurations for most of them.

For the above configuration, if you are interested, you could see Data Source Profile, Rate Limit, Enforce HTTPs, Response Format, Authentication first.