Skip to content

Commit 07479bc

Browse files
pyramationpyramation
authored
Merge pull request #26 from launchql/fix/readme
base readme
2 parents 7e09281 + c918380 commit 07479bc

File tree

1 file changed

+57
-51
lines changed

1 file changed

+57
-51
lines changed

‎README.md‎

Lines changed: 57 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,51 @@ npm install pgsql-parser
2727
- **True PostgreSQL Parsing:** Utilizes the real PostgreSQL source code for accurate parsing.
2828
- **Symmetric Parsing and Deparsing:** Convert SQL to AST and back, enabling query manipulation.
2929
- **AST Manipulation:** Easily modify parts of a SQL statement through the AST.
30+
- **WebAssembly Powered:** Cross-platform compatibility without native dependencies.
31+
32+
## API
33+
34+
The package exports both async and sync methods. Async methods handle initialization automatically, while sync methods require explicit initialization.
35+
36+
⚠️ We recommend using `@pgsql/deparser` instead of `deparse` from `pgsql-parser`. The deparser package is more complete, supports sub-expressions, and doesn't require the WebAssembly module, making it lighter and more flexible for most use cases. It will soon be deprecated, in a minor version bump.
37+
38+
### Async Methods (Recommended)
39+
40+
```typescript
41+
import { parse, deparse, parseFunction } from 'pgsql-parser';
42+
43+
// Parse SQL to AST
44+
const stmts = await parse('SELECT * FROM test_table');
45+
46+
// Deparse AST back to SQL
47+
const sql = await deparse(stmts);
48+
49+
// Parse PL/pgSQL functions
50+
const funcAst = await parseFunction(`
51+
CREATE FUNCTION get_count() RETURNS integer AS $$
52+
BEGIN
53+
RETURN (SELECT COUNT(*) FROM users);
54+
END;
55+
$$ LANGUAGE plpgsql;
56+
`);
57+
```
58+
59+
### Sync Methods
60+
61+
Sync methods require explicit initialization using `loadModule()`:
62+
63+
```typescript
64+
import { loadModule, parseSync, deparseSync } from 'pgsql-parser';
65+
66+
// Initialize first (required for sync methods)
67+
await loadModule();
68+
69+
// Now safe to use sync methods
70+
const stmts = parseSync('SELECT * FROM test_table');
71+
const sql = deparseSync(stmts);
72+
```
73+
74+
**Note:** We recommend using async methods as they handle initialization automatically. Use sync methods only when necessary, and always call `loadModule()` first.
3075

3176
## Parser Example
3277

@@ -35,12 +80,12 @@ Rewrite part of a SQL query:
3580
```js
3681
import { parse, deparse } from 'pgsql-parser';
3782

38-
const stmts = parse('SELECT * FROM test_table');
83+
const stmts = await parse('SELECT * FROM test_table');
3984

4085
// Assuming the structure of stmts is known and matches the expected type
4186
stmts[0].RawStmt.stmt.SelectStmt.fromClause[0].RangeVar.relname = 'another_table';
4287

43-
console.log(deparse(stmts));
88+
console.log(await deparse(stmts));
4489

4590
// SELECT * FROM "another_table"
4691
```
@@ -52,11 +97,11 @@ The `pgsql-deparser` module serializes ASTs to SQL in pure TypeScript, avoiding
5297
Here's how you can use the deparser in your TypeScript code, using [`@pgsql/utils`](https://github.com/launchql/pgsql-parser/tree/main/packages/utils) to create an AST for `deparse`:
5398

5499
```ts
55-
import ast, { SelectStmt } from '@pgsql/utils';
100+
import ast from '@pgsql/utils';
56101
import { deparse } from 'pgsql-deparser';
57102

58103
// This could have been obtained from any JSON or AST, not necessarily @pgsql/utils
59-
const stmt: SelectStmt = ast.selectStmt({
104+
const stmt = ast.selectStmt({
60105
targetList: [
61106
ast.resTarget({
62107
val: ast.columnRef({
@@ -96,51 +141,16 @@ npm install -g pgsql-parser
96141
pgsql-parser <sqlfile>
97142
```
98143

99-
### Documentation
100-
101-
### `parser.parse(sql)`
102-
103-
Parses the query and returns a parse object.
104-
105-
### Parameters
106-
107-
| parameter | type | description |
108-
| -------------------- | ------------------ | --------------------------------------------------------- |
109-
| `query` | String | SQL query |
110-
111-
Returns an object in the format:
112-
113-
```
114-
{ query: <query|Object>,
115-
error: { message: <message|String>,
116-
fileName: <fileName|String>,
117-
lineNumber: <line|Number>,
118-
cursorPosition: <cursor|Number> }
119-
```
120-
121-
### `parser.deparse(query)`
122-
123-
Deparses the query tree and returns a formatted SQL statement. This function takes as input a query AST
124-
in the same format as the `query` property of on the result of the `parse` method. This is the primary
125-
functionality of this module.
126-
127-
### Parameters
128-
129-
| parameter | type | description |
130-
| -------------------- | ------------------ | --------------------------------------------------------- |
131-
| `query` | Object | Query tree obtained from `parse` |
132-
133-
Returns a normalized formatted SQL string.
134-
135144
## Versions
136145

137146
As of PG 13, PG majors versions maintained will have a matching dedicated major npm version. Only the latest Postgres stable release receives active updates.
138147

139-
Our latest is built with `13-latest` branch from libpg_query
148+
Our latest is built with `17-latest` branch from libpg_query
140149

141-
| PostgreSQL Major Version | libpg_query | Status | npm
150+
| PostgreSQL Major Version | libpg_query | Status | npm tag |
142151
|--------------------------|-------------|---------------------|---------|
143-
| 13 | 13-latest | Active development | `latest`
152+
| 17 | 17-latest | Active Development | `latest` |
153+
| 13 | 13-latest | Only Critical Fixes | `13.16.0` |
144154
| 12 | (n/a) | Not supported |
145155
| 11 | (n/a) | Not supported |
146156
| 10 | 10-latest | Not supported | `@1.3.1` ([tree](https://github.com/launchql/pgsql-parser/tree/39b7b1adc8914253226e286a48105785219a81ca)) |
@@ -157,22 +167,18 @@ Our latest is built with `13-latest` branch from libpg_query
157167
* [pg-proto-parser](https://github.com/launchql/pg-proto-parser): A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
158168
* [libpg-query](https://github.com/launchql/libpg-query-node): The real PostgreSQL parser exposed for Node.js, used primarily in `pgsql-parser` for parsing and deparsing SQL queries.
159169

170+
## Credits
171+
160172
Thanks [@lfittl](https://github.com/lfittl) for building the core `libpg_query` suite:
161173

162174
* [libpg_query](https://github.com/pganalyze/libpg_query)
163175
* [pg_query](https://github.com/lfittl/pg_query)
164176
* [pg_query.go](https://github.com/lfittl/pg_query.go)
165177

166-
## Credits
167-
168-
Thanks to [@zhm](https://github.com/zhm) for the OG parser that started it all:
169-
170-
* [pg-query-parser](https://github.com/zhm/pg-query-parser)
171-
* [pg-query-native](https://github.com/zhm/node-pg-query-native)
172-
* [Original LICENSE](https://github.com/zhm/pg-query-parser/blob/master/LICENSE.md)
178+
Thanks to [@zhm](https://github.com/zhm) for the [OG Parser](https://github.com/zhm/pg-query-parser/blob/master/LICENSE.md) that started it all.
173179

174180
## Disclaimer
175181

176-
AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
182+
AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
177183

178184
No developer or entity involved in creating Software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the Software code or Software CLI, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

0 commit comments

Comments
 (0)