task: added pg-query and pg-query-ext

norberttech · norberttech · commit e7cb1f8710f8 · 2025-11-26T19:22:46.000+01:00
diff --git a/documentation/components/extensions/pg-query-ext.md b/documentation/components/extensions/pg-query-ext.md
@@ -0,0 +1,170 @@
+# PG Query Extension
+
+- [⬅️️ Back](/documentation/introduction.md)
+
+A compiled PHP extension for PostgreSQL query parsing using [libpg_query](https://github.com/pganalyze/libpg_query).
+
+This extension provides low-level functions for parsing PostgreSQL SQL queries. For a higher-level, object-oriented interface with strongly-typed AST nodes, see the [pg-query library](/documentation/components/libs/pg-query.md).
+
+## Features
+
+- Parse PostgreSQL SQL queries into JSON AST
+- Generate query fingerprints for query grouping
+- Normalize SQL queries (replace literals with placeholders)
+- Parse PL/pgSQL functions
+- Split multiple SQL statements
+- Scan SQL into tokens
+
+## Requirements
+
+- PHP 8.2+
+- C compiler (gcc/clang)
+- git (for auto-downloading libpg_query)
+- make
+- protobuf-c library
+
+## Installation
+
+### Using PIE (Recommended)
+
+[PIE](https://github.com/php/pie) is the modern PHP extension installer.
+
+```bash
+# Simple installation (auto-downloads libpg_query for PostgreSQL 17)
+pie install flow-php/pg-query-ext
+
+# Install with a specific PostgreSQL grammar version (15, 16, or 17)
+pie install flow-php/pg-query-ext --with-pg-version=16
+```
+
+The extension will automatically download and build the appropriate libpg_query version. Build dependencies (`protobuf-c`, `git`, `make`, `gcc`) must be available on your system.
+
+### Supported PostgreSQL Versions
+
+| PostgreSQL | libpg_query version |
+|------------|---------------------|
+| 17         | 17-6.1.0 (default)  |
+| 16         | 16-5.2.0            |
+| 15         | 15-4.2.4            |
+
+## Loading the Extension
+
+### In php.ini
+
+```ini
+extension=pg_query
+```
+
+### During Development
+
+```bash
+php -d extension=/path/to/pg_query.so your_script.php
+```
+
+## Usage
+
+```php
+<?php
+
+// Parse SQL and return JSON AST
+$json = pg_query_parse('SELECT * FROM users WHERE id = 1');
+$ast = json_decode($json, true);
+
+// Generate fingerprint (same for structurally equivalent queries)
+$fp = pg_query_fingerprint('SELECT * FROM users WHERE id = 1');
+// Returns same fingerprint for: SELECT * FROM users WHERE id = 2
+
+// Normalize query (replace literals with $N placeholders)
+$normalized = pg_query_normalize("SELECT * FROM users WHERE name = 'John'");
+// Returns: SELECT * FROM users WHERE name = $1
+
+// Split multiple statements
+$statements = pg_query_split('SELECT 1; SELECT 2; SELECT 3');
+// Returns: ['SELECT 1', ' SELECT 2', ' SELECT 3']
+
+// Parse PL/pgSQL function
+$plpgsql = pg_query_parse_plpgsql('
+    CREATE FUNCTION add(a int, b int) RETURNS int AS $$
+    BEGIN
+        RETURN a + b;
+    END;
+    $$ LANGUAGE plpgsql;
+');
+
+// Scan SQL into tokens (returns protobuf data)
+$protobuf = pg_query_scan('SELECT 1');
+```
+
+## Functions Reference
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `pg_query_parse(string $sql)` | Parse SQL to JSON AST | `string` (JSON) |
+| `pg_query_fingerprint(string $sql)` | Generate query fingerprint | `string\|false` |
+| `pg_query_normalize(string $sql)` | Normalize query with placeholders | `string\|false` |
+| `pg_query_parse_plpgsql(string $sql)` | Parse PL/pgSQL function | `string` (JSON) |
+| `pg_query_split(string $sql)` | Split multiple statements | `array<string>` |
+| `pg_query_scan(string $sql)` | Scan SQL into tokens | `string` (protobuf) |
+
+## Error Handling
+
+The extension throws `RuntimeException` on parse errors:
+
+```php
+<?php
+
+try {
+    $result = pg_query_parse('INVALID SQL SYNTAX');
+} catch (RuntimeException $e) {
+    echo "Parse error: " . $e->getMessage();
+}
+```
+
+## Development
+
+### Build Commands
+
+```bash
+# Build and run tests
+make test
+
+# Build only
+make build
+
+# Rebuild extension only (without rebuilding libpg_query)
+make rebuild
+
+# Clean build artifacts
+make clean
+
+# Remove everything including libpg_query
+make distclean
+```
+
+### Modifying the Extension
+
+When modifying the C source files:
+
+```bash
+# Inside nix-shell with --arg with-pg-query-ext true
+cd src/extension/pg-query-ext
+make rebuild
+
+# Test your changes
+make test
+```
+
+## Architecture
+
+The extension is built on top of [libpg_query](https://github.com/pganalyze/libpg_query), which extracts PostgreSQL's query parser into a standalone library. This means you get the exact same SQL parsing behavior as PostgreSQL itself.
+
+Key implementation details:
+- **Static linking**: libpg_query.a is statically linked into the extension
+- **Build dependency**: Requires `protobuf-c` library for compilation (libpg_query uses protobuf internally)
+- **Auto-download**: The build system automatically downloads the correct libpg_query version
+
+## See Also
+
+- [pg-query library](/documentation/components/libs/pg-query.md) - Higher-level PHP wrapper with strongly-typed AST nodes
+- [libpg_query](https://github.com/pganalyze/libpg_query) - The underlying C library
+- [Nix Development Environment](/documentation/contributing/nix.md) - Using nix-shell for development
diff --git a/documentation/components/libs/pg-query.md b/documentation/components/libs/pg-query.md
@@ -0,0 +1,216 @@
+# PG Query
+
+- [⬅️️ Back](/documentation/introduction.md)
+
+PostgreSQL Query Parser library provides strongly-typed AST (Abstract Syntax Tree) parsing for PostgreSQL SQL queries using the [libpg_query](https://github.com/pganalyze/libpg_query) library through a PHP extension.
+
+This library wraps the low-level extension functions and provides:
+- Strongly-typed AST nodes generated from protobuf definitions
+- A `Parser` class for object-oriented access
+- DSL helper functions for convenient usage
+
+## Requirements
+
+This library requires the `pg_query` PHP extension. See [pg-query-ext documentation](/documentation/components/extensions/pg-query-ext.md) for installation instructions.
+
+## Installation
+
+```
+composer require flow-php/pg-query:~--FLOW_PHP_VERSION--
+```
+
+## Usage
+
+### Using the Parser Class
+
+```php
+<?php
+
+use Flow\PgQuery\Parser;
+
+$parser = new Parser();
+
+// Parse SQL into AST
+$result = $parser->parse('SELECT id, name FROM users WHERE active = true');
+
+// Access the AST
+foreach ($result->getStmts() as $stmt) {
+    $node = $stmt->getStmt();
+    $selectStmt = $node->getSelectStmt();
+    // Work with strongly-typed AST nodes...
+}
+```
+
+### Using DSL Functions
+
+```php
+<?php
+
+use function Flow\PgQuery\DSL\pg_parse;
+use function Flow\PgQuery\DSL\pg_parser;
+use function Flow\PgQuery\DSL\pg_fingerprint;
+use function Flow\PgQuery\DSL\pg_normalize;
+use function Flow\PgQuery\DSL\pg_split;
+
+// Parse SQL
+$result = pg_parse('SELECT * FROM users');
+
+// Get a reusable parser instance
+$parser = pg_parser();
+
+// Generate fingerprint
+$fingerprint = pg_fingerprint('SELECT id FROM users WHERE id = 1');
+
+// Normalize query
+$normalized = pg_normalize('SELECT * FROM users WHERE id = 1');
+
+// Split multiple statements
+$statements = pg_split('SELECT 1; SELECT 2;');
+```
+
+## Features
+
+### Query Parsing
+
+Parse PostgreSQL SQL into a strongly-typed AST:
+
+```php
+<?php
+
+use Flow\PgQuery\Parser;
+
+$parser = new Parser();
+$result = $parser->parse('SELECT id, name FROM users WHERE active = true ORDER BY name');
+
+foreach ($result->getStmts() as $stmt) {
+    $selectStmt = $stmt->getStmt()->getSelectStmt();
+
+    // Access FROM clause
+    foreach ($selectStmt->getFromClause() as $fromItem) {
+        $rangeVar = $fromItem->getRangeVar();
+        echo "Table: " . $rangeVar->getRelname() . "\n";
+    }
+
+    // Access target list (SELECT columns)
+    foreach ($selectStmt->getTargetList() as $target) {
+        $columnRef = $target->getResTarget()->getVal()->getColumnRef();
+        // Process column references...
+    }
+}
+```
+
+### Query Fingerprinting
+
+Generate unique fingerprints for structurally equivalent queries. This is useful for grouping similar queries regardless of their literal values:
+
+```php
+<?php
+
+use Flow\PgQuery\Parser;
+
+$parser = new Parser();
+
+// These queries produce the same fingerprint
+$fp1 = $parser->fingerprint('SELECT * FROM users WHERE id = 1');
+$fp2 = $parser->fingerprint('SELECT * FROM users WHERE id = 999');
+
+var_dump($fp1 === $fp2); // true
+```
+
+### Query Normalization
+
+Replace literal values with parameter placeholders:
+
+```php
+<?php
+
+use Flow\PgQuery\Parser;
+
+$parser = new Parser();
+
+$normalized = $parser->normalize("SELECT * FROM users WHERE name = 'John' AND age = 25");
+// Returns: SELECT * FROM users WHERE name = $1 AND age = $2
+```
+
+### Statement Splitting
+
+Split a string containing multiple SQL statements:
+
+```php
+<?php
+
+use Flow\PgQuery\Parser;
+
+$parser = new Parser();
+
+$statements = $parser->split('SELECT 1; SELECT 2; SELECT 3');
+// Returns: ['SELECT 1', ' SELECT 2', ' SELECT 3']
+```
+
+## API Reference
+
+### Parser Class
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `parse(string $sql)` | Parse SQL into AST | `ParseResult` |
+| `fingerprint(string $sql)` | Generate query fingerprint | `?string` |
+| `normalize(string $sql)` | Normalize query with placeholders | `?string` |
+| `split(string $sql)` | Split multiple statements | `array<string>` |
+
+### DSL Functions
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `pg_parser()` | Create a new Parser instance | `Parser` |
+| `pg_parse(string $sql)` | Parse SQL into AST | `ParseResult` |
+| `pg_fingerprint(string $sql)` | Generate query fingerprint | `?string` |
+| `pg_normalize(string $sql)` | Normalize query | `?string` |
+| `pg_split(string $sql)` | Split statements | `array<string>` |
+
+## AST Node Types
+
+The library includes 343 strongly-typed AST node classes generated from PostgreSQL's protobuf definitions. All classes are in the `Flow\PgQuery\Protobuf\AST` namespace.
+
+Common node types include:
+- `SelectStmt` - SELECT statement
+- `InsertStmt` - INSERT statement
+- `UpdateStmt` - UPDATE statement
+- `DeleteStmt` - DELETE statement
+- `ColumnRef` - Column reference
+- `A_Expr` - Expression node
+- `FuncCall` - Function call
+- `JoinExpr` - JOIN expression
+- `RangeVar` - Table/view reference
+
+## Exception Handling
+
+```php
+<?php
+
+use Flow\PgQuery\Parser;
+use Flow\PgQuery\Exception\ParserException;
+use Flow\PgQuery\Exception\ExtensionNotLoadedException;
+
+try {
+    $parser = new Parser();
+} catch (ExtensionNotLoadedException $e) {
+    // pg_query extension is not loaded
+}
+
+try {
+    $result = $parser->parse('INVALID SQL SYNTAX HERE');
+} catch (ParserException $e) {
+    echo "Parse error: " . $e->getMessage();
+}
+```
+
+## Performance
+
+For optimal protobuf parsing performance, install the `ext-protobuf` PHP extension:
+
+```bash
+pecl install protobuf
+```
+
+The library will work without it using the pure PHP implementation from `google/protobuf`, but the native extension provides significantly better performance for AST deserialization.
diff --git a/web/landing/templates/documentation/navigation_right.html.twig b/web/landing/templates/documentation/navigation_right.html.twig
