How to contribute¶
Please report any issue to the GitHub Issue Tracker:
Provide the Sample SQL (shortened and simplified, properly formatted)
State the exact Version of JSQLParser
State the RDBMS in use and point on the applicable Grammar specification
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
the request is about a commonly used feature for one of the major RDBMS
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 JSQLParser 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 JSQLParser from the GitHub repository:
git clone https://github.com/JSQLParser/JSqlParser.git
git branch <new-branch>
When having a local repository already, then pull/merge from the GitHub repository:
git pull origin master
git branch <new-branch>
Amend the Code¶
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:
Add or edit the Java Classes at
src/main/java/net/sf/jsqlparserto facilitate this Grammar.
When have added new Java Classes, amend the Visitors, the Visitor Adaptors, the De-Parsers and the Validators.
Provide Java Unit Tests at
src/test/java/net/sf/jsqlparserto test the new feature
The test should call at least one time the method
The test should ensure complete coverage of the new Java Classes.
The complete test suite must succeed.
Add the description of the new feature to the
README.mdfile, section Extensions.
Build the package with
Mavenand ensure, all checks do pass (PMD and CheckStyle and Code Formatting).
Manage Reserved Keywords¶
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 and white-listened.
-- <K_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 white-listing OVERLAPS by adding it to the RelObjectNameWithoutValue() 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 white-list 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).
There is a task
updateKeywords for Gradle and Maven, which will:
Parse the Grammar in order to find all Token definitions
Read the list of explicitly
Derive the list of
White-Listed Keywordsas difference between
Modifies the Grammar Productions
RelObjectNameWithoutValue...adding all Tokens according to
Run two special Unit Tests to verify parsing of all
White-Listed Keywords(as Schema, Table, Column, Function or Alias)
Update the web page about the Reserved Keywords
Without this Gradle Task, 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¶
git add -A
git commit -m <title> -m <description>
git push –set-upstream origin <new-branch>
Please consider using Conventional Commits and structure your commit message as follows:
<type>[optional scope]: <description>
[BREAKING CHANGE: <change_description>]
introduce a new feature
patches a bug in your codebase (bugfix or hotfix)
changes that affect the build system or external dependencies
updates dependencies and does not relate to fix or feat and does not modify src or test files.
changes that affect the continuous integration process
updates the documentation or introduce documentation
updates the formatting of code; remove white spaces, add missing spaces, remove unnecessary newlines
reactors code segments to optimize readability without changing behavior
reverts one or many previous commits
Please visit Better Programming for more information and guidance.