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

cleans up docs - focus only on what's needed for now

Browse Source
This commit is contained in:
Copple committed 2022-08-02 12:38:42 +02:00
1 parent dbd8678163
commit f59b078cdf
6 files changed
+13 -513
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

apps/reference/docs/postgres/extensions/http.mdx
-123
View File
@@ -1,123 +0,0 @@
---
id: http
title: 'http: RESTful Client'
description: An HTTP Client for PostgreSQL Functions.
---
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
The `http` extension allows you to call RESTful endpoints within Postgres.
## Quick demo
<iframe
className="w-full video-with-border"
width="640"
height="385"
src="https://www.youtube-nocookie.com/embed/rARgrELRCwY"
frameBorder="1"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
## Overview
Let's cover some basic concepts:
- REST: stands for REpresentational State Transfer. It's simply 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
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
```sh
1. Go to the Database page.
2. Click on "Extensions" in the sidebar.
3. Search for "http".
4. Click the toggle.
```
</TabItem>
<TabItem value="SQL">
```sql
-- Example: enable the "http" extension
create extension http with schema extensions;
-- Example: disable the "http" extension
drop extension if exists http;
```
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`.
It's good practice to create the extension within a separate schema (like `extensions`) to keep your database clean.
</TabItem>
</Tabs>
### Available functions
While the main usage is simply `http('http_request')`, there are 5 wrapper functions for specific functionality:
- `http_get()`
- `http_post()`
- `http_put()`
- `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
### Simple `GET` example
```sql
select
"status", "content"::jsonb
from
http_get('https://jsonplaceholder.typicode.com/todos/1');
```
### Simple `POST` example
```sql
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).
apps/reference/docs/postgres/extensions/intro.mdx
-5
View File
@@ -1,5 +0,0 @@
---
id: intro
---
Some info about extensions.
apps/reference/docs/postgres/extensions/pgtap.mdx
-129
View File
@@ -1,129 +0,0 @@
---
id: pgtap
title: 'pgTAP: Unit Testing'
description: Unit testing in PostgreSQL.
---
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
`pgTAP` is a unit testing extension for PostgreSQL.
## Overview
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.
## Usage
### Enabling
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
```sh
1. Go to the Database page.
2. Click on "Extensions" in the sidebar.
3. Search for "pgtap".
4. Click the toggle.
```
<video width="99%" muted playsInline controls={true}>
<source
src="/docs/videos/toggle-extensions.mp4"
type="video/mp4"
muted
playsInline
/>
</video>
</TabItem>
<TabItem value="SQL">
```sql
-- Enable the "pgtap" extension
create extension pgtap with schema extensions;
-- Disable the "pgtap" extension
drop extension if exists pgtap;
```
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`.
It's good practice to create the extension within a separate schema (like `extensions`) to keep your database clean.
</TabItem>
</Tabs>
### Managing tests
It's a good practice to keep all your tests in a separate schema.
```sql
create schema tests;
```
### Creating a test
@TODO
- Create a plan
- We should come up with a recommendation on how to run the tests. Via a function? External scripts?
- Eventually this can be done via our CLI
### Running a test
@TODO
## Examples
Let's look at a few different tests which could be helpful in your project.
### Testing tables
```sql
begin;
select plan( 1 );
select has_table( 'profiles' );
select * from finish();
rollback;
```
API:
- [`has_table()`](https://pgtap.org/documentation.html#has_table)
### Testing columns
```sql
begin;
select plan( 1 );
select has_column( 'profiles', 'id' );
select col_is_pk( 'profiles', 'id' );
select * from finish();
rollback;
```
API:
- [`has_column()`](https://pgtap.org/documentation.html#has_column)
- [`col_is_pk()`](https://pgtap.org/documentation.html#col_is_pk)
## Resources
- Official [`pgTAP` documentation](https://pgtap.org/).
apps/reference/docs/postgres/extensions/plv8.mdx
-149
View File
@@ -1,149 +0,0 @@
---
id: plv8
title: 'plv8: JavaScript Language'
description: JavaScript language for PostgreSQL.
---
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
The `plv8` extension allows you use JavaScript within Postgres.
## Overview
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 JavaScript engine](https://v8.dev).
It can be used for database functions, triggers, queries and more.
## Usage
### Enabling
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
```sh
1. Go to the Database page.
2. Click on "Extensions" in the sidebar.
3. Search for "plv8".
4. Click the toggle.
```
</TabItem>
<TabItem value="SQL">
```sql
-- Example: enable the "plv8" extension
create extension plv8;
-- Example: disable the "plv8" extension
drop extension if exists plv8;
```
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`.
Procedural languages are automatically installed within `pg_catalog`, so you don't need to specify a schema.
</TabItem>
</Tabs>
### Creating `plv8` functions
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()
returns void as $$
// V8 JavaScript
// code
// here
$$ language plv8;
```
You can call `plv8` functions like any other Postgres function:
<Tabs
defaultValue="SQL"
values={[
{label: 'SQL', value: 'SQL'},
{label: 'JavaScript', value: 'JS'},
]}>
<TabItem value="SQL">
```sql
select function_name();
```
</TabItem>
<TabItem value="JS">
```js
const { data, error } = supabase.rpc('function_name')
```
</TabItem>
</Tabs>
## Examples
### Scalar Functions
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 hello_world(name text)
returns text as $$
let output = `Hello, ${name}!`;
return output;
$$ language plv8;
```
### Executing SQL
You can execute SQL within `plv8` code using the [`plv8.execute` function](https://plv8.github.io/#plv8-execute).
```sql
create or replace function update_user(id bigint, first_name text)
returns smallint as $$
var num_affected = plv8.execute(
'update profiles set first_name = $1 where id = $2',
[first_name, id]
);
return num_affected;
$$ language plv8;
```
### 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
create or replace function get_messages()
returns setof messages as $$
var json_result = plv8.execute(
'select * from messages'
);
return json_result;
$$ language plv8;
```
## Resources
- Official [`plv8` documentation](https://plv8.github.io/).
- [plv8 GitHub Repository](https://github.com/plv8/plv8).
apps/reference/docs/postgres/extensions/uuid-ossp.mdx
-94
View File
@@ -1,94 +0,0 @@
---
id: uuid-ossp
title: 'uuid-ossp: Unique Identifiers'
description: A UUID generator for PostgreSQL.
---
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
The `uuid-ossp` extension can be used to generate a `UUID`.
## Overview
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
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
```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 extension "uuid-ossp" with schema extensions;
-- Example: disable the "uuid-ossp" extension
drop extension if exists "uuid-ossp";
```
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`.
It's good practice to create the extension within a separate schema (like `extensions`) to keep your database clean.
</TabItem>
</Tabs>
### The `uuid` type
Once the extension is enabled, you now have access to a `uuid` type.
### `uuid_generate_v1()`
Creates a UUID value based on the combination of computer’s MAC address, current timestamp, and a random value.
### `uuid_generate_v4()`
Creates UUID values based solely on random numbers.
## Examples
### Within a query
```sql
select uuid_generate_v4();
```
### As a Primary Key
Automatically create a unique, random ID in a table:
```sql
create table contacts (
id uuid default uuid_generate_v4(),
first_name text,
last_name text,
primary key (id)
);
```
## Resources
- [The Basics Of PostgreSQL `UUID` Data Type](https://www.postgresqltutorial.com/postgresql-uuid/).
apps/reference/nav/_referenceSidebars.js
+13 -13
View File
@@ -40,21 +40,21 @@ const sidebars = {
{
type: 'category',
label: 'Tools',
collapsed: true,
collapsed: false,
items: [{ type: 'link', label: 'GoTrue Auth Server', href: '/gotrue' }],
},
{
type: 'category',
label: 'Postgres Extensions',
link: { type: 'doc', id: 'postgres/extensions/intro' },
collapsed: true,
items: [
'postgres/extensions/http',
'postgres/extensions/pgtap',
'postgres/extensions/plv8',
'postgres/extensions/uuid-ossp',
],
},
// {
// type: 'category',
// label: 'Postgres Extensions',
// link: { type: 'doc', id: 'postgres/extensions/intro' },
// collapsed: true,
// items: [
// 'postgres/extensions/http',
// 'postgres/extensions/pgtap',
// 'postgres/extensions/plv8',
// 'postgres/extensions/uuid-ossp',
// ],
// },
],
}