2 |
3 | # [PgTyped](https://pgtyped.dev/)
4 |
5 | 
6 | [](https://github.com/adelsz/pgtyped/actions) [](https://gitter.im/pgtyped/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
7 |
8 | ## ReScript fork of PgTyped
9 |
10 | > This is a fork PgTyped that outputs ReScript instead of TS. Most things work the same as the TS version. [Here's a dedicated ReScript readme](./RESCRIPT.md) detailing the differences, and how to get started in ReScript.
11 |
12 | PgTyped makes it possible to use raw SQL in TypeScript with guaranteed type-safety.
13 | No need to map or translate your DB schema to TypeScript, PgTyped automatically generates types and interfaces for your SQL queries by using your running Postgres database as the source of type information.
14 |
15 | ---
16 |
17 | ## Features:
18 |
19 | 1. Automatically generates TS types for parameters/results of SQL queries of any complexity.
20 | 2. Supports extracting and typing queries from both SQL and TS files.
21 | 3. Generate query types as you write them, using watch mode.
22 | 4. Useful parameter interpolation helpers for arrays and objects.
23 | 5. No need to define your DB schema in TypeScript, your running DB is the live source of type data.
24 | 6. Prevents SQL injections by not doing explicit parameter substitution. Instead, queries and parameters are sent separately to the DB driver, allowing parameter substitution to be safely done by the PostgreSQL server.
25 | 7. Native ESM support. Runtime dependencies are also provided as CommonJS.
26 |
27 | ### Documentation
28 |
29 | Visit our documentation page at [https://pgtyped.dev/](https://pgtyped.dev/)
30 |
31 | ### Getting started
32 |
33 | 1. `npm install -D @pgtyped/cli typescript` (typescript is a required peer dependency for pgtyped)
34 | 2. `npm install @pgtyped/runtime` (`@pgtyped/runtime` is the only required runtime dependency of pgtyped)
35 | 3. Create a PgTyped `config.json` file.
36 | 4. Run `npx pgtyped -w -c config.json` to start PgTyped in watch mode.
37 |
38 | More info on getting started can be found in the [Getting Started](https://pgtyped.dev/docs/getting-started) page.
39 | You can also refer to the [example app](./packages/example/README.md) for a preconfigured example.
40 |
41 | ### Example
42 |
43 | Lets save some queries in `books.sql`:
44 |
45 | ```sql
46 | /* @name FindBookById */
47 | SELECT * FROM books WHERE id = :bookId;
48 | ```
49 |
50 | PgTyped parses the SQL file, extracting all queries and generating strictly typed TS queries in `books.queries.ts`:
51 |
52 | ```ts
53 | /** Types generated for queries found in "books.sql" */
54 |
55 | //...
56 |
57 | /** 'FindBookById' parameters type */
58 | export interface IFindBookByIdParams {
59 | bookId: number | null;
60 | }
61 |
62 | /** 'FindBookById' return type */
63 | export interface IFindBookByIdResult {
64 | id: number;
65 | rank: number | null;
66 | name: string | null;
67 | author_id: number | null;
68 | }
69 |
70 | /**
71 | * Query generated from SQL:
72 | * SELECT * FROM books WHERE id = :bookId
73 | */
74 | export const findBookById = new PreparedQuery<
75 | IFindBookByIdParams,
76 | IFindBookByIdResult
77 | >(...);
78 | ```
79 |
80 | Query `findBookById` is now statically typed, with types inferred from the PostgreSQL schema.
81 | This generated query can be imported and executed as follows:
82 |
83 | ```ts
84 | import { Client } from 'pg';
85 | import { findBookById } from './books.queries';
86 |
87 | export const client = new Client({
88 | host: 'localhost',
89 | user: 'test',
90 | password: 'example',
91 | database: 'test',
92 | });
93 |
94 | async function main() {
95 | await client.connect();
96 | const books = await findBookById.run(
97 | {
98 | bookId: 5,
99 | },
100 | client,
101 | );
102 | console.log(`Book name: ${books[0].name}`);
103 | await client.end();
104 | }
105 |
106 | main();
107 | ```
108 |
109 | ### Resources
110 |
111 | 1. [Configuring pgTyped](https://pgtyped.dev/docs/cli)
112 | 2. [Writing queries in SQL files](https://pgtyped.dev/docs/sql-file-intro)
113 | 3. [Advanced queries and parameter expansions in SQL files](https://pgtyped.dev/docs/sql-file)
114 | 4. [Writing queries in TS files](https://pgtyped.dev/docs/ts-file-intro)
115 | 5. [Advanced queries and parameter expansions in TS files](https://pgtyped.dev/docs/ts-file)
116 |
117 | ### Project state:
118 |
119 | This project is being actively developed and its APIs might change.
120 | All issue reports, feature requests and PRs appreciated.
121 |
122 | ### License
123 |
124 | [MIT](https://github.com/adelsz/pgtyped/tree/master/LICENSE)
125 |
126 | Copyright (c) 2019-present, Adel Salakh
127 |
--------------------------------------------------------------------------------
/RESCRIPT.md:
--------------------------------------------------------------------------------
1 | # pgtyped-rescript
2 |
3 | This small readme focuses on the differences between regular `pgtyped` and this fork that is compatible with ReScript.
4 |
5 | ## Differences to regular `pgtyped`
6 |
7 | - It outputs ReScript instead of TypeScript.
8 |
9 | Everything else should work pretty much the same as stock `pgtyped`.
10 |
11 | ## Getting started
12 |
13 | Make sure you have ReScript `v11.1`, and [ReScript Core](https://github.com/rescript-association/rescript-core) (plus `RescriptCore` opened globally).
14 |
15 | 1. `npm install -D pgtyped-rescript rescript-embed-lang` (install `rescript-embed-lang` if you want to use the SQL-in-ReScript mode)
16 | 2. `npm install @pgtyped/runtime pg rescript @rescript/core` (`@pgtyped/runtime` and `pg` are the only required runtime dependencies of pgtyped)
17 | 3. Create a PgTyped `pgtyped.config.json` file.
18 | 4. Run `npx pgtyped-rescript -w -c pgtyped.config.json` to start PgTyped in watch mode.
19 |
20 | ### Example of setting up and running `pgtyped-rescript`
21 |
22 | Here's a sample `pgtyped.config.json` file:
23 |
24 | ```json
25 | {
26 | "transforms": [
27 | {
28 | "mode": "sql",
29 | "include": "**/*.sql",
30 | "emitTemplate": "{{dir}}/{{name}}__sql.res"
31 | },
32 | {
33 | "mode": "res",
34 | "include": "**/*.res",
35 | "emitTemplate": "{{dir}}/{{name}}__sql.res"
36 | }
37 | ],
38 | "srcDir": "./src",
39 | "dbUrl": "postgres://pgtyped:pgtyped@localhost/pgtyped"
40 | }
41 | ```
42 |
43 | > Notice how we're configuring what we want the generated ReScript files to be named under `emitTemplate`. For SQL-in-ReScript mode, you need to configure the generated file names exactly as above.
44 |
45 | Please refer to the `pgtyped` docs for all configuration options.
46 |
47 | ## Separate SQL files mode
48 |
49 | `pgtyped-rescript` supports writing queries in separate SQL files, as well as embedded directly in ReScript source code. Below details the separate SQL files approach:
50 |
51 | Create a SQL file anywhere in `src`. We call this one `books.sql`. Add your queries, together with `@name` comments naming them uniquely within the current file:
52 |
53 | ```sql
54 | /* @name findBookById */
55 | SELECT * FROM books WHERE id = :id!;
56 | ```
57 |
58 | After running `npx pgtyped-rescript -c pgtyped.config.json` we should get a `books__sql.res` file, with a module `FindBookById` with various functions for executing the query. Here's a full example of how we can connect to a database, and use that generated function to query it:
59 |
60 | ```rescript
61 | open PgTyped
62 |
63 | external env: {..} = "process.env"
64 |
65 | let dbConfig = {
66 | Pg.Client.host: env["PGHOST"]->Option.getWithDefault("127.0.0.1"),
67 | user: env["PGUSER"]->Option.getWithDefault("pgtyped"),
68 | password: env["PGPASSWORD"]->Option.getWithDefault("pgtyped"),
69 | database: env["PGDATABASE"]->Option.getWithDefault("pgtyped"),
70 | port: env["PGPORT"]->Option.flatMap(port => Int.fromString(port))->Option.getWithDefault(5432),
71 | }
72 |
73 | let client = Pg.Client.make(dbConfig)
74 |
75 | let main = async () => {
76 | await client->Pg.Client.connect
77 |
78 | let res = await client->Books__sql.FindBookById.one({id: 1})
79 | Console.log(res)
80 |
81 | await client->Pg.Client.end
82 | }
83 |
84 | main()->Promise.done
85 | ```
86 |
87 | ## SQL-in-ReScript
88 |
89 | Optionally, you can write SQL directly in your ReScript code and have a seamless, fully typed experience. The above example but with SQL-in-ReScript:
90 |
91 | ```rescript
92 | let query = %sql.one(`
93 | SELECT * FROM books WHERE id = :id!
94 | `)
95 |
96 | let res = await client->query({id: 1})
97 | Console.log(res)
98 | ```
99 |
100 | Notice that with the `%sql` tags, **there's no requirement to name your queries**. You can still name them if you want, but you don't have to.
101 |
102 | In order for this mode to work, you need one more thing - configure the `rescript-embed-lang` PPX in `rescript.json`:
103 |
104 | ```json
105 | "ppx-flags": ["rescript-embed-lang/ppx"],
106 | ```
107 |
108 | With that, you should be able to write queries directly in your ReScript source, and with the `watch` mode enabled have a seamless experience with types autogenerated and wired up for you.
109 |
110 | ## API
111 |
112 | ### `PgTyped`
113 |
114 | The package comes with minimal bindings to be able to set up a `pg` client. Please feel free to open issues for anything that's missing. It's also easy to add your own bindings locally by using `@send` and binding them to `PgTyped.Pg.Client.t`, like:
115 |
116 | ```rescript
117 | // Imagine `end` didn't have bindings
118 | @send external end: PgTyped.Pg.Client.t => promise
88 |
94 |
89 | {features.map((props, idx) => (
90 |
93 | sql template string literal.
28 |
29 | ),
30 | },
31 | {
32 | title: <>Prevent SQL injections,
33 | imageUrl: 'img/integrity.svg',
34 | description: (
35 | <>
36 | PgTyped prevents SQL injections by separately sending queries and
37 | parameters to the DB for execution. This allows parameter substitution
38 | to be safely done by the PostgreSQL server
39 |
40 | ),
41 | },
42 | ];
43 |
44 | function Feature({ imageUrl, title, description }) {
45 | const imgUrl = useBaseUrl(imageUrl);
46 | return (
47 |
48 | {imgUrl && (
49 |
56 | );
57 | }
58 |
59 | function Home() {
60 | const context = useDocusaurusContext();
61 | const { siteConfig = {} } = context;
62 | return (
63 |
50 | 
51 |
52 | )}
53 |
51 | {title}
54 |{description}
55 |
69 |
83 | {siteConfig.title}
70 |{siteConfig.tagline}
71 |
72 |
79 | Get Started
80 |
81 |
82 |