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 JSQLParser
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).

Before reporting any issues, please verify your statement using JSQLFormatter Online.

JSQLParser 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.

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

When starting afresh, clone JSQLParser from the GitHub repository:

git clone https://github.com/JSQLParser/JSqlParser.git
cd JSqlParser
git branch <new-branch>

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

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

The JSQLParser 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 src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt

2. Add or edit the Java Classes at src/main/java/net/sf/jsqlparser to facilitate this Grammar.

3. When have added new Java Classes, amend the Visitors, the Visitor Adaptors, the De-Parsers and the Validators.

4. Provide Java Unit Tests at src/test/java/net/sf/jsqlparser to test the new feature

   • The test should call at least one time the method assertSqlCanBeParsedAndDeparsed()
   • The test should ensure complete coverage of the new Java Classes.
   • The complete test suite must succeed.

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

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

   .. tab:: Gradle
   
       .. code-block:: shell
           :caption: Gradle `check` Task
   
               gradle check
   
   

   .. tab:: Maven
   
       .. code-block:: shell
           :caption: Maven `verify` Task
   
               mvn verify
   
   

7. Verify the performance and avoid any deterioration

       gradle jmh

       Benchmark                               (version)  Mode  Cnt    Score   Error  Units
       JSQLParserBenchmark.parseSQLStatements     latest  avgt   30   83.504 ± 1.557  ms/op
       JSQLParserBenchmark.parseSQLStatements        5.2  avgt   30  400.876 ± 8.291  ms/op
       JSQLParserBenchmark.parseSQLStatements        5.1  avgt   30   85.731 ± 1.288  ms/op
   

8. Create your GitHub Pull Request

Since JSQLParser 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 as identifiers.

The Grammar uses a NonReservedWord() BNF production with inline token declarations, bracketed by MIN_NON_RESERVED_WORD and MAX_NON_RESERVED_WORD sentinel tokens. JavaCC assigns consecutive token kind values to the inline declarations, which enables an efficient O(1) range check in isIdentifierAhead() to determine whether a token can be used as an unquoted identifier.

-- <K_OVERLAPS:"OVERLAPS"> is defined as a non-reserved keyword inside the NonReservedWord() production
-- It can be used for Column, Table and Alias names without quoting

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

When adding a new keyword token to the Grammar:

1. If the keyword should be usable as an unquoted identifier (the common case), add its inline token declaration to the NonReservedWord() production. It will automatically be placed between the sentinel tokens and recognised by the range check.
2. If the keyword must be reserved (e. |_| g. core SQL syntax like SELECT, FROM, WHERE), add it to the Reserved SQL Keywords TOKEN block after the MAX_NON_RESERVED_WORD sentinel.
3. Verify that existing tests pass and that the keyword can be used as a Schema, Table, Column, Function or Alias name where expected.

cd JSqlParser
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:

<type>[optional scope]: <description>

[optional body]

[BREAKING CHANGE: <change_description>]

[optional footer(s)]

Please visit Better Programming for more information and guidance.