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

Copy edits

Browse Source
This commit is contained in:
dannykng committed 2023-02-02 15:42:13 -08:00
1 parent f36746c064
commit 4e0092cd7b
4 files changed
+54 -84
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

apps/docs/pages/guides/database/extensions/hypopg.mdx
+19 -31
View File
@@ -6,11 +6,7 @@ export const meta = {
description: 'Quickly check if an index can be used without creating it.',
}
`HypoPG` is PostgreSQL extension for creating hypothetical/virtual indexes.
## Overview
HypoPG allows users to rapidly create hypothetical/virtual indexes that have no resource cost (CPU, disk, memory) that are visible to the PostgreSQL query planner.
`HypoPG` is PostgreSQL extension for creating hypothetical/virtual indexes. HypoPG allows users to rapidly create hypothetical/virtual indexes that have no resource cost (CPU, disk, memory) that are visible to the PostgreSQL query planner.
That allows users to quickly search for an index to improve a slow query without waiting for them to build.
## Usage
@@ -48,9 +44,9 @@ It's good practice to create the extension within a separate schema (like `exten
</TabPanel>
</Tabs>
### Speeding up a Query
### Speeding up a query
Given a table populated with some data and simple query to select from the table by id
Given the following table and a simple query to select from the table by id:
```sql
create table account (
@@ -66,17 +62,11 @@ from
generate_series(1, 10000) id;
```
we can generate an explain plan for a description of how the PostgreSQL query planner
intends to execute the query.
We can generate an explain plan for a description of how the PostgreSQL query planner
intends to execute the query.
```sql
explain
select
*
from
account
where
id = 1;
explain select * from account where id=1;
QUERY PLAN
-------------------------------------------------------
@@ -85,14 +75,15 @@ where
(2 rows)
```
Using HypoPG, we can create a hypothetical index on the `account(id)` column to check if it would be useful to the query planner and then re-run the explain plan.
Using HypoPG, we can create a hypothetical index on the `account(id)` column to check if it would be useful to the query planner and then re-run the explain plan.
Note that the virtual indexes created by HypoPG are only visible in the PostgreSQL connection that they were created in. Supabase Studio connects to PostgreSQL through a connection pooler so the `hypopg_create_index` statement and the `explain` statement should be executed in a single query.
Note that the virtual indexes created by HypoPG are only visible in the PostgreSQL connection that they were created in. Supabase connects to PostgreSQL through a connection pooler so the `hypopg_create_index` statement and the `explain` statement should be executed in a single query.
```sql
select * from hypopg_create_index('create index on account(id)');
explain select * from account where id=1;
QUERY PLAN
------------------------------------------------------------------------------------
Index Scan using <13504>btree_account_id on hypo (cost=0.29..8.30 rows=1 width=13)
@@ -100,28 +91,25 @@ explain select * from account where id=1;
(2 rows)
```
The query plan has changed from a `Seq Scan` to an `Index Scan` using the newly created virtual index, so we may choose to create a real version of the index with:
The query plan has changed from a `Seq Scan` to an `Index Scan` using the newly created virtual index, so we may choose to create a real version of the index to improve performance on the target query:
```sql
create index on account(id);
```
to improve performance on the target query.
## Functions
API:
- [`hypo_create_index(text)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#create-a-hypothetical-index): A function to create a hypothetical index
- [`hypopg_list_indexes`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A View that lists all hypothetical indexes that have been created
- [`hypopg()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function that lists all hypothetical indexes that have been created with the same format as pg_index
- [`hypopg_get_index_def(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to display the `create index` statement that would create the index
- [`hypopg_get_relation_size(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to estimate how large a hypothetical index would be
- [`hypopg_drop_index(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove a given hypothetical index by oid
- [`hypopg_reset()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove all hypothetical indexes
- [`hypo_create_index(text)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#create-a-hypothetical-index): A function to create a hypothetical index.
- [`hypopg_list_indexes`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A View that lists all hypothetical indexes that have been created.
- [`hypopg()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function that lists all hypothetical indexes that have been created with the same format as pg_index.
- [`hypopg_get_index_def(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to display the `create index` statement that would create the index.
- [`hypopg_get_relation_size(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to estimate how large a hypothetical index would be.
- [`hypopg_drop_index(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove a given hypothetical index by oid.
- [`hypopg_reset()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove all hypothetical indexes.
## Resources
- Official [`HypoPG` documentation](https://hypopg.readthedocs.io/en/rel1_stable/)
- Official [HypoPG documentation](https://hypopg.readthedocs.io/en/rel1_stable/)
export const Page = ({ children }) => <Layout meta={meta} children={children} />
apps/docs/pages/guides/database/extensions/pg_jsonschema.mdx
+6 -10
View File
@@ -6,11 +6,7 @@ export const meta = {
description: 'Validate json/jsonb with JSON Schema in PostgreSQL.',
}
[`pg_jsonschema`](https://json-schema.org) is a PostgreSQL extension adding support for JSON schema validation on json and jsonb data types.
## Overview
[JSON Schema](https://json-schema.org) is a language for annotating and validating JSON documents. `pg_jsonschema` adds the ability to validate PostgreSQL's builtin `json` and `jsonb` data types against a JSON Schema document.
[JSON Schema](https://json-schema.org) is a language for annotating and validating JSON documents. [`pg_jsonschema`](https://json-schema.org) is a PostgreSQL extension that adds the ability to validate PostgreSQL's built-in `json` and `jsonb` data types against a JSON Schema document.
## Usage
@@ -47,14 +43,14 @@ It's good practice to create the extension within a separate schema (like `exten
</TabPanel>
</Tabs>
API:
## Functions
- [`json_matches_schema(schema json, instance json)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `json` *instance* conforms to a JSON Schema *schema*.
- [`jsonb_matches_schema(schema json, instance jsonb)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `jsonb` *instance* conforms to a JSON Schema *schema*.
- [`json_matches_schema(schema json, instance json)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `json` _instance_ conforms to a JSON Schema _schema_.
- [`jsonb_matches_schema(schema json, instance jsonb)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `jsonb` _instance_ conforms to a JSON Schema _schema_.
### Validating a Document
### Validating a document
Since `pg_jsonschema` exposes its utilities as functions, we can test it with a simple select statement
Since `pg_jsonschema` exposes its utilities as functions, we can test it with a simple select statement:
```sql
select
apps/docs/pages/guides/database/extensions/pg_stat_statements.mdx
+18 -26
View File
@@ -3,32 +3,24 @@ import Layout from '~/layouts/DefaultGuideLayout'
export const meta = {
id: 'pg_stat_statements',
title: 'pg_stat_statements: SQL Planning and Execution Statistics',
description: 'Track planning and execution statistics of all SQL statements executed on the database.',
description:
'Track planning and execution statistics of all SQL statements executed on the database.',
}
`pg_stat_statements` is a database extension for tracking planning and execution statistics about all SQL statements executed on the database.
`pg_stat_statements` is a database extension that exposes a view, of the same name, to track statistics about SQL statements executed on the database. The following table shows some of the available statistics and metadata:
## Overview
`pg_stat_statements` exposes a view, of the same name, that tracks statistics about SQL statements executed on the database. The following table shows some of the available statistics and metadata:
```markdown
| Column Type | Description |
|-------------|-------------|
| userid oid (references pg_authid.oid) | OID of user who executed the statement |
| dbid oid (references pg_database.oid) | OID of database in which the statement was executed |
| toplevel bool | True if the query was executed as a top-level statement (always true if pg_stat_statements.track is set to top) |
| queryid bigint | Hash code to identify identical normalized queries. |
| query text | Text of a representative statement |
| plans bigint | Number of times the statement was planned (if pg_stat_statements.track_planning is enabled, otherwise zero) |
| total_plan_time double precision
| Total time spent planning the statement, in milliseconds (if pg_stat_statements.track_planning is enabled, otherwise zero) |
| min_plan_time double precision | Minimum time spent planning the statement, in milliseconds (if pg_stat_statements.track_planning is enabled, otherwise zero) |
| ... | ... |
```
A full list of statistics is available in the [`pg_stat_statements` docs](https://www.postgresql.org/docs/current/pgstatstatements.html)
| Column Type | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| userid oid (references pg_authid.oid) | OID of user who executed the statement |
| dbid oid (references pg_database.oid) | OID of database in which the statement was executed |
| toplevel bool | True if the query was executed as a top-level statement (always true if pg_stat_statements.track is set to top) |
| queryid bigint | Hash code to identify identical normalized queries. |
| query text | Text of a representative statement |
| plans bigint | Number of times the statement was planned (if pg_stat_statements.track_planning is enabled, otherwise zero) |
| total_plan_time double precision | Total time spent planning the statement, in milliseconds (if pg_stat_statements.track_planning is enabled, otherwise zero) |
| min_plan_time double precision | Minimum time spent planning the statement, in milliseconds (if pg_stat_statements.track_planning is enabled, otherwise zero) |
A full list of statistics is available in the [pg_stat_statements docs](https://www.postgresql.org/docs/current/pgstatstatements.html).
## Usage
@@ -65,9 +57,9 @@ It's good practice to create the extension within a separate schema (like `exten
</TabPanel>
</Tabs>
### Inspecting Activity
### Inspecting activity
A common use for `pg_stat_statements` is to track down expensive or slow queries. The `pg_stat_statements` view contains a row for each executed query with statistics inlined. You can leverage the statistics to, for example, identify frequently executed and slow queries against a given table
A common use for `pg_stat_statements` is to track down expensive or slow queries. The `pg_stat_statements` view contains a row for each executed query with statistics inlined. For example, you can leverage the statistics to identify frequently executed and slow queries against a given table.
```sql
select
@@ -88,11 +80,11 @@ order by
calls desc
```
From the results, an informed decision about which queries to optimize/index/adjust can be made.
From the results, an informed decision about which queries to optimize, index, or adjust can be made.
## Resources
- Official [`pg_stat_statements` documentation](https://www.postgresql.org/docs/current/pgstatstatements.html)
- Official [pg_stat_statements documentation](https://www.postgresql.org/docs/current/pgstatstatements.html)
export const Page = ({ children }) => <Layout meta={meta} children={children} />
apps/docs/pages/guides/database/extensions/pgroonga.mdx
+11 -17
View File
@@ -43,9 +43,9 @@ It's good practice to create the extension within a separate schema (like `exten
</TabPanel>
</Tabs>
### Creating a Full Text Search Index
### Creating a full text search index
Given a table with a `text` column
Given a table with a `text` column:
```sql
create table memos (
@@ -54,7 +54,7 @@ create table memos (
);
```
We can index the column for full text search with a `pgroonga` index
We can index the column for full text search with a `pgroonga` index:
```sql
create index ix_memos_content ON memos USING pgroonga(content);
@@ -71,23 +71,17 @@ values
('There is groonga command.');
```
The PostgreSQL query planner is smart enough to know that, for extremely small tables, its faster to scan the whole table rather than loading an index. To force the index to be used, we can disable sequential scans
The PostgreSQL query planner is smart enough to know that, for extremely small tables, it's faster to scan the whole table rather than loading an index. To force the index to be used, we can disable sequential scans:
```sql
-- For testing only. Don't do this in production
set enable_seqscan = off;
```
Now if we run an explain plan on a query filtering on `memos.content`,
Now if we run an explain plan on a query filtering on `memos.content`:
```sql
explain
select
*
from
memos
where
content like '%engine%';
explain select * from memos where content like '%engine%';
QUERY PLAN
-----------------------------------------------------------------------------
@@ -96,17 +90,17 @@ Index Scan using ix_memos_content on memos (cost=0.00..1.11 rows=1 width=36)
(2 rows)
```
The pgroonga index is used to retrive the result set
The pgroonga index is used to retrive the result set:
```markdown
| id | content |
| -- | ------------------------------------------------------------------------ |
| 2 | 'Groonga is a fast full text search engine that supports all languages.' |
| id | content |
| --- | ------------------------------------------------------------------------ |
| 2 | 'Groonga is a fast full text search engine that supports all languages.' |
```
## Resources
- Official [`PGroonga` documentation](https://pgroonga.github.io/tutorial/)
- Official [PGroonga documentation](https://pgroonga.github.io/tutorial/)
export const Page = ({ children }) => <Layout meta={meta} children={children} />