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

Rename UI -> Dashboard (part 1)

Browse Source
This commit is contained in:
dannykng committed 2022-08-08 17:44:58 -07:00
1 parent 73670c6cbd
commit 60616cefa8
11 files changed
+355 -602
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

web/docs/guides/api.mdx
+75 -101
View File
@@ -24,7 +24,7 @@ The APIs are:
- **Scalable.** <br />The API can serve thousands of simultaneous requests, and works well for Serverless workloads.
### REST API
### REST API {#rest-api-overview}
Supabase provides a RESTful API using [PostgREST](https://postgrest.org/). This is a very thin API layer on top of Postgres.
It provides everything you need from a CRUD API:
@@ -45,7 +45,7 @@ It provides everything you need from a CRUD API:
allowFullScreen
></iframe>
### GraphQL API
### GraphQL API {#graphql-api-overview}
:::note
@@ -55,7 +55,7 @@ GraphQL is in Beta, and may have breaking changes. It is only available on self-
GraphQL in Supabase works through [pg_graphql](https://supabase.com/blog/2021/12/03/pg-graphql), an open source PostgreSQL extension for GraphQL.
### Realtime API
### Realtime API {#realtime-api-overview}
Supabase provides a Realtime API using [Realtime](https://github.com/supabase/realtime). You can use this to listen to database changes over websockets.
Realtime leverages PostgreSQL's built-in logical replication. You can manage your Realtime API simply by managing Postgres publications.
@@ -69,33 +69,33 @@ All APIs are auto-created from Database tables. After you have added tables or f
API routes are automatically created when you create Postgres Tables, Views, or Functions.
Let's create our first
API route by creating a table called `todos` (which will store some public user information).
This will create a corresponding route `todos` which can accept `GET`, `POST`, `PATCH`, & `DELETE` requests.
API route by creating a table called `todos` to store tasks.
This creates a corresponding route `todos` which can accept `GET`, `POST`, `PATCH`, & `DELETE` requests.
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
groupId="dashboard-or-sql"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
```sh
1. Go to the "Table editor" section.
2. Click "New Table".
3. Enter the table name "todos".
4. Click "Save".
5. Click "New Column".
6. Enter the column name "task" and make the type "text".
7. Click "Save".
```
<TabItem value="dashboard">
1. Go to the [Table editor](https://app.supabase.com/project/_/editor) page in the Dashboard.
2. Click **New Table**.
3. Enter "todos" for the Name.
4. Click **Save**.
5. Click **New Column**.
6. Enter "task" for the Name and "text" as the Type.
7. Click **Save**.
<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-create-table-sm.mp4" type="video/mp4" muted playsInline />
</video>
</TabItem>
<TabItem value="SQL">
<TabItem value="sql">
```sql
-- Create a table called "todos" with a column to store tasks.
@@ -113,13 +113,9 @@ create table todos (
Every Supabase project has a unique API URL. Your API is secured behind an API gateway which requires an API Key for every request.
```sh
1. Go to the "Settings" section.
2. Click "API" in the sidebar.
3. Find your API URL in this page.
4. Find your "anon" and "service_role" keys on this page.
```
1. Go to the [Settings](https://app.supabase.com/project/_/settings/general) page in the Dashboard.
2. Click **API** in the sidebar.
3. Find your API `URL`, `anon`, and `service_role` keys on this page.
<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-url-and-key.mp4" type="video/mp4" muted playsInline />
@@ -134,42 +130,27 @@ Both of these routes require the `anon` key to be passed through an `apikey` hea
#### API Keys
You can find the Keys inside the Dashboard in the same location as the URL above.
You are provided with two keys:
- an `anon` key, which is safe to be used in a browser context.
- a `service_role` key, which should only be used on a server. This key can bypass Row Level Security. NEVER use this key in a browser.
### Accessing the Docs
### Accessing the docs in the Dashboard
#### REST API
#### REST API {#rest-api-dashboard-docs}
Supabase generates documentation in the Dashboard which updates as you make database changes.
Supabase generates documentation in the [Dashboard](https://app.supabase.com) which updates as you make database changes.
Let's view the documentation for a `countries` table which we created in our database.
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'}
]}>
<TabItem value="UI">
```sh
1. Go to the "API" section.
2. Find "todos" in the "Tables and Views" section.
1. Go to the [API](https://app.supabase.com/project/_/api) page in the Dashboard.
2. Find the `countries` table under **Tables and Views** in the sidebar.
3. Switch between the JavaScript and the cURL docs using the tabs.
```
<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-docs.mp4" type="video/mp4" muted playsInline />
</video>
</TabItem>
</Tabs>
#### GraphQL
The GraphQL Endpoint that we provide (`https://<project_ref>.supabase.co/graphql/v1`) is compatible with any GraphiQL implementation that can pass an `apikey` header.
@@ -192,12 +173,14 @@ using the API URL (`SUPABASE_URL`) and Key (`SUPABASE_ANON_KEY`) we provided:
<Tabs
defaultValue="JavaScript"
values={[
{label: 'JavaScript', value: 'JavaScript'},
{label: 'cURL', value: 'cURL'},
]}>
<TabItem value="JavaScript">
groupId="language"
defaultValue="javascript"
values={[
{label: 'JavaScript', value: 'javascript'},
{label: 'cURL', value: 'curl'},
]}>
<TabItem value="javascript">
```javascript
// Initialize the JS client
@@ -211,7 +194,7 @@ const { data: todos, error } = await supabase
```
</TabItem>
<TabItem value="cURL">
<TabItem value="curl">
```bash
# Append /rest/v1/ to your URL, and then use the table name as the route
@@ -243,12 +226,14 @@ Be sure to rebuild the GraphQL schema after altering the SQL schema.
You can use any GraphQL client with the Supabase GraphQL API. For our GraphQL example we will use [urql](https://formidable.com/open-source/urql/docs/).
<Tabs
defaultValue="Javascript"
values={[
{label: 'Javascript', value: 'Javascript'},
{label: 'cURL', value: 'cURL'},
]}>
<TabItem value="Javascript">
groupId="language"
defaultValue="javascript"
values={[
{label: 'JavaScript', value: 'javascript'},
{label: 'cURL', value: 'curl'},
]}>
<TabItem value="javascript">
```javascript
import { createClient, useQuery } from 'urql'
@@ -292,7 +277,7 @@ const { data, fetching, error } = result
```
</TabItem>
<TabItem value="cURL">
<TabItem value="curl">
```bash
# Append /graphql/v1/ to your URL, and then use the table name as the route
@@ -311,26 +296,26 @@ curl --request POST '<SUPABASE_URL>/graphql/v1' \
By default Realtime is disabled on your database. Let's turn on Realtime for the `todos` table.
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
groupId="dashboard-or-sql"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
```sh
1. Go to the "Database" section.
2. Click on "Replication" in the sidebar.
3. Control which database events are sent by toggling the Insert/Update/Delete toggles.
4. Control which tables broadcast changes by clicking into the "Source" and toggling the tables.
```
<TabItem value="dashboard">
1. Go to the [Database](https://app.supabase.com/project/_/database/tables) page in the Dashboard.
2. Click on **Replication** in the sidebar.
3. Control which database events are sent by toggling **Insert**, **Update**, and **Delete**.
4. Control which tables broadcast changes by selecting **Source** and toggling each table.
<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-realtime.mp4" type="video/mp4" muted playsInline />
</video>
</TabItem>
<TabItem value="SQL">
<TabItem value="sql">
```sql
alter publication supabase_realtime add table todos;
@@ -339,14 +324,7 @@ alter publication supabase_realtime add table todos;
</TabItem>
</Tabs>
Now we can listen to any new data that is inserted into the `todos` table:
<Tabs
defaultValue="Javascript"
values={[
{label: 'Javascript', value: 'Javascript'}
]}>
<TabItem value="Javascript">
From the client, we can listen to any new data that is inserted into the `todos` table:
```javascript
// Initialize the JS client
@@ -365,9 +343,6 @@ const { data: todos, error } = await supabase
.subscribe()
```
</TabItem>
</Tabs>
Use [subscribe()](/docs/reference/javascript/subscribe) to listen to database changes.
The Realtime API works through PostgreSQL's replication functionality. Postgres sends database changes to a [publication](/docs/guides/database/replication#publications)
called `supabase_realtime`, and by managing this publication you can control which data is broadcast.
@@ -378,26 +353,26 @@ called `supabase_realtime`, and by managing this publication you can control whi
### Securing your Routes
Your API is designed to work with Postgres Row Level Security. If you use Supabase [Auth](/docs/guides/auth), you can restrict data based on the logged-in user.
Your API is designed to work with Postgres Row Level Security (RLS). If you use Supabase [Auth](/docs/guides/auth), you can restrict data based on the logged-in user.
To control access to your data, you can use [Policies](/docs/guides/auth#policies).
When you create a table in Postgres, Row Level Security is disabled by default. Make sure you secure it by [enabling RLS](/docs/guides/api#securing-your-routes).
When you create a table in Postgres, Row Level Security is disabled by default. To enable RLS:
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
groupId="dashboard-or-sql"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
```sh
1. Go to the "Authentication" section.
2. Click on "Policies" in the sidebar.
3. Click "Enable RLS" to enable Row Level Security.
```
<TabItem value="dashboard">
1. Go to the [Authentication](https://app.supabase.com/project/_/auth/users) page in the Dashboard.
2. Click on **Policies** in the sidebar.
3. Select **Enable RLS** to enable Row Level Security.
</TabItem>
<TabItem value="SQL">
<TabItem value="sql">
```sql
alter table todos enable row level security;
@@ -408,7 +383,6 @@ alter table todos enable row level security;
### The `service_role` key
Never expose the `service_role` key in a browser or anywhere where a user can see it. This Key can is designed to bypass Row Level Security - so it should only be used on a private server.
We have [partnered with GitHub](https://supabase.com/blog/2022/03/28/community-day#supabase-is-now-a-github-secret-scanning-partner) to scan for Supabase `service_role` keys pushed to public repositories.
web/docs/guides/database/arrays.mdx
+42 -47
View File
@@ -7,26 +7,23 @@ description: How to use arrays in PostgreSQL and the Supabase API.
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
PostgreSQL supports flexible [array types](https://www.postgresql.org/docs/12/arrays.html).
These arrays are also supported in the Supabase dashboard and in the JavaScript API.
PostgreSQL supports flexible [array types](https://www.postgresql.org/docs/12/arrays.html). These arrays are also supported in the Supabase Dashboard and in the JavaScript API.
## Steps
### Create a table with an array column
## Create a table with an array column
Create a test table with a text array (an array of strings):
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
groupId="dashboard-or-sql"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
<TabItem value="UI">
<TabItem value="dashboard">
```bash
1. Got the Table Editor
1. Go to the Table Editor
2. Create a New Table
3. Create a new table named `arraytest` and save the table
- New Column
@@ -34,11 +31,10 @@ values={[
- Make it type `text`
- Check the box labelled `Define as array`
- Save the new column
```
</TabItem>
<TabItem value="SQL">
<TabItem value="sql">
```sql
CREATE TABLE arraytest (id integer NOT NULL, textarray text ARRAY);
@@ -47,30 +43,29 @@ CREATE TABLE arraytest (id integer NOT NULL, textarray text ARRAY);
</TabItem>
</Tabs>
### Insert a record with an array value
## Insert a record with an array value
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
{label: 'JS', value: 'JavaScript'},
]}>
groupId="dashboard-or-sql"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
{label: 'JS', value: 'javascript'},
]}>
<TabItem value="UI">
<TabItem value="dashboard">
```bash
- Table Editor
- Select `arraytest`
- Insert Row
- In the `textarray` field input, paste:
- `["Harry", "Larry", "Moe"]`
- Save the new row
```
</TabItem>
<TabItem value="SQL">
<TabItem value="sql">
```sql
INSERT INTO arraytest (id, textarray) VALUES (1, ARRAY['Harry', 'Larry', 'Moe']);
@@ -78,8 +73,8 @@ INSERT INTO arraytest (id, textarray) VALUES (1, ARRAY['Harry', 'Larry', 'Moe'])
</TabItem>
<TabItem value="JavaScript">
To insert a record from the JavaScript client:
<TabItem value="javascript">
Insert a record from the JavaScript client:
```js
const { data, error } = await supabase
@@ -91,21 +86,20 @@ const { data, error } = await supabase
</Tabs>
### View the results
## View the results
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
groupId="dashboard-or-sql"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
<TabItem value="UI">
<TabItem value="dashboard">
```bash
- Table Editor
- Select `arraytest`
```
Your first array data!
@@ -114,7 +108,7 @@ Your first array data!
| 1 | ["Harry","Larry","Moe"] |
</TabItem>
<TabItem value="SQL">
<TabItem value="sql">
```sql
SELECT * FROM arraytest;
@@ -129,18 +123,19 @@ Your first array data!
</TabItem>
</Tabs>
### Query Array Data
## Query array data
To query an array, PostgreSQL uses 1-based arrays, so be careful, since you're probably used to 0-based arrays in JavaScript.
<Tabs
defaultValue="SQL"
values={[
{label: 'SQL', value: 'SQL'},
{label: 'JS', value: 'JavaScript'},
]}>
groupId="dashboard-or-sql"
defaultValue="sql"
values={[
{label: 'SQL', value: 'sql'},
{label: 'JS', value: 'javascript'},
]}>
<TabItem value="SQL">
<TabItem value="sql">
To select the first item from the array and get the total length of the array:
@@ -155,7 +150,8 @@ returns:
| Harry | 3 |
</TabItem>
<TabItem value="JavaScript">
<TabItem value="javascript">
This returns the entire array field:
@@ -175,7 +171,6 @@ returns:
```
</TabItem>
</Tabs>
## Resources
web/docs/guides/database/connecting-to-postgres.mdx
+2 -18
View File
@@ -38,30 +38,14 @@ We provides several types of API to suit your preferences and use-case:
You cannot manage the database schema via the API (for security reasons). To do that you can use the dashboard or connect directly to your database.
### Finding your API URL
### API URL and Keys
You can find the API URL and Keys inside the Dashboard.
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'}
]}>
<TabItem value="UI">
```sh
1. Go to the "Settings" section.
2. Click "API" in the sidebar.
3. Find your API URL and Keys in this page.
```
You can find the API URL and Keys in the [Dashboard](https://app.supabase.com/project/_/settings/api).
<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-url-and-key.mp4" type="video/mp4" muted playsInline />
</video>
</TabItem>
</Tabs>
## Direct connections
Every Supabase project provides a full Postgres database. You can connect to the database using any tool which supports Postgres.
web/docs/guides/database/extensions.mdx
+16 -22
View File
@@ -14,47 +14,41 @@ Supabase has pre-installed some of the most useful open source extensions.
### Enable and disable extensions
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
```sh
1. Go to the Database page
2. Click on "Extensions" in the sidebar
3. Find the extension you would like to enable/disable
4. Click the toggle.
```
<TabItem value="dashboard">
1. Go to the [Database](https://app.supabase.com/project/_/database/tables) page in the Dashboard.
2. Click **Extensions** in the sidebar.
3. Enable or disable an extension.
<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
<TabItem value="sql">
```sql
-- Example: enable the "pgtap" extension and ensure it is installed
create extension pgtap with schema extensions;
-- Example: disable the "pgtap" extension
drop extension 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`.
To disable an extension call `drop extension`.
Enabling few extensions by the SQL code `create extension <extension-name> with schema extensions` may lead to permission issues (e.g. `dblink`, `http`, `pg_cron`).
:::caution
Enabling some extensions with `create extension <extension-name> with schema extensions` may lead to permission issues (e.g., `dblink`, `http`, `pg_cron`).
:::
</TabItem>
@@ -63,6 +57,6 @@ Enabling few extensions by the SQL code `create extension <extension-name> with
### Full list of extensions
Supabase is pre-configured with over 50 extensions. You can also install your own SQL extensions directly into the database through our SQL editor.
Supabase is pre-configured with over 50 extensions. You can also install your own SQL extensions directly in the database through our SQL editor.
<ExtensionsComponent />
web/docs/guides/database/extensions/http.mdx
+14 -20
View File
@@ -37,40 +37,34 @@ You can use the `http` extension to make these network requests from Postgres.
## Usage
### Enabling
### Enable the extension
<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.
```
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
<TabItem value="dashboard">
1. Go to the [Database](https://app.supabase.com/project/_/database/tables) page in the Dashboard.
2. Click on **Extensions** in the sidebar.
3. Search for "http" and enable the extension.
</TabItem>
<TabItem value="SQL">
```sql
<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`.
To disable an extension, call `drop extension`.
It's good practice to create the extension within a separate schema (like `extensions`) to keep your database clean.
@@ -125,4 +119,4 @@ from
## 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
+14 -21
View File
@@ -16,43 +16,36 @@ 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
### Enable the extension
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
```sh
1. Go to the Database page.
2. Click on "Extensions" in the sidebar.
3. Search for "pgtap".
4. Click the toggle.
```
<TabItem value="dashboard">
1. Go to the [Database](https://app.supabase.com/project/_/database/tables) page in the Dashboard.
2. Click on **Extensions** in the sidebar.
3. Search for "pgtap" and enable the extension.
<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
<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".
@@ -130,4 +123,4 @@ API:
## Resources
- Official [`pgTAP` documentation](https://pgtap.org/).
- Official [`pgTAP` documentation](https://pgtap.org/)
web/docs/guides/database/extensions/plv8.mdx
+27 -38
View File
@@ -18,47 +18,41 @@ It can be used for database functions, triggers, queries and more.
## Usage
### Enabling
### Enable the extension
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
```sh
1. Go to the Database page.
2. Click on "Extensions" in the sidebar.
3. Search for "plv8".
4. Click the toggle.
```
<TabItem value="dashboard">
1. Go to the [Database](https://app.supabase.com/project/_/database/tables) page in the Dashboard.
2. Click on **Extensions** in the sidebar.
3. Search for "plv8" and enable the extension.
</TabItem>
<TabItem value="SQL">
```sql
<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`.
To disable an extension, 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
### Create `plv8` functions
Functions written in `plv8` are written just like any other PostgreSQL functions, only
with the `language` identifier set to `plv8`.
@@ -74,28 +68,24 @@ $$ 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">
defaultValue="sql"
values={[
{label: 'SQL', value: 'sql'},
{label: 'JavaScript', value: 'javascript'},
]}>
<TabItem value="sql">
```sql
select function_name();
```
</TabItem>
<TabItem value="JS">
```js
<TabItem value="javascript">
```js
const { data, error } = supabase.rpc('function_name')
```
</TabItem>
@@ -103,7 +93,7 @@ const { data, error } = supabase.rpc('function_name')
## Examples
### Scalar Functions
### 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.
@@ -134,7 +124,7 @@ returns smallint as $$
$$ language plv8;
```
### Set-returning Functions
### 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.
@@ -150,8 +140,7 @@ returns setof messages as $$
$$ language plv8;
```
## 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
+15 -19
View File
@@ -17,38 +17,34 @@ This makes them particularly well suited as Primary Keys. It is occasionally ref
## Usage
### Enabling
### Enable the extension
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
```sh
1. Go to the Database page.
2. Click on "Extensions" in the sidebar.
3. Search for "uuid-ossp".
4. Click the toggle.
```
<TabItem value="dashboard">
1. Go to the [Database](https://app.supabase.com/project/_/database/tables) page in the Dashboard.
2. Click on **Extensions** in the sidebar.
3. Search for "uuid-ossp" and enable the extension.
</TabItem>
<TabItem value="SQL">
```sql
<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`.
To disable an extension, call `drop extension`.
It's good practice to create the extension within a separate schema (like `extensions`) to keep your database clean.
@@ -93,4 +89,4 @@ create table contacts (
## Resources
- [The Basics Of PostgreSQL `UUID` Data Type](https://www.postgresqltutorial.com/postgresql-uuid/).
- [The Basics Of PostgreSQL `UUID` Data Type](https://www.postgresqltutorial.com/postgresql-uuid/)
web/docs/guides/database/json.mdx
+81 -115
View File
@@ -10,21 +10,42 @@ import TabItem from '@theme/TabItem'
PostgreSQL supports [JSON functions and operators](https://www.postgresql.org/docs/current/functions-json.html) which gives flexibility when storing data inside a database column.
PostgreSQL supports two types of JSON columns: `JSON` and `JSONB`.
The recommended type is `JSONB` for almost all cases.
When you use the `JSONB` format, the data is parsed when it's put into the database so it's faster when querying and also it can be indexed.
## Steps
### Create a table with a JSON column.
## Create a table with a JSON column
<Tabs
defaultValue="SQL"
values={[
{label: 'SQL', value: 'SQL'},
{label: 'UI', value: 'UI'},
]}>
<TabItem value="SQL">
groupId="json"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
<TabItem value="dashboard">
1. Go to the [Table Editor](https://app.supabase.com/project/_/editor) page in the Dashboard.
2. Click **New Table** and create a table called `books`.
3. Include a primary key with the following properties:
- Name: `id`
- Type: `int8`
- Default value: `Automatically generate as indentity`
4. Click **Save**.
5. Click **New Column** and add 3 columns with the following properties:
- **title** column
- Name: `title`
- Type: `text`
- **author** column
- Name: `author`
- Type: `text`
- **metadata** column
- Name: `metadata`
- Type: `jsonb`
</TabItem>
<TabItem value="sql">
```sql
create table books (
@@ -35,51 +56,25 @@ create table books (
);
```
</TabItem>
<TabItem value="UI">
```sh
Create the table:
1. Go to the Table Editor
2. Click "New Table"
3. Name the table "books"
4. Include a primary key with the following properties:
- Name: "id"
- Type: "int8"
- Default value: "Automatically generate as indentity"
5. Click "Save"
Click "New Column" and 3 new columns with the following properties:
1. title column:
- Name: "title"
- Type: "text"
2. author column:
- Name: "author"
- Type: "text"
3. metadata column:
- Name: "metadata"
- Type: "jsonb"
```
</TabItem>
</Tabs>
### Insert data into the table.
## Insert data into the table
<Tabs
defaultValue="Data"
values={[
{label: 'Data', value: 'Data'},
{label: 'SQL', value: 'SQL'},
{label: 'UI', value: 'UI'},
{label: 'JS', value: 'JavaScript'},
]}>
<TabItem value="Data">
groupId="json"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
{label: 'JavaScript', value: 'javascript'},
]}>
<TabItem value="dashboard">
1. Go to the [Table Editor](https://app.supabase.com/project/_/editor) page in the Dashboard.
2. Select the `books` table in the sidebar.
3. Click **+ Insert Row** and add 5 rows with the following properties:
| id | title | author | metadata |
| --- | ----------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
@@ -90,7 +85,8 @@ values={[
| 5 | Harry Potter and the Goblet of Fire | J.K. Rowling | {"ages":[10,99],"price":24.95,"description":"Fourth year of school starts, big drama ensues."} |
</TabItem>
<TabItem value="SQL">
<TabItem value="sql">
```sql
insert into books
@@ -124,40 +120,8 @@ values
```
</TabItem>
<TabItem value="UI">
```bash
- click `Table Editor`
- click `books`
- click `+ Insert Row`
- `title`: `The Poky Little Puppy`
- `author`: 'Janette Sebring Lowrey'
- `metadata`: {"description":"Puppy is slower than other, bigger animals.","price":5.95,"ages":[3,6]}
- click `Save`
- click `+ Insert Row`
- `title`: `The Tale of Peter Rabbit`
- `author`: 'Beatrix Potter'
- `metadata`: {"ages":[2,5],"price":4.49,"description":"Rabbit eats some vegetables."}
- click `Save`
- click `+ Insert Row`
- `title`: `Tootle`
- `author`: 'Gertrude Crampton'
- `metadata`: {"ages":[2,5],"price":3.99,"description":"Little toy train has big dreams."}
- click `Save`
- click `+ Insert Row`
- `title`: `Green Eggs and Ham`
- `author`: 'Dr. Seuss'
- `metadata`: {"ages":[4,8],"price":7.49,"description":"Sam has changing food preferences and eats unusually colored food."}
- click `Save`
- click `+ Insert Row`
- `title`: `Harry Potter and the Goblet of Fire`
- `author`: 'J.K. Rowling'
- `metadata`: {"ages":[10,99],"price":24.95,"description":"Fourth year of school starts, big drama ensues."}
- click `Save`
```
</TabItem>
<TabItem value="JavaScript">
<TabItem value="javascript">
```js
const { data, error } = await supabase.from('books').insert([
@@ -204,16 +168,18 @@ const { data, error } = await supabase.from('books').insert([
</TabItem>
</Tabs>
### View the data.
## View the data
<Tabs
defaultValue="SQL"
values={[
{label: 'SQL', value: 'SQL'},
{label: 'JS', value: 'JavaScript'},
{label: 'Data', value: 'Data'},
]}>
<TabItem value="SQL">
groupId="json"
defaultValue="sql"
values={[
{label: 'SQL', value: 'sql'},
{label: 'JavaScript', value: 'javascript'},
{label: 'Result', value: 'result'},
]}>
<TabItem value="sql">
```sql
select *
@@ -221,7 +187,8 @@ from books;
```
</TabItem>
<TabItem value="JavaScript">
<TabItem value="javascript">
```js
const { data, error } = await supabase.from('books').select('*')
@@ -229,7 +196,8 @@ console.log(JSON.stringify(data, null, 2))
```
</TabItem>
<TabItem value="Data">
<TabItem value="result">
| id | title | author | metadata |
| --- | ----------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
@@ -239,26 +207,25 @@ console.log(JSON.stringify(data, null, 2))
| 4 | Green Eggs and Ham | Dr. Seuss | {"ages":[4,8],"price":7.49,"description":"Sam has changing food preferences and eats unusually colored food."} |
| 5 | Harry Potter and the Goblet of Fire | J.K. Rowling | {"ages":[10,99],"price":24.95,"description":"Fourth year of school starts, big drama ensues."} |
NOTICE: The data as it appears here will have the `JSONB` fields in a different order than when we inserted them.
As we said earlier about the differences between the `JSON` and `JSONB` fields:
> When you use the `JSONB` format, the data is parsed when it's put into the database...
The data as it appears here has the `JSONB` fields in a different order than when inserted. As mentioned earlier, data is parsed as its inserted when using the JSONB format.
</TabItem>
</Tabs>
### Query the `JSONB` data.
## Query the `JSONB` data
#### Select title, description, price, and age range for each book.
Select the title, description, price, and age range for each book.
<Tabs
defaultValue="SQL"
values={[
{label: 'SQL', value: 'SQL'},
{label: 'JS', value: 'JavaScript'},
{label: 'Results', value: 'Results'}
]}>
<TabItem value="SQL">
groupId="json"
defaultValue="sql"
values={[
{label: 'SQL', value: 'sql'},
{label: 'JavaScript', value: 'javascript'},
{label: 'Result', value: 'result'}
]}>
<TabItem value="sql">
```sql
select
@@ -272,7 +239,8 @@ from
```
</TabItem>
<TabItem value="JavaScript">
<TabItem value="javascript">
```js
const { data, error } = await supabase
@@ -284,7 +252,8 @@ console.log(JSON.stringify(data, null, 2))
```
</TabItem>
<TabItem value="Results">
<TabItem value="result">
| title | description | price | low_age | high_age |
| ----------------------------------- | ------------------------------------------------------------------ | ----- | ------- | -------- |
@@ -297,16 +266,13 @@ console.log(JSON.stringify(data, null, 2))
</TabItem>
</Tabs>
#### Data Types
Note that the `->` operator returns JSONB data. If you want TEXT/STRING data returned, use the `->>` operator.
One last thing to note: the -> operator returns JSONB data. If you want TEXT/STRING data returned, you need to use the ->> operator.
- metadata -> 'description' (this returns a JSON object)
- metadata ->> 'description' (this returns STRING/TEXT data)
- metadata -> 'description' (returns a JSON object)
- metadata ->> 'description' (returns STRING/TEXT data)
## Resources
- [Supabase Account - Free Tier OK](https://supabase.com)
- [Supabase JS Client](https://github.com/supabase/supabase-js)
- [PostgreSQL: JSON Functions and Operators](https://www.postgresql.org/docs/12/functions-json.html)
- [PostgreSQL JSON types](https://www.postgresql.org/docs/12/datatype-json.html)
web/docs/guides/database/replication.mdx
+18 -156
View File
@@ -8,126 +8,48 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Replication is technique for copying the data from one database to another. This is useful for:
Replication is a technique for copying the data from one database to another. Supabase uses replication functionality to provide a real-time API. Replication is useful for:
- Spreading out the "load". For example, if your database has a lot of reads, you might want to split it between two databases.
- Spreading out the "load." For example, if your database has a lot of reads, you might want to split it between two databases.
- Reducing latency. For example, you may want one database in London to serve your European customers, and one in New York to serve the US.
- In Supabase's case, we use the built-in replication functionality to provide a real-time API.
Replication is done through _publications_, a method of choosing which changes to send to other systems (usually another Postgres database). Publications can be managed in the [Dashboard](https://app.supabase.com) or with SQL.
## Manage publications in the Dashboard
## Publications
Publications are a way of choosing which changes should be sent to other systems (usually another Postgres database).
### Managing Publications
Supabase provides an interface for managing your publications, or you can use SQL.
<Tabs
defaultValue="UI"
values={[
{label: 'UI', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
```sh
1. Go to the "Database" section.
2. Click on "Replication" in the sidebar.
3. Control which database events are sent by toggling the Insert/Update/Delete toggles.
4. Control which tables broadcast changes by clicking into the "Source" and toggling the tables.
```
1. Go to the [Database](https://app.supabase.com/project/_/database/tables) page in the Dashboard.
2. Click on **Replication** in the sidebar.
3. Control which database events are sent by toggling **Insert**, **Update**, and **Delete**.
4. Control which tables broadcast changes by selecting **Source** and toggling each table.
<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-realtime.mp4" type="video/mp4" muted playsInline />
</video>
</TabItem>
<TabItem value="SQL">
## Create a publication
```sql
alter publication supabase_realtime add table products;
```
</TabItem>
</Tabs>
### Create a Publication
This publication will contain all changes to all tables.
<Tabs
defaultValue="sql"
groupId="reference/postgres"
values={[{ label: 'SQL', value: 'sql' }]}>
<TabItem value="sql">
This publication contains changes to all tables.
```sql
create publication publication_name
for all tables;
```
</TabItem>
</Tabs>
### Create a Publication which listens to individual tables
<Tabs
defaultValue="sql"
groupId="reference/postgres"
values={[{ label: 'SQL', value: 'sql' }]}>
<TabItem value="sql">
## Create a publication to listen to individual tables
```sql
create publication publication_name
for table table_one, table_two;
```
</TabItem>
</Tabs>
### Add tables to an existing publication
<Tabs
defaultValue="sql"
groupId="reference/postgres"
values={[{ label: 'SQL', value: 'sql' }]}>
<TabItem value="sql">
## Add tables to an existing publication
```sql
alter publication publication_name
add table table_name;
```
</TabItem>
</Tabs>
### Listen to `insert`
<Tabs
defaultValue="sql"
groupId="reference/postgres"
values={[{ label: 'SQL', value: 'sql' }]}>
<TabItem value="sql">
## Listen to `insert`
```sql
create publication publication_name
@@ -135,21 +57,7 @@ for all tables
with (publish = 'insert');
```
</TabItem>
</Tabs>
### Listen to `update`
<Tabs
defaultValue="sql"
groupId="reference/postgres"
values={[{ label: 'SQL', value: 'sql' }]}>
<TabItem value="sql">
## Listen to `update`
```sql
create publication publication_name
@@ -157,21 +65,7 @@ for all tables
with (publish = 'update');
```
</TabItem>
</Tabs>
### Listen to `delete`
<Tabs
defaultValue="sql"
groupId="reference/postgres"
values={[{ label: 'SQL', value: 'sql' }]}>
<TabItem value="sql">
## Listen to `delete`
```sql
create publication publication_name
@@ -179,42 +73,15 @@ for all tables
with (publish = 'delete');
```
</TabItem>
</Tabs>
### Remove a Publication
<Tabs
defaultValue="sql"
groupId="reference/postgres"
values={[{ label: 'SQL', value: 'sql' }]}>
<TabItem value="sql">
## Remove a publication
```sql
drop publication if exists publication_name;
```
## Recreate a publication
</TabItem>
</Tabs>
### Recreate a Publication
If you are planning to re-create a publication, it's best to do it in a transaction to ensure the operation succeeds.
<Tabs
defaultValue="sql"
groupId="reference/postgres"
values={[{ label: 'SQL', value: 'sql' }]}>
<TabItem value="sql">
If you're recreating a publication, it's best to do it in a transaction to ensure the operation succeeds.
```sql
begin;
@@ -225,8 +92,3 @@ begin;
create publication publication_name;
commit;
```
</TabItem>
</Tabs>
web/docs/guides/database/tables.mdx
+51 -45
View File
@@ -34,29 +34,27 @@ We provide a SQL editor within the Dashboard, or you can [connect](/docs/guides/
and run the SQL queries yourself.
<Tabs
defaultValue="UI"
values={[
{label: 'Dashboard', value: 'UI'},
{label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">
groupId="dashboard-or-sql"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
<TabItem value="dashboard">
<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-create-table-sm.mp4" type="video/mp4" muted playsInline />
</video>
```sh
1. Go to the "Table editor" section.
2. Click "New Table".
3. Enter the table name "todos".
4. Click "Save".
5. Click "New Column".
6. Enter the column name "task" and make the type "text".
7. Click "Save".
```
1. Go to the [Table Editor](https://app.supabase.com/project/_/editor) page in the Dashboard.
2. Click **New Table** and create a table with the name `todos`.
3. Click **Save**.
4. Click **New Column** and create a column with the name `task` and type `text`.
5. Click **Save**.
</TabItem>
<TabItem value="SQL">
<TabItem value="sql">
```sql
create table movies (
@@ -69,7 +67,9 @@ create table movies (
</TabItem>
</Tabs>
It is best practice to use lowercase and underscores when naming tables. For example: `table_name`, not `Table Name`.
:::note
When naming tables, use lowercase and underscores instead of spaces (e.g., `table_name`, not `Table Name`).
:::
## Columns
@@ -173,13 +173,14 @@ Use the "Bulk Loading" instructions if you are loading large data sets.
### Basic data loading
<Tabs
defaultValue="SQL"
values={[
{label: 'SQL', value: 'SQL'},
{label: 'JavaScript', value: 'JS'},
{label: 'Dart', value: 'DART'},
]}>
<TabItem value="SQL">
defaultValue="sql"
values={[
{label: 'SQL', value: 'sql'},
{label: 'JavaScript', value: 'javascript'},
{label: 'Dart', value: 'dart'},
]}>
<TabItem value="sql">
```sql
insert into movies
@@ -190,7 +191,8 @@ values
```
</TabItem>
<TabItem value="JS">
<TabItem value="javascript">
```sql
const { data, error } = await supabase
@@ -205,7 +207,8 @@ const { data, error } = await supabase
```
</TabItem>
<TabItem value="DART">
<TabItem value="dart">
```sql
final res = await supabase
@@ -270,12 +273,28 @@ For example if you had the following situations:
- An `actor` can perfom in several movies.
<Tabs
defaultValue="SQL"
values={[
{label: 'SQL', value: 'SQL'},
{label: 'Dashboard', value: 'UI'},
]}>
<TabItem value="SQL">
groupId="dashboard-or-sql"
defaultValue="dashboard"
values={[
{label: 'Dashboard', value: 'dashboard'},
{label: 'SQL', value: 'sql'},
]}>
<TabItem value="dashboard">
<iframe
className="video-with-border w-full"
width="640"
height="420"
src="https://www.youtube-nocookie.com/embed/TKwF3IGij5c"
frameBorder="1"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
</TabItem>
<TabItem value="sql">
```sql
create table movies (
@@ -296,19 +315,6 @@ create table performances (
);
```
</TabItem>
<TabItem value="UI">
<iframe
className="video-with-border w-full"
width="640"
height="420"
src="https://www.youtube-nocookie.com/embed/TKwF3IGij5c"
frameBorder="1"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
</TabItem>
</Tabs>