VulcanSQL Documentation

VulcanSQL provides a suite of API plugins designed to enhance functionality, streamline data processing, and ensure a secure, optimal user experience. These plugins allow developers to control how data is delivered and how the API behaves under load.

Key areas of extensibility and control include:

• Response Format: Standardizing data output (e.g., json, csv) for client consistency.
• Pagination: Managing large datasets by breaking them into smaller, manageable chunks.
• CORS (Cross-Origin Resource Sharing): Managing secure data access across different domains.
• Rate Limiting: Controlling request frequency to prevent abuse and maintain performance.
• Access Logging: Monitoring and analyzing user activities for security and efficiency.

VulcanSQL provides several built-in mechanisms to ensure data confidentiality, integrity, and availability. Developers can implement the following security layers to protect sensitive information:

• Authentication: Verifying the identity of users, devices, or systems.
• Authorization: Controlling the level of access granted after identity is verified.
• Dynamic Data Masking: Obfuscating sensitive information by replacing it with fictional or scrambled data (useful for third-party sharing or UI display).
• Column-Level Security (CLS): Restricting access to specific columns within a database table.
• Row-Level Security (RLS): Limiting access to specific rows within a database table based on user permissions or specific criteria.

The @vulcan-sql/core package provides 10 distinct extension points that allow developers to customize how VulcanSQL interacts with data sources, processes filters and tags, validates input, manages persistence, serializes data, reads profiles, and provides templates.

Key extension pairs include:

• Filter Customization: Use FilterBuilder to define new filter recognition logic and FilterRunner to implement the execution logic for those filters.
• Tag Customization: Use TagBuilder to define new tag recognition logic and TagRunner to implement the execution logic for those tags.

A filter is a mechanism used to transform variables within a SQL template. For example, an upper filter can convert a string to uppercase.

Usage Example:

SELECT * FROM users WHERE name = {{ context.params.name | upper }}

To implement a custom filter in VulcanSQL, you must implement a pair of extensions:

1. FilterBuilder: Responsible for recognizing and building the new filter logic (extending beyond standard Nunjucks filters and built-in VulcanSQL filters).
2. FilterRunner: Responsible for executing the logic defined by the FilterBuilder.

VulcanSQL uses the Nunjucks template engine, allowing you to apply filters to variables using the pipe operator (|). Filters can be chained together for complex transformations.

-- Basic usage
SELECT {{ context.params.name | upper }} AS name_upper

-- Chaining filters
{% set items = ['foo', 'bar', 'bear'] %}
SELECT {{ items | join(",") | upper }} AS items_joined_upper

The raw filter is a custom VulcanSQL filter that outputs the literal value of a variable or dynamic parameter without further transformation. It is primarily used to capture a value into a variable so it can be used for logical checks (like if statements) within the template, preventing the templating engine from trying to evaluate the raw value as a template expression.

{% set gender = (context.params.gender | upper | raw) %}
{% if gender in ['MALE', 'FEMALE'] %}
    SELECT concat('Yes,', {{ context.params.name }}, 'is', {{ gender }}) as message;
{% endif %}