@typesql/pg 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +21 -59
  3. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # @typesql/pg
2
2
 
3
+ ## 0.2.1
4
+
5
+ ### Patch Changes
6
+
7
+ - The README is shorter: install, one example and links to the docs site, which now has the details it used to repeat.
8
+
9
+ - Updated dependencies:
10
+ - @typesql/core@0.6.0
11
+
3
12
  ## 0.2.0
4
13
 
5
14
  ### Minor Changes
package/README.md CHANGED
@@ -1,15 +1,13 @@
1
1
  # @typesql/pg
2
2
 
3
- [node-postgres](https://node-postgres.com) (`pg` 8.x) adapter for
4
- [`@typesql/core`](https://www.npmjs.com/package/@typesql/core): a `createSql` bound to the type
5
- map of `pg`'s default parsers, whose queries run on your pool and return rows typed from the SQL.
3
+ Run [TypeSQL](https://www.npmjs.com/package/@typesql/core) queries on [node-postgres](https://node-postgres.com) (`pg` 8.x), with rows typed the way `pg` returns them.
4
+
5
+ ## Install
6
6
 
7
7
  ```sh
8
- pnpm add @typesql/core @typesql/pg pg
8
+ npm install @typesql/core @typesql/pg pg
9
9
  ```
10
10
 
11
- [Open an example in the TypeScript Playground](https://www.typescriptlang.org/play/#code/PTAEBUE8AcFMGUCKAZUB3AlgFwBagHYD2AJrALTSEDOWA5gE6xWgAUAAljEwI4A2w0WgEoAdKEQBXWPQxNQ9CflCElkQhPqgACoUK8ANKACG+YvMJpmRxqE5wzAI0jocRrACgQoQQHJmpADMjCV4sb2sqaWZGLA18AC5QDHwsAA5jUwIJAFtpDABjY2YaGXxaKkMsDFyaI2zoK2YAETdYMQAJQgA3aVscWHkmEKwqEXd3asp6MLsBgG9QAGE9QwBxWHxpVuJDADkQ3iMHXgGAX1AA+kJs0AAiDi4qPmB8wkZbgG4J+rewhfzGK14HxQOdLtc7g84E9+IJPt8pn9tLpeKCLlcbrc4V9PGAAOoyLADXAYZhOUCuUyGN6gWgbLZEpJhcE3NQaUDENxHIyRRIAA1mMKSKSuVDg+TCZDIGlRgDICUBS9RhKj5frZIwiEZ8iYpaRBfIDJoAIVAc3cAEgJJF6FREmbzeaMMREutNvRtgAeW7JLAAFluAD4vg7YOqMLxEsteF6iQAPLCB4Pm4ik6CHSAAfXwdVgiX2vEOx1gMdg8cTFvNDiMh3wBsjei9+ByeXy5YdANg2wzbhd9PdROIMeqTCwdWgWAAXm3TsHKDRbaaK07e27Pd6Uqk2+bgrg3hnl0sG+u-VuqlgTvXo7c4wmgxXoBJjqT+sRu1g8wcjichzVR-VJ9OXynOMrz4DQ3goqAAC8BCwGgyJ6Cw-wqJsEoYCo8BYKUtCJFi1B0IwtogLwhD5NWOD4cARjQNAtygkIXygeBQowR2QJ8B6xoBiwlB6AxIEqOBTgAIISLumgwTCLAWny8AAKLIHJizgN4IhOoY0CatgJwaSID5PlQL5voYEgiKGRjhu4oDWTZtl2fZoAAGIAEoAPIALIQfO3igAAUq5ACSuygFaUQhaArnBaZTrQapO4UfQ+7EFZDmpfZeLtHJzlyXFYkJUlsUACQAIx8voFoAOzlfxTFhHOIyxUYaAWWEIl5W8ZmxrA+RibALD8V4NkAHoAPwCWBYShRJxjNdgoBSTJ8mKcpSQ7KAVY1gahhsQOb5OW5nlTcwGVZTl5nhkVpXleatxGJybClmOJwiK82S3NVnXdb14BGAA1rAjkYDaWCufQ4A4FcaD9V8g3WaN43ga8igNTBTUtfNfDSeaskKUpKnxXu6mgEjKQsAAVEIoDCfABD7R5XkNasbkAKpaKARoAJrGO1iVOmV7iiKWX1EtDuK2fDYtYLGSTFCCDjqJkWCEMomy2O6YFGGhKiRh57kBSpaD9EouADAEiha0ohF6D0FSgG5yDIEawmLAA0i4GxMn0kOjO4tUMwFZio7Nyp8Jq6tUJrVQqCwPKQLWrBS5TUEBou5qDfD5p+wsMXnEH6NS1j2NBfJzkqUF4CuSF1rMCw50GOt1YmAalMAGrCcgzNyTTLAlYYhUAEyU9l4DM85uxBasq38w6twMJrsAPbGT1tK970VgADNdgtdT1RI-f9gPA6D4OQ6LmeCXV+GNcHtixoXfLF1lZe7BXDM1wTvNrWeJyt+3nfd73UAA8h5yRHmPCeU9rqOh2BWW47RYAFkIGvc029hawH3gDIGNBj4QwsGfGIcQGZqWIEBfiYstDWBzESG0xgbCqm6v9MwRhaAWQmn0WAQNiZ6ByAkbm4kCqkmFH6MYaM5pST5E0XG4AcouXpvVY6mVsp8PyjFGCJUyp3AqrcVBu8+oMVAF4aQVx6CJCMPNLCyRaAywIIQMIJghG+ncEAA) <!-- playground:pg --> to hover the types and edit the SQL, with nothing to install.
12
-
13
11
  ## Usage
14
12
 
15
13
  ```ts
@@ -17,73 +15,37 @@ import { Pool } from "pg";
17
15
  import { createSql } from "@typesql/pg";
18
16
  import type { DB } from "./schema";
19
17
 
20
- const pool = new Pool();
21
- const sql = createSql<DB>(pool);
18
+ const sql = createSql<DB>(new Pool());
19
+
20
+ const users = await sql("SELECT id, email FROM users").execute();
21
+ // { id: number; email: string }[]
22
22
 
23
- const users = await sql("SELECT id, email FROM users").execute(); // { id: number; email: string }[]
24
- const maybe = await sql("SELECT id FROM users WHERE email = $1", "x").executeTakeFirst(); // row | undefined
25
- const user = await sql("SELECT id, email FROM users WHERE id = $1", 7).executeTakeFirstOrThrow(); // row, or NoResultError
26
- const changed = await sql("UPDATE users SET display_name = NULL").executeCount(); // row count
23
+ const user = await sql("SELECT id, email FROM users WHERE id = $1", 7).executeTakeFirstOrThrow();
27
24
 
28
- const id = await sql.transaction(async (tx) => {
25
+ await sql.transaction(async (tx) => {
29
26
  const { id } = await tx("INSERT INTO users (email) VALUES ($1) RETURNING id", "a@b.c").executeTakeFirstOrThrow();
30
27
  await tx("INSERT INTO posts (author_id, title) VALUES ($1, $2)", id, "Hello").execute();
31
- return id;
32
28
  });
33
29
  ```
34
30
 
35
- ## API
31
+ `createSql` takes a `Pool`, a `Client` or a `PoolClient`. As in `pg`, `int8` (so `count(*)`), `numeric` and `money` come back as strings.
36
32
 
37
- | Export | |
38
- |---|---|
39
- | `createSql<DB>(client, options?)` | core's `createSql<DB, PgTypeMap>()` with the queries running on `client` (a `Pool`, `Client` or `PoolClient`); `{ rowKeys: "camelCase" }` camelCases the row keys |
40
- | `q.execute()`, `q.executeTakeFirst()`, `q.executeTakeFirstOrThrow()`, `q.executeCount()` | `Promise<Row[]>`, `Promise<Row \| undefined>`, `Promise<Row>` (`NoResultError` on 0 rows), `Promise<number>` (`rowCount`) |
41
- | `sql.transaction(fn)` | on a `Pool`: checks out a client, `BEGIN`, `fn(tx)`, `COMMIT`, releases it; `ROLLBACK` and rethrow on error. On a `Client` or `PoolClient`: the same on that connection. `tx` is `sql` bound to the transaction; `tx.transaction(fn)` uses a savepoint |
42
- | `executor(client)` | an `Executor` for `q.execute(executor)` and core's `createSql(executor)` (reports `rowCount`) |
43
- | `migrate(pool, m)` | runs `m.statements` (e.g. from core's `migrations()`) in one transaction |
44
- | `PgSql<DB, Keys>` | the type `createSql` returns |
45
- | `PgTypeMap`, `PgParamTypeMap`, `PgInterval` | the type map (rows), what parameters also accept, and the `postgres-interval` object type |
46
- | `PgQueryable`, `PgPoolLike`, `PgTransactionClient`, `PgResult`, `MigrationSource` | parameter types |
47
-
48
- `client` is anything with `query(text, values)`. The parameters are structural, so fakes work
49
- in tests. If the `ROLLBACK` of a pool transaction fails, the client is released with the error
50
- so the pool discards the connection.
33
+ [Open an example in the TypeScript Playground](https://www.typescriptlang.org/play/#code/PTAEBUE8AcFMGUCKAZUB3AlgFwBagHYD2AJrALTSEDOWA5gE6xWgAUAAljEwI4A2w0WgEoAdKEQBXWPQxNQ9CflCElkQhPqgACoUK8ANKACG+YvMJpmRxqE5wzAI0jocRrACgQoQQHJmpADMjCV4sb2sqaWZGLA18AC5QDHwsAA5jUwIJAFtpDABjY2YaGXxaKkMsDFyaI2zoK2YAETdYMQAJQgA3aVscWHkmEKwqEXd3asp6MLsBgG9QAGE9QwBxWHxpVuJDADkQ3iMHXgGAX1AA+kJs0AAiDi4qPmB8wkZbgG4J+rewhfzGK14HxQOdLtc7g84E9+IJPt8pn9tLpeKCLlcbrc4V9PGAAOoyLADXAYZhOUCuUyGN6gWgbLZEpJhcE3NQaUDENxHIyRRIAA1mMKSKSuVDg+TCZDIGlRgDICUBS9RhKj5frZIwiEZ8iYpaRBfIDJoAIVAc3cAEgJJF6FREmbzeaMMREutNvRtgAeW7JLAAFluAD4vg7YOqMLxEsteF6iQAPLCB4Pm4ik6CHSAAfXwdVgiX2vEOx1gMdg8cTFvNDiMh3wBsjei9+ByeXy5YdANg2wzbhd9PdROIMeqTCwdWgWAAXm3TsHKDRbaaK07e27Pd6Uqk2+bgrg3hnl0sG+u-VuqlgTvXo7c4wmgxXoBJjqT+sRu1g8wcjichzVR-VJ9OXynOMrz4DQ3goqAAC8BCwGgyJ6Cw-wqJsEoYCo8BYKUtCJFi1B0IwtogLwhD5NWOD4cARjQNAtygkIXygeBQowR2QJ8B6xoBiwlB6AxIEqOBTgAIISLumgwTCLAWny8AAKLIHJizgN4IhOoY0CatgJwaSID5PlQL5voYEgiKGRjhu4oDWTZtl2fZoAAGIAEoAPIALIQfO3igAAUq5ACSuygFaUQhaArnBaZTrQapO4UfQ+7EFZDmpfZeLtHJzlyXFYkJUlsUACQAIx8voFoAOzlfxTFhHOIyxUYaAWWEIl5W8ZmxrA+RibALD8V4NkAHoAPwCWBYShRJxjNdgoBSTJ8mKcpSQ7KAVY1gahhsQOb5OW5nlTcwGVZTl5nhkVpXleatxGJybClmOJwiK82S3NVnXdb14BGAA1rAjkYDaWCufQ4A4FcaD9V8g3WaN43ga8igNTBTUtfNfDSeaskKUpKnxXu6mgEjKQsAAVEIoDCfABD7R5XkNasbkAKpaKARoAJrGO1iVOmV7iiKWX1EtDuK2fDYtYLGSTFCCDjqJkWCEMomy2O6YFGGhKiRh57kBSpaD9EouADAEiha0ohF6D0FSgG5yDIEawmLAA0i4GxMn0kOjO4tUMwFZio7Nyp8Jq6tUJrVQqCwPKQLWrBS5TUEBou5qDfD5p+wsMXnEH6NS1j2NBfJzkqUF4CuSF1rMCw50GOt1YmAalMAGrCcgzNyTTLAlYYhUAEyU9l4DM85uxBasq38w6twMJrsAPbGT1tK970VgADNdgtdT1RI-f9gPA6D4OQ6LmeCXV+GNcHtixoXfLF1lZe7BXDM1wTvNrWeJyt+3nfd73UAA8h5yRHmPCeU9rqOh2BWW47RYAFkIGvc029hawH3gDIGNBj4QwsGfGIcQGZqWIEBfiYstDWBzESG0xgbCqm6v9MwRhaAWQmn0WAQNiZ6ByAkbm4kCqkmFH6MYaM5pST5E0XG4AcouXpvVY6mVsp8PyjFGCJUyp3AqrcVBu8+oMVAF4aQVx6CJCMPNLCyRaAywIIQMIJghG+ncEAA) <!-- playground:pg --> to hover the types and edit the SQL, with nothing to install.
51
34
 
52
- ## `typesql introspect`
35
+ ## Generate your schema
53
36
 
54
- Generates the schema from a live database: tables, views, materialized views and enums, with
55
- the exact Postgres type of every column (domains as their base type), nullability, defaults,
56
- identity and generated columns, other schemas nested, and TypeScript types for JSON columns
57
- from a config file.
37
+ This package also ships the `typesql` command, which writes the `DB` type from a live database:
58
38
 
59
39
  ```sh
60
- pnpm exec typesql introspect --url postgres://localhost/app --out src/db/schema.ts
61
- pnpm exec typesql introspect --schema public,auth --config typesql.config.ts
40
+ npx typesql introspect --url postgres://localhost/app --out src/db/schema.ts
62
41
  ```
63
42
 
64
- The same is available from code as `introspect(client)` and `generateSource(db)` in
65
- `@typesql/pg/introspect`. See the
66
- [Introspection guide](https://github.com/ismailkarsli/typesql/blob/main/packages/docs/guide/introspect.md).
67
-
68
- ## `PgTypeMap`
69
-
70
- What `pg`'s default parsers return:
43
+ ## Documentation
71
44
 
72
- | Postgres | TypeScript |
73
- |---|---|
74
- | `int2`, `int4`, `oid`, `float4`, `float8` | `number` |
75
- | `int8` (also `count(*)`), `numeric`, `money` | `string` |
76
- | `bool` | `boolean` |
77
- | `date`, `timestamp`, `timestamptz` | `Date` |
78
- | `json`, `jsonb` | `unknown` |
79
- | `bytea` | `Buffer` |
80
- | `interval` | `PgInterval` |
81
- | `point`, `circle` | `{ x, y }`, `{ x, y, radius }` |
82
- | text-like and other types | `string` |
45
+ - [node-postgres adapter](https://typesql.karsli.net/adapters/pg): running queries, transactions and migrations
46
+ - [From a live database](https://typesql.karsli.net/guide/introspect): `typesql introspect` options
47
+ - [Type mapping](https://typesql.karsli.net/reference/type-mapping#node-postgres): the TypeScript type of every Postgres type
83
48
 
84
- Arrays map element-wise. The full table, including the array types `pg` leaves as raw text, is
85
- on the [node-postgres adapter page](https://github.com/ismailkarsli/typesql/blob/main/packages/docs/adapters/pg.md).
49
+ ## License
86
50
 
87
- Parameters accept the row type and what `pg` serializes for the type (`PgParamTypeMap`):
88
- `number | bigint | string` for `int8`, `numeric` and `money`, `Date | string` for dates and
89
- timestamps, `string` for `interval`, `Uint8Array` for `bytea`.
51
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typesql/pg",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "node-postgres (pg) adapter for TypeSQL, with `typesql introspect` to generate a schema from a live database.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -35,7 +35,7 @@
35
35
  "access": "public"
36
36
  },
37
37
  "dependencies": {
38
- "@typesql/core": "0.5.0"
38
+ "@typesql/core": "0.6.0"
39
39
  },
40
40
  "peerDependencies": {
41
41
  "pg": ">=8"