From 55634d422bd532115221a98055ec7480256205df Mon Sep 17 00:00:00 2001 From: Kasper Marstal Date: Tue, 20 Feb 2024 12:03:23 -0800 Subject: [PATCH] Update README with suggestions from Show HN post (https://news.ycombinator.com/item?id=39428609) (#22) --- DESIGN.md | 2 +- README.md | 53 +++++++++++++++++++++++++++++------------------------ 2 files changed, 30 insertions(+), 25 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 866f710..15f75ea 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,6 +1,6 @@ # Introduction -PL/PRQL implements a Procedural Language handler (PL) for the Pipelined Relation Query Language (PRQL). The purpose of this document is to describe the extension's design and foster constructive dialogue with PRQL developers, aligning design decisions and user experiences. +PL/PRQL implements a Procedural Language handler (PL) for the Pipelined Relation Query Language ([PRQL](https://prql-lang.org)). The purpose of this document is to describe the extension's design and foster constructive dialogue with PRQL developers, aligning design decisions and user experiences. ## Scope diff --git a/README.md b/README.md index 8337c53..6af1e3b 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,10 @@ # PRQL in PostgreSQL! -PL/PRQL is a PostgreSQL extension that lets you write functions with PRQL. The extension supports PostgreSQL v12-16 on Linux and macOS. +PL/PRQL is a PostgreSQL extension that lets you write functions with [PRQL](https://prql-lang.org/). The extension supports PostgreSQL v12-16 on Linux and macOS. ## What is PRQL? -PRQL (Pipelined Relational Query Language) is an open-source query language for data manipulation and analysis that compiles to SQL. PRQL introduces a pipeline concept (similar to Unix pipes) where data is transformed line-by-line. The sequential series of transformations reduces the complexity often encountered with nested SQL queries and makes your data manipulation logic easier to read and write. +PRQL (Pipelined Relational Query Language) is an open source query language for data manipulation and analysis that compiles to SQL. PRQL introduces a pipeline concept (similar to Unix pipes) that transforms data line-by-line. The sequential series of transformations reduces the complexity often encountered with nested SQL queries and makes your data manipulation logic easier to read and write. ## Key features - [Write functions with PRQL](#functions) - Useful for large analytical queries @@ -44,7 +44,7 @@ This is similar to how PL/Python, PL/Javascript, and PL/Rust are implemented. ### PRQL Compiler -You can use the PRQL compiler to see the SQL statements that PostgreSQL executes under the hood. You compile PRQL to SQL with the `prql_to_sql()` function: +You can use the PRQL compiler to see the SQL statements that PostgreSQL executes under the hood. You can compile the above PRQL example to SQL with the `prql_to_sql()` function: ```sql select prql_to_sql(...); -- statements above omitted for brevity @@ -52,24 +52,14 @@ select prql_to_sql(...); -- statements above omitted for brevity prql_to_sql ------------- WITH table_0 AS ( - SELECT - player, - COALESCE(SUM(kills), 0) AS _expr_0, - COALESCE(SUM(deaths), 0) AS _expr_1 - FROM - matches - WHERE - match_id = $1 - GROUP BY - player + SELECT player, COALESCE(SUM(kills), 0) AS _expr_0, COALESCE(SUM(deaths), 0) AS _expr_1 + FROM matches + WHERE match_id = $1 + GROUP BY player ) -SELECT - player, - _expr_0 / _expr_1 AS kd_ratio -FROM - table_0 -WHERE - _expr_1 > 0 +SELECT player, _expr_0 / _expr_1 AS kd_ratio +FROM table_0 +WHERE _expr_1 > 0 -- Generated by PRQL compiler version:0.11.1 (https://prql-lang.org) (1 row) ``` @@ -103,6 +93,21 @@ For more information on PRQL, visit the PRQL [website](https://prql-lang.org/), > PRQL supports `select` statements only. `insert`, `update`, and `delete` statements, and your other database code, will continue to live in vanilla SQL, ORMs, or other database frameworks. ## Getting Started +### Install Deb File +Follow these steps to install deb file: + +1. Download the deb file that matches your operating system from the [Releases](https://github.com/kaspermarstal/plprql/releases/) page. +2. Open a terminal and change to the directory where the `.deb` file was downloaded. Install the package with dpkg, e.g.: + + ```cmd + sudo dpkg -i plprql-0.1.0-postgresql-16-debian-bookworm-amd64.deb + ``` +3. If dpkg reports missing dependencies, run the following command to fix them: + + ```cmd + sudo apt-get install -f + ``` + ### Install From Source Follow either of these steps to install from source: @@ -123,7 +128,7 @@ Follow either of these steps to install from source: ``` ### Set Up Development Environment -Follow these steps to set up your development environment: +PL/PRQL is built on top of the [pgrx](https://github.com/pgcentralfoundation/pgrx) framework for writing PostgreSQL extensions in Rust. This framework comes with development tools that you need to install. Follow these steps to set up your development environment: 1. Install `cargo-pgrx`. @@ -139,13 +144,13 @@ Follow these steps to set up your development environment: ``` where `` is the path to your system installation's `pg_config` tool (typically `/usr/bin/pg_config`). Supported versions are PostgreSQL v12-16. You can also run `cargo pgrx init` and have `pgrx` download, install, and compile PostgreSQL v12-16. These installations are managed by `pgrx` and used for development and testing. Individual `pgrx`-managed installations can be installed using e.g. `cargo pgrx init --pg16 download`. -3. Clone this repository and `cd` into root directory. +3. Clone this repository. ```cmd git clone https://github.com/kaspermarstal/plprql ``` -4. Install the extension to the PostgreSQL specified by +4. `cd` into root directory and install the extension to the PostgreSQL specified by the `pg_config` currently on your `$PATH`. ```cmd cd plprql/plprql @@ -169,7 +174,7 @@ Follow these steps to set up your development environment: psql> select match_stats(1); ``` -## Running Tests +### Running Tests You can run tests using `cargo pgrx test pg16`. Unit tests are in the main `plprql` crate while integration tests are in the `plprql-tests` crate. From the root source directory: ```cmd