### Initialize and Run VulcanSQL Project Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/get-started/first-api.mdx Commands to initialize a VulcanSQL project based on installation method (NPM or binary), start the server in watch mode, and test the default API endpoint. ```bash vulcan hello ``` ```bash vulcan init --template=quick-start-from-nodejs ``` ```bash vulcan start --watch ``` ```bash curl http://localhost:3000/api/flights ``` -------------------------------- ### Install VulcanSQL Catalog Server via Binary Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/catalog/installation.mdx This method installs the VulcanSQL catalog server by pulling a Docker image from Github Packages. Ensure Docker is running before executing the command. After execution, the server will start listening on http://localhost:4200. ```bash vulcan catalog ``` -------------------------------- ### Install VulcanSQL Project Source: https://github.com/canner/vulcan-sql/blob/develop/labs/playground1/README.md Commands to install VulcanSQL packages and dependencies for the playground project. This includes navigating to the project directory, installing Node.js packages with yarn, and building the project using make. ```bash cd ./lab/playground1 yarn make ``` -------------------------------- ### Install VulcanSQL Catalog Server via NPM Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/catalog/installation.mdx This method installs the VulcanSQL catalog server package using NPM. It requires Node.js version 16 or higher and a package manager like NPM or Yarn. After installation, the catalog server can be started by running the 'vulcan catalog' command, which will make it listen on http://localhost:4200. ```bash npm i @vulcan-sql/catalog-server ``` -------------------------------- ### Start Node.js Production Server Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/deployment.mdx Installs project dependencies and starts the VulcanSQL server on production Node.js environments. This command should be run after copying the generated ./dist folder contents to the server. ```bash npm install && node index.js ``` -------------------------------- ### Install Dependencies with Yarn Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/README.md Installs project dependencies using Yarn. This command should be run first to set up the project environment. ```shell $ yarn ``` -------------------------------- ### Install Catalog Server Package Source: https://github.com/canner/vulcan-sql/blob/develop/packages/catalog-server/README.md Installs the catalog server package using npm. This command is the initial step for setting up the catalog server locally or in a development environment. ```bash npm i @vulcan-sql/catalog-server ``` -------------------------------- ### Initialize VulcanSQL Project Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/develop/init.mdx Creates a new VulcanSQL project directory with the specified name and template. Requires the VulcanSQL CLI to be installed. The template determines the project structure based on the CLI installation method. ```bash vulcan init my-api-project --template=binary ``` ```bash vulcan init my-api-project --template=nodejs ``` -------------------------------- ### Start VulcanSQL Server Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/develop/init.mdx Starts the VulcanSQL server, enabling you to develop and test your API. The `--watch` flag enables hot-reloading, automatically restarting the server when changes are detected in your project files. ```bash vulcan start --watch ``` -------------------------------- ### Install ksqlDB Extension (npm) Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/connectors/ksqldb.mdx Installs the ksqlDB driver extension package for Vulcan SQL. This step is skipped if developing with a pre-bundled binary. ```bash npm i @vulcan-sql/extension-driver-ksqldb ``` -------------------------------- ### Start Local Development Server Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/README.md Starts a local development server for live preview. Changes are reflected in real-time without needing to restart the server. ```shell $ yarn start ``` -------------------------------- ### Install VulcanSQL CLI on Windows (Binary) Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/get-started/installation.mdx Download the VulcanSQL CLI executable for Windows, extract the zip file, and place the 'vulcan.exe' file in a desired directory. ```shell 1. Download: vulcan.win.zip 2. Extract the zip folder. 3. Move vulcan.exe to your preferred directory. ``` -------------------------------- ### Install Local Extension Package Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/extensions/make-extension.mdx Command to install your local extension package by specifying its folder path. This is an alternative to `npm link` for local development. ```bash $ npm i /Users//Code/my-extension ``` -------------------------------- ### Initialize gcloud CLI Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/deployment/gcp-app-engine.mdx Initializes the Google Cloud CLI, setting up your local environment to interact with GCP services. This command guides you through project selection and configuration. ```shell gcloud init ``` -------------------------------- ### Start Catalog Server CLI Source: https://github.com/canner/vulcan-sql/blob/develop/packages/catalog-server/README.md Starts the VulcanSQL catalog server using the VulcanSQL CLI. This command assumes the main VulcanSQL server is already running and listening. ```bash vulcan catalog ``` -------------------------------- ### YAML Configuration Example Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/api-building/rate-limit.mdx Example of how to configure rate limiting settings in the vulcan.yaml file, including enabling the feature and setting options like interval and max requests. ```yaml rate-limit: enabled: true options: interval: min: 1 max: 10000 ``` -------------------------------- ### Curl Command Response Example Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/api-building/sql-syntax.mdx An example of a response received after sending a request using the curl command, showing HTTP headers and a JSON payload. ```shell # The response by sending the request which used curl command < HTTP/1.1 200 OK < Vary: Origin < ... [{"$1":"CANNER"}]% ``` -------------------------------- ### Install KSqlDb Extension Driver Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-driver-ksqldb/README.md Installs the KSqlDb driver package using npm. This is the first step to integrate KsqlDB functionality into VulcanSQL. ```bash npm i @vulcan-sql/extension-driver-ksqldb ``` -------------------------------- ### Install VulcanSQL CLI on Linux (Binary) Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/get-started/installation.mdx Download the pre-built VulcanSQL CLI binary for Linux, extract it, and move the executable to a directory in your system's PATH. ```bash tar zxvf vulcan.linux.tar.gz mv vulcan /usr/local/bin ``` -------------------------------- ### Access Log Output Example Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/api-plugin/access-log.mdx This example demonstrates the typical output format of the Access Log when configured. It includes timestamps, log levels, request details, and associated metadata. ```bash 2022-09-26 08:04:08.307 INFO [ACCESS_LOG packages/serve/src/lib/middleware/accessLogMiddleware.ts:23 AccessLogMiddleware.] --> ::1 -- "GET /api/artist/1" -- size: none 2022-09-26 08:04:08.308 INFO [ACCESS_LOG packages/serve/src/lib/middleware/accessLogMiddleware.ts:26 AccessLogMiddleware.] -> header: {"xxxxxxxxxxxx"} 2022-09-26 08:04:08.308 INFO [ACCESS_LOG packages/serve/src/lib/middleware/accessLogMiddleware.ts:27 AccessLogMiddleware.] -> query: {} 2022-09-26 08:04:08.310 INFO [ACCESS_LOG packages/serve/src/lib/middleware/accessLogMiddleware.ts:28 AccessLogMiddleware.] -> params: undefined ``` -------------------------------- ### Install VulcanSQL Base Packages Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/extensions/make-extension.mdx Installs the necessary VulcanSQL core packages required for building custom extensions. These packages provide the base components to extend. ```bash npm i @vulcan-sql/core @vulcan-sql/build @vulcan-sql/serve ``` -------------------------------- ### Install VulcanSQL CLI on MacOS (Binary) Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/get-started/installation.mdx Download the pre-built VulcanSQL CLI binary for macOS, extract it, and move the executable to a directory in your system's PATH. ```bash tar zxvf vulcan.osx.tar.gz mv vulcan /usr/local/bin ``` -------------------------------- ### SQL Builder Example (VulcanSQL) Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/api-building/predefined-queries.mdx Introduces the upcoming 'SQL Builder' feature, which provides a fluent API for constructing SQL statements in a more readable manner. This example shows how to chain methods for building a query. ```VulcanSQL {% req user %} select * from public.users where name = '{{ context.params.id }}' {% endreq %} {% req orders %} select * from public.orders {% endreq } -- constructing sql statement with a fluent API {% req result main %} orders .where('userId', user.value().id ) .andWhere('price','>', '10000') .select() .orderBy('price', 'desc') .limit(10) {% endreq %} ``` -------------------------------- ### Call REST API with GET Request Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/extensions/api.mdx A minimal example demonstrating how to call a REST API using the `rest_api` function within a SQL SELECT statement. It fetches data from a specified URL. ```sql SELECT {{ {} | rest_api(url='https://dummyjson.com/products/1') }} ``` -------------------------------- ### Curl Request for Path Parameter Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/develop/dynamic-param.mdx Example `curl` command to send a GET request to an API endpoint, passing the 'id' parameter in the URL path to fetch a specific user. ```bash curl -X GET "http://localhost:3000/api/users/1" ``` -------------------------------- ### Create Index File for Extensions Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/extensions/make-extension.mdx Steps to create the initial entry file for your custom extension. This is the first step in preparing your extension for VulcanSQL. ```bash my-extension $ touch index.js ``` ```bash my-extension $ touch index.ts ``` -------------------------------- ### Curl Request for Query Parameter Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/develop/dynamic-param.mdx Example `curl` command to send a GET request to an API endpoint, passing the 'age' parameter in the querystring to dynamically filter user data. ```bash curl -X GET "http://localhost:3000/api/users?age=18" ``` -------------------------------- ### Curl Request for Header Parameter Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/develop/dynamic-param.mdx Example `curl` command to send a GET request to an API endpoint, passing the 'id' parameter in the request header to dynamically filter user data. ```bash curl -X GET "http://localhost:3000/api/users" -H "id: 1" ``` -------------------------------- ### Sample VulcanSQL Project Configuration (vulcan.yaml) Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/references/project-configurations.mdx A comprehensive example of a VulcanSQL project configuration file, illustrating sections for project metadata, core features, built-in extensions, and external modules. ```yaml # 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' ``` -------------------------------- ### Install VulcanSQL CLI via Pip Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/get-started/installation.mdx Install the VulcanSQL CLI using Python's package installer (Pip). Requires Python versions 3.3.x to 3.11.x. ```python $ pip install vulcan-sql $ vulcan --help ``` -------------------------------- ### Install VulcanSQL CLI via NPM Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/get-started/installation.mdx Install the VulcanSQL CLI globally using the Node Package Manager (NPM). Requires Node.js version 16 or higher. ```bash npm i -g @vulcan-sql/cli ``` -------------------------------- ### Install Hugging Face Extension Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/extensions/huggingface/overview.mdx Command to install the Hugging Face extension package for VulcanSQL using npm. This step is only required if VulcanSQL is not installed in its binary version, which includes the extension by default. ```bash npm i @vulcan-sql/extension-huggingface ``` -------------------------------- ### SQL Template Example Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/extensions/vulcan-sql-core/filter/filter-runner.mdx Demonstrates a SQL template using the 'prefix' filter with arguments. This shows how data can be transformed using filters within a SQL context. ```sql {{ 'id' | prefix(pre='vulcan') }} ``` -------------------------------- ### Build CLI Library with Nx Source: https://github.com/canner/vulcan-sql/blob/develop/packages/cli/README.md Builds the CLI library using Nx. This command compiles the library and prepares it for deployment or further use. ```shell nx build cli ``` -------------------------------- ### Install Canner Extension Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-store-canner/README.md Installs the Canner extension package and configures VulcanSQL to use it. ```bash export NPM_TOKEN= npm i @vulcan-sql/extension-store-canner ``` ```yaml extensions: canner-store: '@vulcan-sql/extension-store-canner' ``` -------------------------------- ### Fly.io CLI Command Overview Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/deployment/flydotio.mdx Displays the available commands and basic usage for the `flyctl` command-line interface, used for managing Fly.io applications. ```shell % fly This is flyctl, the Fly.io command line interface. Here's a few commands to get you started: fly launch Launch a new application fly apps Create and manage apps fly postgres Create and manage Postgres databases fly mysql Create and manage PlanetScale MySQL databases fly redis Create and manage Upstash Redis databases fly machines Create and manage individual Fly.io machines If you need help along the way: fly help Display a complete list of commands fly help Display help for a specific command, e.g. 'fly help launch' Visit https://fly.io/docs for additional documentation & guides ``` -------------------------------- ### Install PostgreSQL Driver Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-driver-pg/README.md Installs the PostgreSQL driver package using npm. ```bash npm i @vulcan-sql/extension-driver-pg ``` -------------------------------- ### API Validation Error Response Example Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/api-building/api-validation.mdx An example of the JSON error response returned by VulcanSQL when an API request fails validation checks. ```yaml # order.yaml urlPath: /orders request: - fieldName: price fieldIn: query validators: - name: number args: min: 0 max: 1000000 # Example of an invalid request response: { code: 'vulcan.userError', message: 'The input parameter is invalid, it should be integer type', } ``` -------------------------------- ### Basic SQL Query Example Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/api-building/sql-syntax.mdx Demonstrates a basic SQL query to select users within a specific age range. This SQL file is placed in a designated folder and used to define a Data API endpoint. ```sql SELECT * FROM public.users WHERE age >= 10 AND age <= 19; ``` -------------------------------- ### Install ClickHouse Driver Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-driver-clickhouse/README.md Installs the ClickHouse driver package using npm. This is the initial step to integrate ClickHouse functionality into VulcanSQL. ```bash npm i @vulcan-sql/extension-driver-clickhouse ``` -------------------------------- ### Install Test Utility Package Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/extensions/test-extension.mdx Installs the `@vulcan-sql/test-utility` package as a development dependency, which is required for writing unit tests for filter and tag extensions. ```bash npm i --save-dev @vulcan-sql/test-utility ``` -------------------------------- ### Build the Core Library Source: https://github.com/canner/vulcan-sql/blob/develop/packages/core/README.md Builds the core library using Nx. This command compiles the library and prepares it for deployment or further use. ```shell nx build core ``` -------------------------------- ### Install PostgreSQL Extension Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/connectors/postgresql.mdx Installs the PostgreSQL driver extension for Vulcan SQL using npm. This is a prerequisite for enabling PostgreSQL support. ```bash npm i @vulcan-sql/extension-driver-pg ``` -------------------------------- ### Navigate to Project Directory Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/develop/init.mdx Changes the current working directory to the newly created VulcanSQL project folder. This is a standard command-line operation necessary before running project-specific commands. ```bash cd my-api-project ``` -------------------------------- ### Install DuckDB Extension Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/connectors/duckdb.mdx Installs the necessary npm package for the DuckDB extension. This is the first step for integrating DuckDB with Vulcan SQL. ```bash npm i @vulcan-sql/extension-driver-duckdb ``` -------------------------------- ### Response Example for Text Generation Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-huggingface/README.md Example JSON response format for a text generation query executed via the `huggingface_text_generation` filter. ```JSON [ { "result": "Answer: Based on the provided list, the top-ranked university is Massachusetts Institute of Technology (MIT) with a rank of 1." } ] ``` -------------------------------- ### Install Hugging Face Extension Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-huggingface/README.md Installs the @vulcan-sql/extension-huggingface package using npm. This is the first step to enable Hugging Face integration in VulcanSQL. ```bash npm i @vulcan-sql/extension-huggingface ``` -------------------------------- ### Fly.io Deployment Configuration (`fly.toml`) Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/deployment/flydotio.mdx An example `fly.toml` file generated by `fly launch`, defining application settings such as the app name, primary region, and HTTP service configuration for deployment on Fly.io. ```toml # fly.toml app configuration file generated for xxxxx on 2023-07-13T22:40:54+08:00 # # See https://fly.io/docs/reference/configuration/ for information about how to use this file. # app = "xxxxx" primary_region = "bos" [http_service] internal_port = 3000 force_https = true auto_stop_machines = false auto_start_machines = false min_machines_running = 1 processes = ["app"] ``` -------------------------------- ### Access Log Output Example Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/api-building/access-log.mdx Sample output demonstrating the format and information provided by the access log service. This includes timestamps, log levels, request details, and associated metadata. ```text 2022-09-26 08:04:08.307 INFO [ACCESS_LOG packages/serve/src/lib/middleware/accessLogMiddleware.ts:23 AccessLogMiddleware.] --> ::1 -- "GET /api/artist/1" -- size: none 2022-09-26 08:04:08.308 INFO [ACCESS_LOG packages/serve/src/lib/middleware/accessLogMiddleware.ts:26 AccessLogMiddleware.] -> header: {"xxxxxxxxxxxx"} 2022-09-26 08:04:08.308 INFO [ACCESS_LOG packages/serve/src/lib/middleware/accessLogMiddleware.ts:27 AccessLogMiddleware.] -> query: {} 2022-09-26 08:04:08.310 INFO [ACCESS_LOG packages/serve/src/lib/middleware/accessLogMiddleware.ts:28 AccessLogMiddleware.] -> params: undefined ``` -------------------------------- ### Install Snowflake Driver Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-driver-snowflake/README.md Installs the Snowflake extension driver package using npm. This is the first step to enable Snowflake connectivity in VulcanSQL. ```bash npm i @vulcan-sql/extension-driver-snowflake ``` -------------------------------- ### App Engine Configuration (app.yaml) Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/deployment/gcp-app-engine.mdx Create an `app.yaml` file to define the App Engine runtime environment and configuration. This includes specifying the Node.js runtime, environment type, operating system, runtime version, and environment variables like the VulcanSQL API Server URL. ```yaml runtime: nodejs env: flex runtime_config: operating_system: "ubuntu22" runtime_version: "18" env_variables: VULCAN_SQL_HOST: [Your VulcanSQL API Server URL] ``` -------------------------------- ### Configure API Endpoint Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/get-started/first-api.mdx YAML configuration file that defines the URL path for a new API endpoint and specifies the database profile to be used (e.g., 'duckdb'). ```yaml urlPath: /flight profiles: - duckdb ``` -------------------------------- ### Fly.io Authentication: Signup Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/deployment/flydotio.mdx Executes the command to sign up for a new Fly.io account. Requires internet access and prompts for user input. ```bash fly auth signup ``` -------------------------------- ### TypeScript Transform Function Example Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/extensions/vulcan-sql-core/filter/filter-runner.mdx An example of the `transform` function within a custom FilterRunner. It takes `FilterRunnerTransformOptions` including value and arguments, and returns a transformed string. ```ts public async transform( options: FilterRunnerTransformOptions ): Promise { options.value; // 'id' optoins.args; // {pre: 'vulcan'} return `${toptions.args.pre}-${options.value}` } ``` -------------------------------- ### Package VulcanSQL Catalog Server Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/deployment/gcp-app-engine.mdx This command packages the VulcanSQL API Catalog Server for deployment. It generates a 'dist' folder containing the necessary files. Ensure this folder is renamed if you previously packaged the API server to avoid overwriting. ```shell vulcan package -t catalog-server ``` -------------------------------- ### CORS Configuration Example Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/drafts/api-building/cors.mdx Example YAML configuration for enabling CORS and setting specific options like origin and allowed methods. ```yaml cors: enabled: true options: origin: 'http://google.com' allowMethods: 'GET,HEAD,PUT' ``` -------------------------------- ### Install Redshift Extension Driver Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-driver-redshift/README.md Installs the Redshift extension driver package for VulcanSQL using npm. This is the first step to enable Redshift connectivity. ```bash npm i @vulcan-sql/extension-driver-redshift ``` -------------------------------- ### Install Vulcan Debug Extension Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-debug-tools/README.md Installs the `@vulcan-sql/extension-debug-tools` package using npm. This is the first step to enable debugging features for Vulcan SQL extensions. ```bash npm i @vulcan-sql/extension-debug-tools ``` -------------------------------- ### Deploy VulcanSQL API Catalog Server to Fly.io Source: https://github.com/canner/vulcan-sql/blob/develop/packages/doc/docs/deployment/flydotio.mdx Commands to launch and deploy the VulcanSQL API Catalog Server to Fly.io. These commands are similar to deploying the API Server but are used after packaging the catalog server. ```shell fly launch fly deploy ``` -------------------------------- ### Install Canner Authenticator Package Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-authenticator-canner/README.md Installs the Canner authenticator extension package using npm. This is the first step to integrate Canner authentication with VulcanSQL. ```bash npm i @vulcan-sql/extension-authenticator-canner ``` -------------------------------- ### Install VulcanSQL API Caller Extension Source: https://github.com/canner/vulcan-sql/blob/develop/packages/extension-api-caller/README.md Installs the @vulcan-sql/extension-api-caller package using npm. This is the first step to enable API calling capabilities in VulcanSQL. ```bash npm i @vulcan-sql/extension-api-caller ```