diff --git a/docs/docs/orm-support.md b/docs/docs/orm-support.md index 678bec263..60889c3a1 100644 --- a/docs/docs/orm-support.md +++ b/docs/docs/orm-support.md @@ -192,3 +192,60 @@ const pgliteDb = await getPGliteInstance() Check [TypeORM documentation](https://typeorm.io/data-source) and [typeorm-pglite](https://github.com/muraliprajapati/typeorm-pglite) documentation for more details. + +## Nano Queries + +[Nano Queries](https://nano-queries.js.org/) is a database-agnostic state of the art query builder. + +It work everywhere JavaScript can be run, build a safe queries for anything, including PGLite. + +Features to highlight: +- That is not an ORM. It is a 100% natural query builder +- Simple API to build complex queries +- Laziness. First-class support for dynamic query building and lateral query extension +- Nested queries +- Easy to extend. Build your own modules from primitives + +Nano Queries by its design does not require any "drivers"/"adapters"/"compilers" or any other addons to work with PGLite: + +```javascript +import { PGlite } from '@electric-sql/pglite'; +import { ConfigurableSQLBuilder, SQLCompiler } from 'nano-queries'; + +// SQL builder must be configured once +const { sql, compile, where } = new ConfigurableSQLBuilder( + new SQLCompiler({ + getPlaceholder(valueIndex) { + return '$' + (valueIndex + 1); + }, + }), +); + +const userInput = { + year: 2007, + rating: 4.1, +}; + + +// You may nest one query into another +const filter = where(); +const query = sql`SELECT title FROM movies ${filter} LIMIT 100`; + +// A query segment can be extended any time before compiling +filter.and(sql`release_year = ${userInput.year}`); + +// That's useful to build a complex conditional queries +if (userInput.rating > 0) { + filter.and(sql`rating >= ${userInput.rating}`); +} + +const movies = compile(query); +// { +// sql: 'SELECT title FROM movies WHERE release_year = $1 AND rating >= $2 LIMIT 100', +// bindings: [2007, 4.1], +// } + +await db.query(movies.sql, movies.bindings); +``` + +[Run this demo](https://stackblitz.com/edit/stackblitz-starters-rxhqvgfr?file=pglite.js&view=editor) with movies data in a sandbox & play.