Skip to content

Getting Started with GSP

Welcome to your first tutorial on General SQL Parser .NET! This guide takes you from zero to parsing your first SQL statement in about 30 minutes.

Objectives

By the end of this tutorial you will:

  • Understand what General SQL Parser is and how it works
  • Set up GSP in a .NET console project
  • Parse your first SQL statement
  • Understand the parse result and AST structure
  • Handle basic parse errors
  • Know the core terminology

Prerequisites

  • .NET 10 SDK installed (dotnet --info should show 10.0.x). On Ubuntu 24.04: sudo apt-get install -y dotnet-sdk-10.0.
  • An IDE with C# support (Rider, Visual Studio, or VS Code with the C# Dev Kit)
  • Basic understanding of SQL syntax
  • Familiarity with C# / .NET

Time required

About 30 minutes.

Setup

Step 1: Create a new console project

1
2
3
dotnet new console -o GspTutorial
cd GspTutorial
dotnet add package gudusoft.gsqlparser

This produces a GspTutorial.csproj with shape similar to:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="gudusoft.gsqlparser" Version="3.5.1.0" />
  </ItemGroup>
</Project>

Step 2: Verify the install

Replace Program.cs with:

1
2
3
4
5
6
using gudusoft.gsqlparser;

Console.WriteLine("Testing General SQL Parser...");
var parser = new TGSqlParser(EDbVendor.dbvoracle);
Console.WriteLine("Parser created successfully.");
Console.WriteLine($"Database vendor: {parser.DbVendor}");

Run it:

1
dotnet run

You should see:

1
2
3
Testing General SQL Parser...
Parser created successfully.
Database vendor: dbvoracle

Step-by-step guide

Step 3: Understanding core concepts

Before we parse anything, here are the key concepts:

Core concepts

TGSqlParser — the main parser class that processes SQL text.

EDbVendor — the enum specifying the dialect (Oracle, SQL Server, etc.).

AST (Abstract Syntax Tree) — the structured representation of parsed SQL.

SQL statements — individual SQL commands (SELECT, INSERT, ...).

Parse result — int return code: 0 = success, non-zero = error.

Step 4: Your first parse

Let's parse a simple SELECT:

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

// Step 1: create parser for Oracle SQL
var parser = new TGSqlParser(EDbVendor.dbvoracle);

// Step 2: set the SQL text
parser.sqltext = "SELECT employee_id, first_name, last_name FROM employees";

// Step 3: parse
int result = parser.parse();

// Step 4: check the result
if (result == 0)
{
    Console.WriteLine("Parse successful.");
    Console.WriteLine($"Number of statements: {parser.sqlstatements.size()}");
    Console.WriteLine($"Statement type:       {parser.sqlstatements.get(0).sqlstatementtype}");
}
else
{
    Console.WriteLine("Parse failed.");
    Console.WriteLine(parser.Errormessage);
}

Expected output:

1
2
3
Parse successful.
Number of statements: 1
Statement type:       sstselect

Step 5: Exploring the AST

Now let's see what we can extract from the parsed 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
35
36
37
38
39
40
using gudusoft.gsqlparser;
using gudusoft.gsqlparser.nodes;
using gudusoft.gsqlparser.stmt;

var parser = new TGSqlParser(EDbVendor.dbvoracle);
parser.sqltext = """
    SELECT emp.employee_id, emp.first_name, dept.department_name
    FROM   employees emp
    JOIN   departments dept ON emp.department_id = dept.department_id
    WHERE  emp.salary > 50000
    """;

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

    Console.WriteLine("Tables used:");
    for (int i = 0; i < select.tables.size(); i++)
    {
        TTable table = select.tables.getTable(i);
        string aliasInfo = table.AliasClause != null
            ? $" (alias: {table.AliasClause})"
            : "";
        Console.WriteLine($"  - {table.TableName}{aliasInfo}");
    }

    Console.WriteLine();
    Console.WriteLine("Columns selected:");
    for (int i = 0; i < select.ResultColumnList.size(); i++)
    {
        Console.WriteLine($"  - {select.ResultColumnList.getResultColumn(i)}");
    }

    if (select.WhereClause != null)
    {
        Console.WriteLine();
        Console.WriteLine("WHERE condition:");
        Console.WriteLine($"  {select.WhereClause}");
    }
}

Expected output (formatting may vary):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Tables used:
  - employees (alias: emp)
  - departments (alias: dept)

Columns selected:
  - emp.employee_id
  - emp.first_name
  - dept.department_name

WHERE condition:
  emp.salary > 50000

Step 6: Handling different database vendors

GSP .NET supports 15 dialects out of the box. Let's see how to switch between them:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
using gudusoft.gsqlparser;

TestSql(EDbVendor.dbvoracle,     "SELECT * FROM dual WHERE ROWNUM = 1");
TestSql(EDbVendor.dbvmssql,      "SELECT TOP 10 * FROM employees");
TestSql(EDbVendor.dbvpostgresql, "SELECT * FROM employees LIMIT 10 OFFSET 5");
TestSql(EDbVendor.dbvmysql,      "SELECT * FROM employees LIMIT 5, 10");
TestSql(EDbVendor.dbvsnowflake,  "SELECT * FROM t QUALIFY ROW_NUMBER() OVER (ORDER BY id) = 1");

static void TestSql(EDbVendor vendor, string sql)
{
    var parser = new TGSqlParser(vendor) { sqltext = sql };
    int result = parser.parse();
    string status = result == 0 ? "OK" : $"ERR: {parser.Errormessage.Trim()}";
    Console.WriteLine($"[{vendor,-20}] {status}");
}

Step 7: Error handling

Let's learn how to handle parse errors properly:

 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
using gudusoft.gsqlparser;

// 1. Invalid SQL
{
    var parser = new TGSqlParser(EDbVendor.dbvoracle);
    parser.sqltext = "SELECT * FROM"; // missing table name

    if (parser.parse() != 0)
    {
        Console.WriteLine("Parse failed (expected):");
        Console.WriteLine($"  {parser.Errormessage.Trim()}");
    }
}

// 2. Wrong vendor
{
    var parser = new TGSqlParser(EDbVendor.dbvoracle);
    parser.sqltext = "SELECT TOP 10 * FROM employees"; // SQL Server syntax

    if (parser.parse() != 0)
    {
        Console.WriteLine("Parse failed — wrong vendor.");
        Console.WriteLine("Tip: use EDbVendor.dbvmssql for T-SQL.");
    }
}

Practice exercises

Exercise 1: parse different statement types

Parse these and identify their sqlstatementtype:

1
2
3
4
INSERT INTO employees (id, name) VALUES (1, 'John');
UPDATE employees SET salary = 60000 WHERE id = 1;
DELETE FROM employees WHERE id = 1;
CREATE TABLE test (id INT, name VARCHAR(50));

Exercise 2: extract information

For this query, extract all table names, column names, and join conditions:

1
2
3
4
5
6
SELECT e.employee_id, e.first_name, d.department_name, l.city
FROM   employees e
JOIN   departments d ON e.department_id = d.department_id
JOIN   locations l   ON d.location_id    = l.location_id
WHERE  e.hire_date > DATE '2020-01-01'
ORDER  BY e.last_name;

Exercise 3: vendor auto-detect

Write a method that tries each EDbVendor until one parses cleanly:

1
public static EDbVendor? DetectVendor(string sql) { /* ... */ }

Summary

Congratulations — you've completed your first GSP tutorial. Recap:

  • How to add the gudusoft.gsqlparser NuGet package
  • Core concepts: TGSqlParser, EDbVendor, AST
  • How to parse SQL and check the result
  • How to extract information from the AST
  • How to handle different vendors
  • How to handle parse errors gracefully

Key takeaways

  1. Always check the parse result — 0 means success, non-zero means error.
  2. Pick the right vendor — SQL syntax varies between databases.
  3. Handle errors gracefully — surface meaningful error messages.
  4. Explore the AST — rich structured information is available.

What's next?

Ready for the next challenge? Continue with Basic SQL Parsing.