Skip to content

Quick Start

Get up and running with General SQL Parser in just a few minutes! This guide will walk you through installation, basic setup, and your first SQL parsing example.

Prerequisites

  • Java 8 or higher (Java 11+ recommended)
  • Maven or Gradle for dependency management
  • IDE (IntelliJ IDEA, Eclipse, or VS Code recommended)

Installation

General SQL Parser is published to Gudu Software's public Maven repository at https://www.sqlparser.com/maven/. Add the repository and a single dependency to your build — nothing to download, install, or configure locally.

The public Maven artifact is the trial build

The artifact at com.gudusoft:gsqlparser is the trial edition of General SQL Parser. It is fully functional for evaluation and covers every example on this page. Commercial builds may carry newer fixes and use a more specific four-part version. See the licensing FAQ before production use. The public Maven version is a three-part number (for example 4.1.6) and does not necessarily match the four-part product version shown in the release notes.

Maven

A complete, minimal pom.xml — copy it into an empty directory and it builds on Java 8 through the latest LTS:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>gsp-quickstart</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <properties>
        <!-- The parser JAR is Java 8 bytecode. Pin the compiler level so a
             modern JDK does not fall back to an unsupported default. -->
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <repositories>
        <repository>
            <id>gudu-public-releases</id>
            <url>https://www.sqlparser.com/maven/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>com.gudusoft</groupId>
            <artifactId>gsqlparser</artifactId>
            <version>4.1.6</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.1.1</version>
                <configuration>
                    <mainClass>QuickStartExample</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Create your class at src/main/java/QuickStartExample.java (see Your First SQL Parser below), then compile and run in one step:

1
mvn clean compile exec:java

That's it — Maven downloads gsqlparser-4.1.6.jar from https://www.sqlparser.com/maven/com/gudusoft/gsqlparser/4.1.6/ into your local ~/.m2/ cache on first build.

Data lineage on Java 11+

The DataFlowAnalyzer (data-lineage) APIs generate XML through JAXB, which was removed from the JDK in Java 11. As of 4.1.6 the published POM declares the JAXB runtime, so lineage works on Java 11+ with only the GSP dependency — no extra setup. On Java 8 the JDK-bundled JAXB is used.

Gradle

A complete build.gradle.kts (Kotlin DSL). The application plugin supplies the implementation configuration and a run task:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
plugins {
    application
}

repositories {
    // Gradle has no built-in repositories: mavenCentral() is required so
    // GSP's transitive JAXB dependencies resolve (they live on Maven Central,
    // not the Gudu repository).
    mavenCentral()
    maven { url = uri("https://www.sqlparser.com/maven/") }
}

dependencies {
    implementation("com.gudusoft:gsqlparser:4.1.6")
}

java {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
}

tasks.withType<JavaCompile>().configureEach {
    options.encoding = "UTF-8"
}

application {
    mainClass.set("QuickStartExample")
}

Create your class at src/main/java/QuickStartExample.java (see Your First SQL Parser below), then build and run with the installed Gradle (listed in the prerequisites):

1
gradle clean run

Using the Gradle wrapper

An empty project has no gradlew wrapper script yet. Generate one first with gradle wrapper, after which you can use ./gradlew clean run (gradlew.bat clean run on Windows) for a version-pinned, reproducible build.

Latest version

The current release is 4.1.6. You can always check the latest version by viewing maven-metadata.xml. Maven coordinates are write-once — once a version is published it never changes, so it's safe to pin any specific release.

Running your program

The complete pom.xml above already includes the exec-maven-plugin, so once you've created QuickStartExample.java you can compile and run in one command:

1
mvn clean compile exec:java

To run a different class, change the plugin's <mainClass> (or override it on the command line with -Dexec.mainClass=YourClass).

Offline / air-gapped installs

If your build environment cannot reach the internet, you must transfer the complete dependency closure — not just the GSP JAR. Since 4.1.6 declares JAXB (which lives on Maven Central), installing only the GSP JAR and POM is not enough: Maven would still try to fetch jakarta.xml.bind-api, jaxb-runtime, and the build/exec plugins from a remote repository.

The reliable approach is to build a portable local repository on a connected machine and transfer it whole. Prime it by running the actual build commands once — this captures the exact plugin + dependency closure the build uses. (dependency:go-offline is not sufficient here: it misses some default-lifecycle plugin dependencies and the build still fails offline.)

On a machine with internet access — using the complete pom.xml and QuickStartExample.java from the sections above:

1
2
3
4
5
# Prime a self-contained repo by running the real build once
mvn -Dmaven.repo.local="$PWD/offline-m2" clean compile exec:java

# Confirm it is truly self-contained by re-running with networking off (-o)
mvn -o -Dmaven.repo.local="$PWD/offline-m2" clean compile exec:java

Transfer the project directory and the offline-m2/ folder to the air-gapped host, then run the same offline command there:

1
mvn -o -Dmaven.repo.local="$PWD/offline-m2" clean compile exec:java

Verifying artifact integrity

The published JAR checksum can be checked against the download: 

1
2
BASE=https://www.sqlparser.com/maven/com/gudusoft/gsqlparser/4.1.6
echo "$(curl -s $BASE/gsqlparser-4.1.6.jar.sha1)  gsqlparser-4.1.6.jar" | sha1sum -c -

Your First SQL Parser

Let's create a simple example that parses a SQL statement:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import gudusoft.gsqlparser.TGSqlParser;
import gudusoft.gsqlparser.EDbVendor;

public class QuickStartExample {
    public static void main(String[] args) {
        // Create a parser instance for Oracle SQL
        TGSqlParser sqlparser = new TGSqlParser(EDbVendor.dbvoracle);

        // Set the SQL text to parse
        sqlparser.sqltext = "SELECT employee_id, first_name, last_name " +
                           "FROM employees " +
                           "WHERE department_id = 10 " +
                           "ORDER BY last_name";

        // Parse the SQL
        int result = sqlparser.parse();

        if (result == 0) {
            System.out.println("✅ SQL parsed successfully!");

            // Get basic information about the parsed SQL
            System.out.println("SQL Type: " + sqlparser.sqlstatements.get(0).sqlstatementtype);
            System.out.println("Number of statements: " + sqlparser.sqlstatements.size());

        } else {
            System.out.println("❌ Parse failed!");
            System.out.println("Error: " + sqlparser.getErrormessage());
        }
    }
}

Expected Output

1
2
3
✅ SQL parsed successfully!
SQL Type: sstselect
Number of statements: 1

Database Vendor Support

General SQL Parser supports 30+ database vendors. Here are some common examples:

1
2
TGSqlParser parser = new TGSqlParser(EDbVendor.dbvoracle);
parser.sqltext = "SELECT * FROM dual WHERE ROWNUM = 1";

1
2
TGSqlParser parser = new TGSqlParser(EDbVendor.dbvmssql);
parser.sqltext = "SELECT TOP 10 * FROM employees";

1
2
TGSqlParser parser = new TGSqlParser(EDbVendor.dbvpostgresql);
parser.sqltext = "SELECT * FROM employees LIMIT 10";

1
2
TGSqlParser parser = new TGSqlParser(EDbVendor.dbvmysql);
parser.sqltext = "SELECT * FROM employees LIMIT 10";

1
2
TGSqlParser parser = new TGSqlParser(EDbVendor.dbvbigquery);
parser.sqltext = "SELECT * FROM `project.dataset.table` LIMIT 10";

Common Use Cases

1. SQL Syntax Validation

parse() == 0 confirms the SQL is syntactically valid for the selected dialect. It does not check that the referenced tables/columns exist, that types are compatible, or that the statement would execute — catalog-aware validation requires metadata and the resolver APIs.

1
2
3
4
5
public boolean isSyntacticallyValidSQL(String sql, EDbVendor vendor) {
    TGSqlParser parser = new TGSqlParser(vendor);
    parser.sqltext = sql;
    return parser.parse() == 0;
}

2. Extract Table Names

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import gudusoft.gsqlparser.stmt.TSelectSqlStatement;
import gudusoft.gsqlparser.nodes.TTable;

public void extractTables(String sql) {
    TGSqlParser parser = new TGSqlParser(EDbVendor.dbvoracle);
    parser.sqltext = sql;

    if (parser.parse() == 0
            && parser.sqlstatements.get(0) instanceof TSelectSqlStatement) {
        TSelectSqlStatement select = (TSelectSqlStatement) parser.sqlstatements.get(0);

        for (int i = 0; i < select.tables.size(); i++) {
            TTable table = select.tables.getTable(i);
            System.out.println("Table: " + table.getTableName());
        }
    }
}

3. Format SQL

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.TGSqlParser;

import gudusoft.gsqlparser.pp.para.GFmtOptFactory;
import gudusoft.gsqlparser.pp.para.GFmtOpt;
import gudusoft.gsqlparser.pp.stmtformatter.FormatterFactory;


public class formatsql {

    public static void main(String args[])
     {

        TGSqlParser sqlparser = new TGSqlParser(EDbVendor.dbvpostgresql);

        sqlparser.sqltext ="WITH upd AS (\n" +
                "  UPDATE employees SET sales_count = sales_count + 1 WHERE id =\n" +
                "    (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation')\n" +
                "    RETURNING *\n" +
                ")\n" +
                "INSERT INTO employees_log SELECT *, current_timestamp FROM upd;";



        int ret = sqlparser.parse();
        if (ret == 0){
            GFmtOpt option = GFmtOptFactory.newInstance();
            String result = FormatterFactory.pp(sqlparser, option);
            System.out.println(result);
        }else{
            System.out.println(sqlparser.getErrormessage());
        }
     }
}

Error Handling

Always handle parsing errors gracefully:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import gudusoft.gsqlparser.TGSqlParser;
import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.TSyntaxError;

public class QuickStartExample {
    public static void main(String[] args) {
        TGSqlParser parser = new TGSqlParser(EDbVendor.dbvoracle);
        parser.sqltext = "SELECT * FROM"; // Invalid SQL

        int result = parser.parse();
        if (result != 0) {
            System.err.println("Parse Error:");
            System.err.println("Message: " + parser.getErrormessage());
            for(TSyntaxError error : parser.getSyntaxErrors()) {
                System.err.println("Line: " + error.lineNo);
                System.err.println("Column: " + error.columnNo);
                System.err.println("Token: " + error.tokentext);
                System.err.println("Error type: " + error.errortype);
            }
        }
    }
}

Next Steps

Now that you have General SQL Parser running, explore these areas:

Continue Learning

Troubleshooting

Common Issues

Parse Error: Unexpected token

Solution: Check that you're using the correct database vendor. SQL syntax varies between databases.

1
2
3
4
5
6
7
// Wrong
TGSqlParser parser = new TGSqlParser(EDbVendor.dbvoracle);
parser.sqltext = "SELECT TOP 10 * FROM table"; // SQL Server syntax

// Correct
TGSqlParser parser = new TGSqlParser(EDbVendor.dbvmssql);
parser.sqltext = "SELECT TOP 10 * FROM table";

ClassNotFoundException

Solution: Ensure the GSQLParser JAR is in your classpath and all dependencies are included.

OutOfMemoryError

Solution: For large SQL files, consider parsing statements individually or increase JVM heap size.

Getting Help

  • 📖 Check our FAQ for common questions
  • 💬 Visit our Support page for community help
  • 📧 Contact technical support for commercial licenses

Ready for more advanced features? Continue with our comprehensive tutorials or explore specific how-to guides.