dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-10 11:55:05 +03:00
Code Issues Packages Projects Releases Wiki Activity

Cleans up the extensions docs

Browse Source
This commit is contained in:
Paul Copplestone committed 2021-06-30 15:59:05 +08:00
1 parent ba06d61b87
commit 2f2d9ab75b
4 files changed
+123 -123
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

web/docs/guides/database/extensions/http.mdx
+38 -36
View File
@@ -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
<Tabs
defaultValue="UI"
@@ -34,9 +38,9 @@ values={[
<TabItem value="UI">
```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`.
</TabItem>
</Tabs>
## `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).
- Official [`http` Github Repository](https://github.com/pramsey/pgsql-http).
web/docs/guides/database/extensions/pgtap.mdx
+9 -11
View File
@@ -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
<Tabs
defaultValue="UI"
@@ -34,10 +32,10 @@ values={[
]}>
<TabItem value="UI">
```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`.
</TabItem>
web/docs/guides/database/extensions/plv8.mdx
+48 -43
View File
@@ -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
<Tabs
@@ -35,10 +31,10 @@ values={[
]}>
<TabItem value="UI">
```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`.
</TabItem>
</Tabs>
## 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).
- Official [`plv8` documentation](https://plv8.github.io/).
- [plv8 Github Repository](https://github.com/plv8/plv8).
web/docs/guides/database/extensions/uuid-ossp.mdx
+28 -33
View File
@@ -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
<Tabs
defaultValue="UI"
@@ -32,25 +28,23 @@ values={[
]}>
<TabItem value="UI">
```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.
```
</TabItem>
<TabItem value="SQL">
```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`.
</Tabs>
## `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)
);
```