How to contribute

Error Reports

Please report any issue to the GitHub Issue Tracker:

  1. Provide the Sample SQL (shortened and simplified, properly formatted)

  2. State the exact Version of the Presto SQL:2016 Parser

  3. State the RDBMS in use and point on the applicable Grammar specification

  4. Please write in English and post Plain Text only (avoiding screen shots or bitmap pictures).

Feature Requests

Presto SQL:2016 Parser is a demand-driven software library, where many contributors have shared solutions for their own needs. Requests for new features have a good chance to get implemented when

  1. the request is about a commonly used feature for one of the major RDBMS

  2. or the request is backed by a sponsor or a bounty, which may attract developers to spend their time on it.

Implementing new Features

The team around Presto SQL:2016 Parser warmly welcomes Code Contributions and Pull Requests. Please follow the guidance below and do not hesitate to ask us for assistance.

Create a new Git Branch

When starting afresh, clone the Presto SQL:2016 Parser from the GitHub repository:

git clone https://github.com/prestodb/sql.git
cd sql
git branch <new-branch>

When having a local repository already, then pull/merge from the GitHub repository:

cd sql
git pull origin master
git branch <new-branch>

Amend the Code

The Presto SQL:2016 Parser is generated by JavaCC based on the provided Grammar. The Grammar defines how a SQL Text is read and translated into Java Objects. Thus any contribution will depend on the following steps:

  1. Edit the JavaCC Grammar at sql/parser/grammar

  2. Add or edit the Java Classes at sql/parser/src/main/java/com/facebook/coresql/parser/ to facilitate this Grammar.

  3. Provide Java Unit Tests at sql/parser/src/test/java/com/facebook/coresql/parser/ to test the new feature

    • The test should call the method TestUtils.assertParseAndUnparse() at least one time

    • The test should ensure complete coverage of the new Java Classes.

    • The complete test suite must succeed.

  4. Add the description of the new feature to the README.md file, section Extensions.

  5. Build the package with Maven and ensure, all checks do pass (PMD and CheckStyle and Code Formatting).

Manage Reserved Keywords

Since Presto SQL:2016 Parser is built by JavaCC from a Token based Grammar, Reserved Keywords need a special treatment. All Tokens of the Grammar would become Reserved Keywords – unless explicitly allowed.

Allow Keyword example
-- <OVERLAPS:"OVERLAPS"> is a Token, recently defined in the Grammar
-- Although it is not restricted by the SQL Standard and could be used for Column, Table and Alias names
-- Explicitly allowing OVERLAPS by adding it to the  NonReservedKeywords() Production will allow for parsing the following statement

SELECT Overlaps( overlaps ) AS overlaps
FROM overlaps.overlaps overlaps
WHERE overlaps = 'overlaps'
    AND (CURRENT_TIME, INTERVAL '1' HOUR) OVERLAPS (CURRENT_TIME, INTERVAL -'1' HOUR)
;

So we will need to define and allow any Keywords which may be allowed for Object Names (such as Schema, Table, Column, Function, Alias). This White-List must be updated whenever the Tokens of the Grammar change (e. g. when adding a new Token or Production). Otherwise any new Token or Production will become a Reserved Keyword automatically and can’t be used for Object Names without quoting.

Commit a Pull Request

cd sql
git add -A
git commit -m <title> -m <description>
git push –set-upstream origin <new-branch>

Follow the advice on Meaningful Commit Messages and consider using Commitizen when describing your commits.

Please consider using Conventional Commits and structure your commit message as follows:

Conventional Commit Message Structure
<type>[optional scope]: <description>

[optional body]

[BREAKING CHANGE: <change_description>]

[optional footer(s)]
Commit Message Types

Type

Description

feat

introduce a new feature

fix

patches a bug in your codebase (bugfix or hotfix)

build

changes that affect the build system or external dependencies

chore

updates dependencies and does not relate to fix or feat and does not modify src or test files.

ci

changes that affect the continuous integration process

docs

updates the documentation or introduce documentation

style

updates the formatting of code; remove white spaces, add missing spaces, remove unnecessary newlines

refactor

reactors code segments to optimize readability without changing behavior

perf

improve performance

test

add/remove/update tests

revert

reverts one or many previous commits

Please visit Better Programming for more information and guidance.