From 2f2d9ab75b6950f47d75dcf866de691cfb20aecc Mon Sep 17 00:00:00 2001 From: Paul Copplestone Date: Wed, 30 Jun 2021 15:59:05 +0800 Subject: [PATCH] Cleans up the extensions docs --- web/docs/guides/database/extensions/http.mdx | 74 +++++++-------- web/docs/guides/database/extensions/pgtap.mdx | 20 ++-- web/docs/guides/database/extensions/plv8.mdx | 91 ++++++++++--------- .../guides/database/extensions/uuid-ossp.mdx | 61 ++++++------- 4 files changed, 123 insertions(+), 123 deletions(-) diff --git a/web/docs/guides/database/extensions/http.mdx b/web/docs/guides/database/extensions/http.mdx index bf454a730c7..6c0ac0ab3ca 100644 --- a/web/docs/guides/database/extensions/http.mdx +++ b/web/docs/guides/database/extensions/http.mdx @@ -1,6 +1,6 @@ --- id: http -title: "HTTP: HTTP Client" +title: "http: RESTful Client" description: An HTTP Client for PostgreSQL Functions. --- @@ -8,22 +8,26 @@ import ExtensionsComponent from '../../../../src/components/Extensions' import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`HTTP` is a HTTP Client extension for PostgreSQL. It can be used to make calls to HTTP REST API endpoints from inside your PostgreSQL functions. +The `http` extension allows you to call RESTful endpoints within Postgres. ## Overview -The `HTTP` extension allows you to make HTTP calls from inside your PostgreSQL functions, returning data back from API endpoints. -A successful call to a web URL from the `HTTP` extension returns a record with the following fields: `status`, `content_type`, `headers`, and `content`. +Let's cover some basic concepts: +- REST: stands for REpresentational State Transfer. It's simploy a way to request data from external services. +- RESTful APIs are servers which accept HTTP "calls". The calls are typically: + - `GET` − Read only access to a resource. + - `POST` − Creates a new resource. + - `DELETE` − Removes a resource. + - `PUT` − Updates an existing resource or creates a new resource. +You can use the `http` extension to make these network requests from Postgres. ## Usage -### Enabling `PLV8` - - +### Enabling ```bash -1. Go to the Database page -2. Click on "Extensions" in the sidebar -3. Find the extension you would like to enable/disable +1. Go to the Database page. +2. Click on "Extensions" in the sidebar. +3. Search for "http". 4. Click the toggle. ``` @@ -55,16 +59,16 @@ drop extenstion http; ``` -Even though the SQL code is `create extension`, this is the equivelent of "enabling the extension". +Even though the SQL code is `create extension`, this is the equivalent of "enabling the extension". To disable an extension you can call `drop extension`. -## `HTTP` functions +### Available functions -While the main `HTTP` function is simply `http(http_request)`, there are 5 wrapper functions for specific functionality: +While the main usage is simply `http('http_request')`, there are 5 wrapper functions for specific functionality: - `http_get()` - `http_post()` @@ -72,39 +76,37 @@ While the main `HTTP` function is simply `http(http_request)`, there are 5 wrapp - `http_delete()` - `http_head()` +### Returned values + +A successful call to a web URL from the `http` extension returns a record with the following fields: + +- `status`: integer +- `content_type`: character varying +- `headers`: http_header[] +- `content`: character varying. Typically you would want to cast this to `jsonb` using the format `content::jsonb` + ## Examples -### `HTTP GET` -Get a bunch of information about the current time (in JSON format): +### Simple `GET` example ```sql -SELECT content FROM http_get('http://worldtimeapi.org/api/ip'); +select "status", "content"::jsonb +from http_get('https://jsonplaceholder.typicode.com/todos/1'); ``` -Get the current ip address of the PostgreSQL server: + +### Simple `POST` example ```sql -SELECT content::json->>'origin' as ip FROM http_get('http://httpbin.org/ip'); -``` - -Get information on a food product: - -```sql -SELECT content::json as product FROM http_get('https://world.openfoodfacts.org/api/v0/product/9300650018860.json'); -``` - -### `HTTP POST` - -Post data to an API endpoint: - -```sql -SELECT status, content::JSON->'form' as form_result - FROM http_post('http://httpbin.org/post', - 'myvar=myval&foo=bar&special=' || urlencode('my special string & things?'), - 'application/x-www-form-urlencoded'); +select "status", "content"::jsonb +from http_post( + 'https://jsonplaceholder.typicode.com/posts', + '{ "title": "foo", "body": "bar", "userId": 1 }', + 'application/json' +); ``` ## Resources -- Official [`HTTP` Github Repository](https://github.com/pramsey/pgsql-http). \ No newline at end of file +- Official [`http` Github Repository](https://github.com/pramsey/pgsql-http). \ No newline at end of file diff --git a/web/docs/guides/database/extensions/pgtap.mdx b/web/docs/guides/database/extensions/pgtap.mdx index 46118b036b8..5205701a55f 100644 --- a/web/docs/guides/database/extensions/pgtap.mdx +++ b/web/docs/guides/database/extensions/pgtap.mdx @@ -12,7 +12,7 @@ import TabItem from '@theme/TabItem'; ## Overview -Before showing you how to write tests, let's cover some basic concepts: +Let's cover some basic concepts: - Unit tests: allow you to test small parts of a system (like a database table!). - TAP: stands for [Test Anything Protocol](http://testanything.org/). It is an framework which aims to simplify the error reporting during testing. @@ -22,9 +22,7 @@ Before showing you how to write tests, let's cover some basic concepts: ## Usage -### Enabling pgTAP - - +### Enabling -```bash -1. Go to the Database page -2. Click on "Extensions" in the sidebar -3. Find the extension you would like to enable/disable +```sh +1. Go to the Database page. +2. Click on "Extensions" in the sidebar. +3. Search for "pgtap". 4. Click the toggle. ``` @@ -54,14 +52,14 @@ values={[ ```sql -- Example: enable the "pgtap" extension -create extenstion pgtap; +create extension pgtap; -- Example: disable the "pgtap" extension -drop extenstion pgtap; +drop extension pgtap; ``` -Even though the SQL code is `create extension`, this is the equivelent of "enabling the extension". +Even though the SQL code is `create extension`, this is the equivalent of "enabling the extension". To disable an extension you can call `drop extension`. diff --git a/web/docs/guides/database/extensions/plv8.mdx b/web/docs/guides/database/extensions/plv8.mdx index afff10d5c34..42146e005ab 100644 --- a/web/docs/guides/database/extensions/plv8.mdx +++ b/web/docs/guides/database/extensions/plv8.mdx @@ -1,6 +1,6 @@ --- id: plv8 -title: "PLV8: Javascript Language" +title: "plv8: Javascript Language" description: Javascript language for PostgreSQL. --- @@ -8,23 +8,19 @@ import ExtensionsComponent from '../../../../src/components/Extensions' import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`PLV8` is a trusted Javascript language extension for PostgreSQL. It can be used for database functions, triggers, etc. +The `plv8` extension allows you use Javascript within Postgres. ## Overview -The `PLV8` extension allows you to write PostgreSQL functions using the [V8 Jasvascript engine](https://v8.dev). -It has its own runtime environment that can be customized with a runtime startup procedure (`set plv8.start_proc`) -and execution timeout period (`set plv8.execution_timeout`). It can execute multiple types of function calls inside of PostgreSQL -including `Scalar Function Calls`, `Set-returning Function Calls`, `Trigger Function Calls`, and more. - - +While Postgres natively runs SQL, it can also run other "procedural languages". +`plv8` allows you to run Javascript code - specifically any code that runs on the [V8 Jasvascript engine](https://v8.dev). +It can be used for database functions, triggers, queries and more. ## Usage -### Enabling `PLV8` - +### Enabling -```bash -1. Go to the Database page -2. Click on "Extensions" in the sidebar -3. Find the extension you would like to enable/disable +```sh +1. Go to the Database page. +2. Click on "Extensions" in the sidebar. +3. Search for "plv8". 4. Click the toggle. ``` @@ -50,32 +46,38 @@ values={[ ```sql -- Example: enable the "plv8" extension -create extenstion plv8; +create extension plv8; -- Example: disable the "plv8" extension -drop extenstion plv8; +drop extension plv8; ``` -Even though the SQL code is `create extension`, this is the equivelent of "enabling the extension". +Even though the SQL code is `create extension`, this is the equivalent of "enabling the extension". To disable an extension you can call `drop extension`. -## Creating `PLV8` functions +### Creating `plv8` functions -Functions written in `PLV8` (Javascript V8) are written just like any other PostgreSQL functions, only -with the `LANGUAGE` identifier set to `plv8`. +Functions written in `plv8` are written just like any other PostgreSQL functions, only +with the `language` identifier set to `plv8`. ```sql -CREATE OR REPLACE FUNCTION function_name(parameter1 text, parameter2 integer) RETURNS TEXT AS $$ +create or replace function function_name() +returns void as $$ // V8 Javascript // code // here - return 'return value'; -$$ LANGUAGE plv8; +$$ language plv8; +``` + +You can call `plv8` functions like any other Postgres function: + +```sql +select function_name(); ``` @@ -83,40 +85,43 @@ $$ LANGUAGE plv8; ### Scalar Functions -A simple Scalar Function. +A [scalar function](https://plv8.github.io/#scalar-function-calls) is anything that takes in some user input and returns a single result. ```sql -CREATE OR REPLACE FUNCTION HelloWorld(name text) RETURNS TEXT AS $$ - let output = `Hello from PLV8, ${name}!`; - output += ' The time is now ' + new Date(); +create or replace function hello_world(name text) +returns text as $$ + + let output = `Hello, ${name}!`; return output; -$$ LANGUAGE plv8; + +$$ language plv8; ``` -To test it: +### Set-returning Functions + +A [set-returning function](https://plv8.github.io/#set-returning-function-calls) is anything that returns a full set of results - for example, rows in a table. ```sql -SELECT HelloWorld('Harold'); +create or replace function get_rows() +returns text as $$ + + -- @TODO + +$$ language plv8; ``` -A simple Scalar Function to convert a string to proper case: -```sql -CREATE OR REPLACE FUNCTION ProperCase(str text) RETURNS TEXT AS $$ - return str.toLowerCase().replace(/^(.)|\s(.)/g, - function($1) { return $1.toUpperCase(); }); -$$ LANGUAGE plv8; -``` +## Configuration -To test it: +@TODO: break this down: -```sql -SELECT ProperCase('this is my title with all the words capitalized'); -``` +> It has its own runtime environment that can be customized with a runtime startup procedure (`set plv8.start_proc`) +and execution timeout period (`set plv8.execution_timeout`). It can execute multiple types of function calls inside of PostgreSQL +including `Scalar Function Calls`, `Set-returning Function Calls`, `Trigger Function Calls`, and more. ## Resources -- Official [`PLV8` documentation](https://plv8.github.io/). -- [PLV8 Github Repository](https://github.com/plv8/plv8). \ No newline at end of file +- Official [`plv8` documentation](https://plv8.github.io/). +- [plv8 Github Repository](https://github.com/plv8/plv8). \ No newline at end of file diff --git a/web/docs/guides/database/extensions/uuid-ossp.mdx b/web/docs/guides/database/extensions/uuid-ossp.mdx index e9153260100..f5561cd803b 100644 --- a/web/docs/guides/database/extensions/uuid-ossp.mdx +++ b/web/docs/guides/database/extensions/uuid-ossp.mdx @@ -1,6 +1,6 @@ --- id: uuid-ossp -title: "UUID-OSSP: Unique Identifiers" +title: "uuid-ossp: Unique Identifiers" description: A UUID generator for PostgreSQL. --- @@ -8,21 +8,17 @@ import ExtensionsComponent from '../../../../src/components/Extensions' import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`UUID-OSSP` is an extension for PostgreSQL that creates the ability to generate `Universally Unique Identifers`, also known as (`UUIDs`). +The `uuid-ossp` extension can be used to generate a `UUID`. + ## Overview -A universally unique identifier (`UUID`) is a 128-bit label used for information in computer systems. -- [Wikipedia](https://en.wikipedia.org/wiki/Universally_unique_identifier) -`UUID-OSSP` enables the following functions used to generate `UUIDs`: -- `uuid_generate_v1()` -- `uuid_generate_v4()` +A `UUID` is a "Universally Unique Identifer" and it is, for practical purposes, unique. +This makes them particularly well suited as Primary Keys. It is occasionally referred to as a `GUID`, which stands for "Globally Unique Identifer". ## Usage - -### Enabling `UUID-OSSP` - - +### Enabling -```bash -1. Go to the Database page -2. Click on "Extensions" in the sidebar -3. Find the extension you would like to enable/disable +```sh +1. Go to the Database page. +2. Click on "Extensions" in the sidebar. +3. Search for "uuid-ossp". 4. Click the toggle. ``` - - ```sql -- Example: enable the "uuid-ossp" extension -create extenstion "uuid-ossp"; +create extension "uuid-ossp"; -- Example: disable the "uuid-ossp" extension -drop extenstion "uuid-ossp"; +drop extension "uuid-ossp"; ``` @@ -61,36 +55,37 @@ To disable an extension you can call `drop extension`. -## `UUID` functions +## Available functions +There are two functions available: -To generate the UUID values based on the combination of computer’s MAC address, current timestamp, and a random value, you use the uuid_generate_v1() function: +### `uuid_generate_v1()` -```uuid_generate_v1()``` +Creates a UUID value based on the combination of computer’s MAC address, current timestamp, and a random value. -To generate a UUID value solely based on random numbers, use the uuid_generate_v4(): +### `uuid_generate_v4()` -```uuid_generate_v4()``` +Creates UUID values based solely on random numbers. ## Examples -Basic usage in a select statement: +### Within a query ```sql -SELECT uuid_generate_v1(); -SELECT uuid_generate_v4(); +select uuid_generate_v4(); ``` +### As a Primary Key + Automatically create a unique, random ID in a table: ```sql -CREATE TABLE contacts ( - contact_id uuid DEFAULT uuid_generate_v4(), - first_name VARCHAR NOT NULL, - last_name VARCHAR NOT NULL, - email VARCHAR NOT NULL, - phone VARCHAR, - PRIMARY KEY (contact_id) +create table contacts ( + id uuid default uuid_generate_v4(), + first_name text, + last_name text, + + primary key (id) ); ```