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 data API schema file
  - ursers.sql
  - users.yaml

For the API schema file Configuration, we will talk more in Data 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

Built-in extension configurations​

VulcanSQL provides the extension components to let users could extend it for making VulcanSQL powerful, and VulcanSQL also uses the extension components to create built-in extensions which enable it to run the feature.

Like the below configurations, The profiles, rate-limit, enforce-https, response-format, and auth are our built-in extensions. These extensions work in serve phase to make the API request 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.

We'll talk about the detailed configuration of extensions in their chapters.

For the above configuration, if you are interested, you could see Data Source Profile, Rate Limit, Enforce HTTPS, Response Format, and Access Control first.

External extension configurations​

Besides built-in extensions, users could extend our extension components to create extensions, and these extended extensions are called external extensions.

VulcanSQL had created some external extensions, if you would like to use these extensions, you could follow the below structure to define them.

# Declare you would like to used-external module and give a module name
extensions:
  ext-module-name1: @vulcan-sql/xxx-module # installed VulcanSQL module
  ext-module-name2: path/to/folder/of/package # path

ext-module-name1:
  ... # The config options of the ext-module-name1

ext-module-name2:
  ... # The config options of ext-module-name2

# The config options of core feature and built-in extension
...

The extensions config could let user could declare what external extensions they would like to use in the VulcanSQL project.

The user should declare a variable called module name and specify it external extension location. The location has two ways to specify:

  • module name
  • local module folder path.

Specify the module name​

you could use npm or yarn to install a 3rd-party source or VulcanSQL-provided external extension package ( @vulcan-sql/xxx-ext-module format ) and specify the package module name, e.g: ext-module-name-1 :

extensions:
  ext-module-name1: @vulcan-sql/xxx-module # installed VulcanSQL module

For example, if you would like to use @vulcan-sql/dbt it looks like the below:

extensions:
  dbt: '@vulcan-sql/extension-dbt'

dbt:
  modelFiles: path/to/folder

Specify the local module file path​

If you would like to use your local developed external extensions, you could specify the module path e.g: ext-module-name-2 :

extensions:
  ext-module-name2: path/to/folder/of/package # path

# Set the configuration options of the ext-module-name2 if ext-module-name2 provide configurations to let user could set.
ext-module-name2: ...

Not all external extensions have configuration options​

Not all external extensions have configuration options, some options maybe rely on internal or built-extensions configuration options and set options under internal or built-extensions config options. We should check each document of the external extensions module.

For example, if you would like to use @vulcan-sql/duckdb it looks like the below:

extensions:
  duckdb: '@vulcan-sql/extension-driver-duckdb'

But the duckdb is an data source driver, so if you would like to make your Data API /orders could query orders from duckdb driver, you should define the duckdb data source driver in data source profile like below:

# duckdb-profile.yaml
name: duck
type: duckdb
connection:
  persistent-path: ./test-data/moma.db
  log-queries: true
  log-parameters: true
allow: '*'

Or define it directly under the profiles configuration options of built-in extensions with extensions options in the project config:

# vulcan.yaml

# other configuration options core feature
---
extensions:
  duckdb: '@vulcan-sql/extension-driver-duckdb'

profiles:
  - name: duck
    type: duckdb
    connection:
      persistent-path: ./test-data/moma.db
      log-queries: true
      log-parameters: true
    allow: '*'

---
# other configuration options built-in extensions