Skip to content

Commit e2ecdf5

Browse files
refactor: Simplify main README.md transform documentation
- Remove detailed transform documentation from main README - Keep only the packages table entry for @pgsql/transform - Detailed documentation remains in packages/transform/README.md - Main README now has concise highlight as requested Co-Authored-By: Dan Lynch <[email protected]>
1 parent 7aef660 commit e2ecdf5

File tree

1 file changed

+0
-120
lines changed

1 file changed

+0
-120
lines changed

README.md

Lines changed: 0 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -218,126 +218,6 @@ console.log(await deparse(query));
218218
// SELECT name, email FROM users WHERE age > 18
219219
```
220220

221-
## AST Transformation Between PostgreSQL Versions
222-
223-
The `@pgsql/transform` package enables transformation of PostgreSQL ASTs between different PostgreSQL versions, providing a crucial component for building a single source of truth deparser that works with legacy SQL code.
224-
225-
### Core Use Case
226-
227-
The transform package serves as the backbone for maintaining backward compatibility in the deparser pipeline. It allows you to:
228-
229-
- **Transform legacy ASTs**: Convert ASTs from older PostgreSQL versions (13, 14, 15, 16) to the latest version (17)
230-
- **Build unified deparsers**: Create a single deparser that can handle SQL from multiple PostgreSQL versions
231-
- **Maintain compatibility**: Support legacy codebases while leveraging the latest PostgreSQL parser features
232-
233-
### Key Limitation
234-
235-
The transform package only supports ASTs that derive from SQL parseable by PostgreSQL 17. This means:
236-
237-
-**Supported**: SQL code from PG13-16 that is still valid in PG17
238-
-**Not supported**: Deprecated PG13 syntax that was removed in later versions
239-
-**Not supported**: SQL that cannot be parsed by the PG17 parser
240-
241-
This limitation is by design - it ensures that all transformed ASTs can be reliably deparsed using the latest PostgreSQL grammar.
242-
243-
### Installation
244-
245-
```bash
246-
npm install @pgsql/transform
247-
```
248-
249-
### Basic Usage
250-
251-
#### Multi-Version Transformer
252-
253-
```typescript
254-
import { ASTTransformer } from '@pgsql/transform';
255-
256-
const transformer = new ASTTransformer();
257-
258-
// Transform from any version to PG17
259-
const pg17Ast = transformer.transformToLatest(pg13Ast, 13);
260-
261-
// Transform between specific versions
262-
const pg15Ast = transformer.transform(pg13Ast, 13, 15);
263-
264-
// Convenience methods for common transformations
265-
const pg17FromPg13 = transformer.transform13To17(pg13Ast);
266-
const pg17FromPg14 = transformer.transform14To17(pg14Ast);
267-
```
268-
269-
#### Direct Transformers
270-
271-
For better performance when you know the source and target versions:
272-
273-
```typescript
274-
import {
275-
PG13ToPG17Transformer,
276-
PG14ToPG17Transformer,
277-
PG15ToPG17Transformer,
278-
PG16ToPG17Transformer
279-
} from '@pgsql/transform';
280-
281-
// Direct transformation from PG13 to PG17
282-
const pg13to17 = new PG13ToPG17Transformer();
283-
const pg17Ast = pg13to17.transform(pg13Ast);
284-
285-
// Works with both individual nodes and ParseResult objects
286-
const transformedParseResult = pg13to17.transform(pg13ParseResult);
287-
```
288-
289-
#### Integration with Parser and Deparser
290-
291-
```typescript
292-
import { parse } from '@pgsql/parser'; // Multi-version parser
293-
import { deparse } from 'pgsql-deparser';
294-
import { PG13ToPG17Transformer } from '@pgsql/transform';
295-
296-
// Parse with older PostgreSQL version
297-
const pg13Ast = await parse('SELECT * FROM users', { version: 13 });
298-
299-
// Transform to latest version for deparser
300-
const transformer = new PG13ToPG17Transformer();
301-
const pg17Ast = transformer.transform(pg13Ast);
302-
303-
// Deparse using latest grammar
304-
const sql = await deparse(pg17Ast);
305-
console.log(sql); // SELECT * FROM users
306-
```
307-
308-
### Transformation Chain
309-
310-
The package supports both incremental and direct transformations:
311-
312-
**Incremental Chain**: PG13 → PG14 → PG15 → PG16 → PG17
313-
- Each step handles version-specific changes
314-
- Useful for debugging transformation issues
315-
- Allows intermediate version targeting
316-
317-
**Direct Transformers**: PG13 → PG17, PG14 → PG17, etc.
318-
- Optimized single-step transformations
319-
- Better performance for common use cases
320-
- Internally chains the incremental transformers
321-
322-
### Version Support
323-
324-
| Source Version | Target Versions | Transformer Class |
325-
|----------------|-----------------|-------------------|
326-
| PostgreSQL 13 | 14, 15, 16, 17 | `V13ToV14Transformer`, `PG13ToPG17Transformer` |
327-
| PostgreSQL 14 | 15, 16, 17 | `V14ToV15Transformer`, `PG14ToPG17Transformer` |
328-
| PostgreSQL 15 | 16, 17 | `V15ToV16Transformer`, `PG15ToPG17Transformer` |
329-
| PostgreSQL 16 | 17 | `V16ToV17Transformer`, `PG16ToPG17Transformer` |
330-
331-
### Architecture
332-
333-
The transform package is designed to work seamlessly with the broader pgsql-parser ecosystem:
334-
335-
1. **Parse** legacy SQL using version-specific parsers
336-
2. **Transform** the resulting AST to the latest version
337-
3. **Deparse** using the unified, latest-version deparser
338-
339-
This architecture enables a single source of truth for SQL generation while maintaining support for legacy codebases.
340-
341221
## Related
342222

343223
* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.

0 commit comments

Comments
 (0)