Skip to content

Quick Start

Get up and running with General SQL Parser .NET in just a few minutes. This guide walks you through installation, your first parse, and the most common use cases.

Prerequisites

  • .NET 10 SDK (the recommended target — LTS, supported through 2028-11). Older runtimes work via the netstandard2.0 facade: .NET Framework 4.6.1+, Mono, Unity, etc.
  • A C# IDE (Rider, Visual Studio, or VS Code with the C# Dev Kit).
  • On Ubuntu 24.04: sudo apt-get install -y dotnet-sdk-10.0 (built into the Ubuntu apt feed; no Microsoft repo required). Verify with dotnet --info.

Installation

The library is published to NuGet as gudusoft.gsqlparser.

1
dotnet add package gudusoft.gsqlparser

1
2
3
<ItemGroup>
  <PackageReference Include="gudusoft.gsqlparser" Version="3.5.1.0" />
</ItemGroup>

1
Install-Package gudusoft.gsqlparser

The published NuGet ships with all 15 dialects baked in (DB2, Greenplum, Hive, Impala, Informix, MDX, MSSQL, MySQL, Netezza, Oracle, PostgreSQL, Redshift, Snowflake, Sybase, Teradata). If you build the library from source you can omit dialects with /p:includeXxx=true flags.

Trial vs full edition

The published NuGet is the full edition. The free trial (with a banner watermark in the output) is available as a separate ZIP from https://www.sqlparser.com/download.php; install with dotnet add package gudusoft.gsqlparser.trial once Gudu Software publishes the trial NuGet, or add the DLL via <Reference> for now.

Your first SQL parse

Create a new console project and add the package:

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

Replace Program.cs with:

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

var parser = new TGSqlParser(EDbVendor.dbvoracle);
parser.sqltext = """
    SELECT employee_id, first_name, last_name
    FROM   employees
    WHERE  department_id = 10
    ORDER  BY last_name
""";

int result = parser.parse();
if (result == 0)
{
    Console.WriteLine("Parsed successfully.");
    Console.WriteLine($"Statement type:       {parser.sqlstatements.get(0).sqlstatementtype}");
    Console.WriteLine($"Number of statements: {parser.sqlstatements.size()}");
}
else
{
    Console.WriteLine("Parse failed.");
    Console.WriteLine(parser.Errormessage);
}

Then dotnet run:

1
2
3
Parsed successfully.
Statement type:       sstselect
Number of statements: 1

Database vendor selection

Pick the matching EDbVendor constant when you construct the parser:

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

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

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

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

1
2
var parser = new TGSqlParser(EDbVendor.dbvsnowflake);
parser.sqltext = "SELECT * FROM orders QUALIFY ROW_NUMBER() OVER (ORDER BY id) = 1";

The full list of supported EDbVendor constants: dbvdb2, dbvgreenplum, dbvhive, dbvimpala, dbvinformix, dbvmdx, dbvmssql (alias dbvaccess), dbvmysql, dbvnetezza, dbvoracle, dbvpostgresql, dbvredshift, dbvsnowflake, dbvsybase, dbvteradata.

Common use cases

1. Validate SQL

1
2
3
4
5
public static bool IsValidSql(string sql, EDbVendor vendor)
{
    var parser = new TGSqlParser(vendor) { 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
18
19
20
using gudusoft.gsqlparser;
using gudusoft.gsqlparser.nodes;
using gudusoft.gsqlparser.stmt;

public static void ExtractTables(string sql)
{
    var parser = new TGSqlParser(EDbVendor.dbvoracle) { sqltext = sql };
    if (parser.parse() != 0)
    {
        Console.Error.WriteLine(parser.Errormessage);
        return;
    }

    var select = (TSelectSqlStatement)parser.sqlstatements.get(0);
    for (int i = 0; i < select.tables.size(); i++)
    {
        TTable table = select.tables.getTable(i);
        Console.WriteLine($"Table: {table.TableName}");
    }
}

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

var parser = new TGSqlParser(EDbVendor.dbvpostgresql);
parser.sqltext = """
    WITH upd AS (
      UPDATE employees SET sales_count = sales_count + 1 WHERE id =
        (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation')
        RETURNING *
    )
    INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
    """;

if (parser.parse() == 0)
{
    GFmtOpt option = GFmtOptFactory.newInstance();
    string formatted = FormatterFactory.pp(parser, option);
    Console.WriteLine(formatted);
}
else
{
    Console.WriteLine(parser.Errormessage);
}

The formatter is the same engine used by the formatsql demo (under gsp_demo_dotnet/src/demos/) — see that project for a full CLI implementation.

For step-by-step recipes — uppercase vs lowercase keywords, comma-first style, indent width, file round-tripping, multi-statement scripts, and a full reference of the GFmtOpt settings — see the dedicated Format (Pretty-print) SQL how-to.

Error handling

parse() returns 0 on success and non-zero on failure. Detailed errors live on Errormessage (a single string) and SyntaxErrors (a list with line/column information).

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

var parser = new TGSqlParser(EDbVendor.dbvoracle);
parser.sqltext = "SELECT * FROM"; // intentionally malformed

int result = parser.parse();
if (result != 0)
{
    Console.Error.WriteLine("Parse error:");
    Console.Error.WriteLine($"  {parser.Errormessage}");
    foreach (TSyntaxError error in parser.SyntaxErrors)
    {
        Console.Error.WriteLine(
            $"  line {error.lineNo}, col {error.columnNo}: " +
            $"{error.tokentext} ({error.errortype})");
    }
}

Next steps

Now that you have GSP running, explore further:

Continue learning

Troubleshooting

Parse error: unexpected token

Solution: Check that you're using the right EDbVendor. SQL syntax varies between vendors.

1
2
3
4
5
6
7
// Wrong — Oracle parser doesn't accept SQL Server's TOP
var parser = new TGSqlParser(EDbVendor.dbvoracle);
parser.sqltext = "SELECT TOP 10 * FROM t";

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

TypeLoadException / FileNotFoundException at runtime

Solution: Make sure your project's TFM is one of net10.0, net8.0+, net6.0+, netstandard2.0-consuming, or net461+. If you're targeting net5.0 or older netcoreapp*, upgrade — those runtimes are EOL.

OutOfMemoryException on large scripts

Solution: Parse statement-by-statement instead of loading a multi-megabyte file as one string. See the performance optimization guide.

Getting help

Ready for more? Continue with the comprehensive tutorials or jump into a how-to guide.