From 186d52c1165ca247d890e06c5c8d15bdae2cb883 Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Mon, 12 Oct 2026 21:13:26 +0000 Subject: [PATCH] docs: drop stale Experimental banners, recommend PG18 --- packages/deparser/README.md | 14 ++++--- packages/plpgsql-deparser/README.md | 2 +- packages/plpgsql-parser/README.md | 2 +- packages/transform-ast/README.md | 41 ++++++++++--------- .../src/transformers-direct/README.md | 33 ++++++++------- 5 files changed, 50 insertions(+), 42 deletions(-) diff --git a/packages/deparser/README.md b/packages/deparser/README.md index 2ba6faee2..1b05f3a15 100644 --- a/packages/deparser/README.md +++ b/packages/deparser/README.md @@ -69,27 +69,29 @@ console.log(deparse(stmt)); // Output: SELECT * FROM another_table ``` -### Latest Version (PostgreSQL 17) +### Latest Version (PostgreSQL 18) ```sh npm install pgsql-deparser ``` -### Version-Specific Packages (PostgreSQL 13-16) +### Version-Specific Packages (PostgreSQL 13-17) -While we highly recommend using PG17, for PostgreSQL versions 13-16, use the version-specific packages: +We recommend PG18. PG17 remains fully supported; for PostgreSQL versions 13-17, use the version-specific packages: ```sh npm install pgsql-deparser@pg13 # PostgreSQL 13 npm install pgsql-deparser@pg14 # PostgreSQL 14 npm install pgsql-deparser@pg15 # PostgreSQL 15 npm install pgsql-deparser@pg16 # PostgreSQL 16 +npm install pgsql-deparser@pg17 # PostgreSQL 17 ``` **Version Status:** -- **PG17**: 🚀 Recommended (stable + modern AST) -- **PG14-16**: ⚠ Experimental (modern AST, hardening in progress) -- **PG13**: Stable (legacy AST format) +- **PG18**: 🚀 Recommended (stable + modern AST) +- **PG17**: Stable (modern AST) +- **PG14-16**: Legacy (modern AST, not actively developed) +- **PG13**: Legacy (legacy AST format) ## Options diff --git a/packages/plpgsql-deparser/README.md b/packages/plpgsql-deparser/README.md index 0c81235f0..54f5a7c4b 100644 --- a/packages/plpgsql-deparser/README.md +++ b/packages/plpgsql-deparser/README.md @@ -14,7 +14,7 @@ PL/pgSQL AST Deparser - Converts PL/pgSQL function ASTs back to SQL strings. -> **⚠ Experimental:** This package is currently experimental. If you're looking for SQL deparsing (not PL/pgSQL), see [`pgsql-deparser`](https://www.npmjs.com/package/pgsql-deparser). +> **Looking for SQL deparsing (not PL/pgSQL)?** See [`pgsql-deparser`](https://www.npmjs.com/package/pgsql-deparser). > **For full SQL + PL/pgSQL deparsing:** If you need to deparse complete `CREATE FUNCTION` statements (not just function bodies), use [`plpgsql-parser`](https://www.npmjs.com/package/plpgsql-parser) instead. It handles the full heterogeneous parsing/deparsing pipeline automatically. diff --git a/packages/plpgsql-parser/README.md b/packages/plpgsql-parser/README.md index 92bf91779..fc6410bfc 100644 --- a/packages/plpgsql-parser/README.md +++ b/packages/plpgsql-parser/README.md @@ -14,7 +14,7 @@ Combined SQL + PL/pgSQL parser with hydrated ASTs and transform API. -> **⚠ Experimental:** This package is currently experimental. If you're looking for just SQL parsing, see [`pgsql-parser`](https://www.npmjs.com/package/pgsql-parser). For body-only PL/pgSQL deparsing, see [`plpgsql-deparser`](https://www.npmjs.com/package/plpgsql-deparser). +> **Related packages:** For SQL-only parsing, see [`pgsql-parser`](https://www.npmjs.com/package/pgsql-parser). For body-only PL/pgSQL deparsing, see [`plpgsql-deparser`](https://www.npmjs.com/package/plpgsql-deparser). ## Overview diff --git a/packages/transform-ast/README.md b/packages/transform-ast/README.md index 134617812..3a56a686b 100644 --- a/packages/transform-ast/README.md +++ b/packages/transform-ast/README.md @@ -18,17 +18,17 @@ The transform package enables you to: -- **Transform legacy ASTs**: Convert ASTs from PostgreSQL versions 13-16 to version 17 +- **Transform legacy ASTs**: Convert ASTs from PostgreSQL versions 13-17 to version 18 (or 13-16 to 17) - **Build unified deparsers**: Create a single deparser pipeline that works with multiple PostgreSQL versions - **Maintain backward compatibility**: Support legacy codebases while leveraging the latest PostgreSQL features ## Key Limitation -This package only supports ASTs derived from SQL that is parseable by PostgreSQL 17. This means: +This package only supports ASTs derived from SQL that is parseable by the target version's parser (PostgreSQL 18 for the latest). This means: -- ✅ **Supported**: SQL from PG13-16 that remains valid in PG17 +- ✅ **Supported**: SQL from PG13-17 that remains valid in PG18 - ❌ **Not supported**: Deprecated syntax from older versions that was removed -- ❌ **Not supported**: SQL that cannot be parsed by the PG17 parser +- ❌ **Not supported**: SQL that cannot be parsed by the PG18 parser This design ensures all transformed ASTs can be reliably deparsed using the latest PostgreSQL grammar. @@ -47,14 +47,14 @@ import { ASTTransformer } from '@pgsql/transform-ast'; const transformer = new ASTTransformer(); -// Transform any version to PG17 -const pg17Ast = transformer.transformToLatest(pg13Ast, 13); +// Transform any version to the latest (PG18) +const pg18Ast = transformer.transformToLatest(pg13Ast, 13); // Transform between specific versions const pg15Ast = transformer.transform(pg13Ast, 13, 15); // Convenience methods -const result = transformer.transform13To17(pg13Ast); +const result = transformer.transform13To18(pg13Ast); ``` ### Direct Transformers @@ -62,10 +62,10 @@ const result = transformer.transform13To17(pg13Ast); For better performance when you know source and target versions: ```typescript -import { PG13ToPG17Transformer } from '@pgsql/transform-ast'; +import { PG13ToPG18Transformer } from '@pgsql/transform-ast'; -const transformer = new PG13ToPG17Transformer(); -const pg17Ast = transformer.transform(pg13Ast); +const transformer = new PG13ToPG18Transformer(); +const pg18Ast = transformer.transform(pg13Ast); ``` ### Integration Example @@ -73,26 +73,26 @@ const pg17Ast = transformer.transform(pg13Ast); ```typescript import { parse } from '@pgsql/parser'; import { deparse } from 'pgsql-deparser'; -import { PG13ToPG17Transformer } from '@pgsql/transform-ast'; +import { PG13ToPG18Transformer } from '@pgsql/transform-ast'; // Parse with older version const pg13Ast = await parse('SELECT * FROM users', { version: 13 }); // Transform to latest -const transformer = new PG13ToPG17Transformer(); -const pg17Ast = transformer.transform(pg13Ast); +const transformer = new PG13ToPG18Transformer(); +const pg18Ast = transformer.transform(pg13Ast); // Deparse with latest grammar -const sql = await deparse(pg17Ast); +const sql = await deparse(pg18Ast); ``` ## 🔄 Transformation Chain -**Incremental**: PG13 → PG14 → PG15 → PG16 → PG17 +**Incremental**: PG13 → PG14 → PG15 → PG16 → PG17 → PG18 - Step-by-step version upgrades - Useful for debugging transformation issues -**Direct**: PG13 → PG17, PG14 → PG17, etc. +**Direct**: PG13 → PG18, PG14 → PG18, etc. (PG17 targets also available) - Single-step transformations - Optimized for performance @@ -100,10 +100,11 @@ const sql = await deparse(pg17Ast); | From | To | Transformer | |------|----|-----------| -| PG13 | PG14, PG15, PG16, PG17 | `V13ToV14Transformer`, `PG13ToPG17Transformer` | -| PG14 | PG15, PG16, PG17 | `V14ToV15Transformer`, `PG14ToPG17Transformer` | -| PG15 | PG16, PG17 | `V15ToV16Transformer`, `PG15ToPG17Transformer` | -| PG16 | PG17 | `V16ToV17Transformer`, `PG16ToPG17Transformer` | +| PG13 | PG14, PG15, PG16, PG17, PG18 | `V13ToV14Transformer`, `PG13ToPG17Transformer`, `PG13ToPG18Transformer` | +| PG14 | PG15, PG16, PG17, PG18 | `V14ToV15Transformer`, `PG14ToPG17Transformer`, `PG14ToPG18Transformer` | +| PG15 | PG16, PG17, PG18 | `V15ToV16Transformer`, `PG15ToPG17Transformer`, `PG15ToPG18Transformer` | +| PG16 | PG17, PG18 | `V16ToV17Transformer`, `PG16ToPG17Transformer`, `PG16ToPG18Transformer` | +| PG17 | PG18 | `V17ToV18Transformer`, `PG17ToPG18Transformer` | ## 🏗 Architecture diff --git a/packages/transform-ast/src/transformers-direct/README.md b/packages/transform-ast/src/transformers-direct/README.md index 43aa3e5e4..229a783bd 100644 --- a/packages/transform-ast/src/transformers-direct/README.md +++ b/packages/transform-ast/src/transformers-direct/README.md @@ -1,6 +1,6 @@ # Direct Transformers for PostgreSQL AST -Direct transformers provide optimized, tree-shakeable modules for transforming PostgreSQL ASTs directly from one version to PG17. +Direct transformers provide optimized, tree-shakeable modules for transforming PostgreSQL ASTs directly from one version to PG18 (the latest) or PG17. ## Features @@ -14,21 +14,21 @@ Direct transformers provide optimized, tree-shakeable modules for transforming P ### Transform a Complete Parse Result ```typescript -import { PG15ToPG17Transformer } from '@pgsql/transform-ast/transformers-direct/v15-to-v17'; +import { PG15ToPG18Transformer } from '@pgsql/transform-ast/transformers-direct/v15-to-v18'; import { Parser } from '@pgsql/parser'; const parser = new Parser({ version: 15 }); const pg15Ast = await parser.parse('SELECT * FROM users'); -const transformer = new PG15ToPG17Transformer(); -const pg17Ast = transformer.transform(pg15Ast); -// pg17Ast is typed as V17Types.ParseResult +const transformer = new PG15ToPG18Transformer(); +const pg18Ast = transformer.transform(pg15Ast); +// pg18Ast is typed as PG18.ParseResult ``` ### Transform Any Node in the AST ```typescript -import { PG15ToPG17Transformer } from '@pgsql/transform-ast/transformers-direct/v15-to-v17'; +import { PG15ToPG18Transformer } from '@pgsql/transform-ast/transformers-direct/v15-to-v18'; // Transform just a statement node const stmtNode = pg15Ast.stmts[0].stmt; @@ -45,6 +45,11 @@ const transformedWhere = transformer.transform(whereClause); | Transformer | Import Path | Dependencies | |------------|-------------|--------------| +| PG17→PG18 | `@pgsql/transform-ast/transformers-direct/v17-to-v18` | v17→v18 only | +| PG16→PG18 | `@pgsql/transform-ast/transformers-direct/v16-to-v18` | v16→v17, v17→v18 | +| PG15→PG18 | `@pgsql/transform-ast/transformers-direct/v15-to-v18` | v15→v16, v16→v17, v17→v18 | +| PG14→PG18 | `@pgsql/transform-ast/transformers-direct/v14-to-v18` | v14→v15, v15→v16, v16→v17, v17→v18 | +| PG13→PG18 | `@pgsql/transform-ast/transformers-direct/v13-to-v18` | All transformers | | PG16→PG17 | `@pgsql/transform-ast/transformers-direct/v16-to-v17` | v16→v17 only | | PG15→PG17 | `@pgsql/transform-ast/transformers-direct/v15-to-v17` | v15→v16, v16→v17 | | PG14→PG17 | `@pgsql/transform-ast/transformers-direct/v14-to-v17` | v14→v15, v15→v16, v16→v17 | @@ -54,17 +59,17 @@ const transformedWhere = transformer.transform(whereClause); ### `transform(node)` -Transforms a node from the source PostgreSQL version to PG17. +Transforms a node from the source PostgreSQL version to the transformer's target version (PG18 or PG17). **Overloads:** -- `transform(node: VXXTypes.Node): V17Types.Node` - Transform any node type -- `transform(node: VXXTypes.ParseResult): V17Types.ParseResult` - Transform a parse result +- `transform(node: VXXTypes.Node): VYYTypes.Node` - Transform any node type +- `transform(node: VXXTypes.ParseResult): VYYTypes.ParseResult` - Transform a parse result **Parameters:** - `node` - The node or parse result to transform **Returns:** -- The transformed node or parse result in PG17 format +- The transformed node or parse result in the target version's format ### `transformStatement(stmt)` (Deprecated) @@ -76,11 +81,11 @@ Import types directly from the version-specific type modules: ```typescript import * as PG15 from '@pgsql/transform-ast/15/types'; -import * as PG17 from '@pgsql/transform-ast/17/types'; +import * as PG18 from '@pgsql/transform-ast/18/types'; // Use types for type annotations const node: PG15.Node = ...; -const result: PG17.ParseResult = ...; +const result: PG18.ParseResult = ...; ``` ## Examples @@ -100,8 +105,8 @@ const complexSQL = ` const pg14Parser = new Parser({ version: 14 }); const pg14Ast = await pg14Parser.parse(complexSQL); -const transformer = new PG14ToPG17Transformer(); -const pg17Ast = transformer.transform(pg14Ast); +const transformer = new PG14ToPG18Transformer(); +const pg18Ast = transformer.transform(pg14Ast); ``` ### Transforming Specific Nodes