Skip to main content

Configuration

After creating a VulcanSQL project by vulcan init, you will see a file named vulcan.yaml under the project root. The vulcan.yaml is the where VulcanSQL project configurations stored, to setup core features like data source, authentication, API Documentation, etc... we will introduce it in this chapter.

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 the project configuration file name whatever you like by passing option, but it is the default filename using command like vulcan build, vulcan serve, or vulcan start.

So for example, if you rename the project file name to hello-world.yaml, then when you run the above command, you should add the optional options -c or --config :

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

Structure of the project configuration

It's the default project configuration settings, when you enter vulcan init , you will see some configuration options you have pre-defined, below is a sample of how the file is contructed:

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

# The configuration options of core feature
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 external extension modules you wouldl like to use in your VulcanSQL project
extensions:
  duckdb: '@vulcan-sql/extension-driver-duckdb'

# 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

You will see a split of four major sections by the above comment, the sections consist of our project information, core feature configuration options, built-in extension, and external extension configuration options.

Project information​

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

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

Core feature options​

VulcanSQL has some configuration options related to our core features, below are the core feature options:

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 command and we called build phase and serving phase. For the schema-parser, types and profiles related to serving phase,

Build phase and Serve 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 artifact compiled files to the artifact options defined places.

In the serving phase, VulcanSQL will use the schema-parser option 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 template and artifact options again for translating the SQL files and send to data sources, for the data sources connection information, VulcanSQL rely on profiles option to find each data source settings.

template options​

  • provider - The provider represents what 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 VulcanSQL default use InMemory .
  • folderPath - When the provider is LocalFile, we need to set the folderPath option. The folderPath indicates a folder location which used to put your SQL files.
template:
  provider: LocalFile
  folderPath: path/to/folder
  codeLoader: InMemory

If you put to 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 used to save and read the artifact file. The default value is also for LocalFile
  • serializer - Indicate the format which the compiled artifact file serializes it.
  • filePath - The compiled artifact file kept location.
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 which used to put your API schema files.
schema-parser:
  reader: LocalFile
  folderPath: sqls # Path to ./sqls folder

We suggest you put each API schema file in the same layer as the SQL file and name it as the same SQL file to recognize it easily, otherwise if your API schema does not define some field, VulcanSQL will use the API Schema filename to match the same name SQL file for querying data result:

/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 Configuration, we will talk more in API Schema.

document-generator options​

  • specs - The API document used specifications, 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

Extension​

You could set the VulcanSQL extension configuration. The Extension could let users extend to do powerful things. VulcanSQL also uses the extensions to create built-in extensions which enable it to run the feature.

Below is an configuration sample, these extensions work in serve phase to make the API have 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, and Access Control first.