The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: Improve readability of page elements by LLM and AI tools (#47275)
Chris Chinchilla3c26fd071b1e
diff --git a/apps/docs/content/guides/ai/choosing-compute-addon.mdx b/apps/docs/content/guides/ai/choosing-compute-addon.mdxindex e4f8c1ae905..9243663b8f2 100644--- a/apps/docs/content/guides/ai/choosing-compute-addon.mdx+++ b/apps/docs/content/guides/ai/choosing-compute-addon.mdx@@ -120,8 +120,10 @@ It is possible to upload more vectors to a single table if Memory allows it (for</Admonition>+The chart below compares HNSW queries-per-second across compute sizes for different embedding dimensions.+<Image- alt="multi database"+ alt="Chart comparing HNSW queries-per-second across Supabase compute sizes for different embedding dimensions."src={{light: '/docs/img/ai/instance-type/hnsw-dims--light.png',dark: '/docs/img/ai/instance-type/hnsw-dims--dark.png',@@ -256,8 +258,10 @@ For 1,000,000 vectors 40 probes results to accuracy of 0.98. Note that exact val</TabPanel></Tabs>+The chart below plots requests-per-second against compute size.+<Image- alt="multi database"+ alt="Chart plotting requests-per-second against Supabase compute size."src={{light: '/docs/img/ai/going-prod/size-to-rps--light.png',dark: '/docs/img/ai/going-prod/size-to-rps--dark.png',@@ -294,8 +298,10 @@ You can increase the Requests per Second by increasing `m` and `ef_construction`><TabPanel id="hnsw" label="HNSW">+The chart below shows how the HNSW build parameters `m` and `ef_construction` affect requests-per-second on the dbpedia dataset.+<Image- alt="multi database"+ alt="Chart showing how HNSW build parameters (m and ef_construction) affect requests-per-second on the dbpedia dataset."src={{light: '/docs/img/ai/going-prod/dbpedia-hnsw-build-parameters--light.png',dark: '/docs/img/ai/going-prod/dbpedia-hnsw-build-parameters--dark.png',@@ -308,8 +314,10 @@ You can increase the Requests per Second by increasing `m` and `ef_construction`</TabPanel><TabPanel id="ivfflat" label="IVFFlat">+The chart below shows how the number of IVFFlat lists affects performance for one million vectors.+<Image- alt="multi database"+ alt="Chart showing how the number of IVFFlat lists affects performance for 1 million vectors."src={{light: '/docs/img/ai/instance-type/lists-for-1m--light.png',dark: '/docs/img/ai/instance-type/lists-for-1m--dark.png',@@ -329,7 +337,7 @@ Check out more tips and the complete step-by-step guide in [Going to ProductionWe follow techniques outlined in the [ANN Benchmarks](https://github.com/erikbern/ann-benchmarks) methodology. A Python test runner is responsible for uploading the data, creating the index, and running the queries. The pgvector engine is implemented using [vecs](https://github.com/supabase/vecs), a Python client for pgvector.<Image- alt="multi database"+ alt="Diagram of the vecs benchmark setup: a Python test runner uploads data, builds the index, and runs queries against pgvector."src={{light: '/docs/img/ai/instance-type/vecs-benchmark--light.png',dark: '/docs/img/ai/instance-type/vecs-benchmark--dark.png',@@ -340,6 +348,8 @@ We follow techniques outlined in the [ANN Benchmarks](https://github.com/erikber/>+_The diagram above shows the vecs benchmark setup: a Python test runner uploads data, builds the index, and runs queries against pgvector._+Each test is run for a minimum of 30-40 minutes. They include a series of experiments executed at different concurrency levels to measure the engine's performance under different load types. The results are then averaged.As a general recommendation, we suggest using a concurrency level of 5 or more for most workloads and 30 or more for high-load workloads.diff --git a/apps/docs/content/guides/ai/concepts.mdx b/apps/docs/content/guides/ai/concepts.mdxindex 264cbcc9860..357581cc455 100644--- a/apps/docs/content/guides/ai/concepts.mdx+++ b/apps/docs/content/guides/ai/concepts.mdx@@ -39,7 +39,14 @@ So how does this relate to embeddings?Embeddings compress discrete information (words & symbols) into distributed continuous-valued data (vectors). If we took our phrases from before and plot them on a chart, it might look something like this:-<img src="/docs/img/ai/vector-similarity.png" alt="Vector similarity" width="640" height="640" />+The chart below plots example phrases as points. Phrases with similar meanings sit close together, and unrelated phrases sit far apart.++<img+ src="/docs/img/ai/vector-similarity.png"+ alt="A two-dimensional chart plotting example phrases as points, where phrases with similar meanings sit close together and unrelated phrases sit far apart."+ width="640"+ height="640"+/>Phrases 1 and 2 would be plotted close to each other, since their meanings are similar. We would expect phrase 3 to live somewhere far away since it isn't related. If we had a fourth phrase, “Sally ate Swiss cheese”, this might exist somewhere between phrase 3 (cheese can go on sandwiches) and phrase 1 (mice like Swiss cheese).diff --git a/apps/docs/content/guides/ai/engineering-for-scale.mdx b/apps/docs/content/guides/ai/engineering-for-scale.mdxindex a9c74970bd7..225e4c6c835 100644--- a/apps/docs/content/guides/ai/engineering-for-scale.mdx+++ b/apps/docs/content/guides/ai/engineering-for-scale.mdx@@ -14,8 +14,10 @@ For small workloads, you can typically store your data in a single database.If you've used [Vecs](/docs/guides/ai/vecs-python-client) to create 3 different collections, you can expose collections to your web or mobile application using [views](/docs/guides/database/tables#views):+The diagram below shows a single database holding the three vector collections of `docs`, `posts`, and `images`. Each are exposed to your application through a view.+<Image- alt="single database"+ alt="Architecture diagram: a single Supabase database holding three vector collections (docs, posts, and images), each exposed to the application through a view."src={{light: '/docs/img/ai/scaling/engineering-for-scale--single-database--light.png',dark: '/docs/img/ai/scaling/engineering-for-scale--single-database--dark.png',@@ -51,8 +53,10 @@ const { data, error } = await supabaseAs you move into production, we recommend splitting your collections into separate projects. This is because it allows your vector stores to scale independently of your production data. Vectors typically grow faster than operational data, and they have different resource requirements. Running them on separate databases removes the single-point-of-failure.+The diagram below shows a primary database alongside separate secondary "pod" databases, each holding its own vector collection so they can scale independently.+<Image- alt="With secondaries"+ alt="Architecture diagram: a primary database alongside separate secondary 'pod' databases, each holding its own vector collection so collections can scale independently."src={{light: '/docs/img/ai/scaling/engineering-for-scale--with-secondaries--light.png',dark: '/docs/img/ai/scaling/engineering-for-scale--with-secondaries--dark.png',@@ -134,10 +138,10 @@ const { data, error } = await supabase### Enterprise architecture-This diagram provides an example architecture that allows you to access the collections either with our client libraries or using Vecs. You can add as many secondary databases as you need (in this example we only show one):+This diagram below provides an example architecture that allows you to access the collections either with our client libraries or using Vecs. You can add as many secondary databases as you need (in this example we only show one):<Image- alt="multi database"+ alt="Enterprise architecture diagram: an application accessing vector collections in multiple secondary databases, either directly via Vecs or through the primary database using Foreign Data Wrappers."src={{light: '/docs/img/ai/scaling/engineering-for-scale--multi-database--light.png',dark: '/docs/img/ai/scaling/engineering-for-scale--multi-database--dark.png',diff --git a/apps/docs/content/guides/ai/going-to-prod.mdx b/apps/docs/content/guides/ai/going-to-prod.mdxindex cf422a2c101..0673f11d211 100644--- a/apps/docs/content/guides/ai/going-to-prod.mdx+++ b/apps/docs/content/guides/ai/going-to-prod.mdx@@ -74,8 +74,10 @@ The values of lists and probes directly affect accuracy and queries per second (You can find more examples of how `lists` and `probes` constants affect accuracy and QPS in [pgvector 0.4.0 performance](/blog/pgvector-performance) blogpost.+The chart below shows how the IVFFlat lists count affects accuracy and queries-per-second.+<Image- alt="multi database"+ alt="Chart showing how the IVFFlat lists count affects query accuracy and queries-per-second."src={{light: '/docs/img/ai/going-prod/lists-count--light.png',dark: '/docs/img/ai/going-prod/lists-count--dark.png',@@ -117,8 +119,10 @@ You can look at our [Choosing Compute Add-on](/docs/guides/ai/choosing-compute-aOr take a look at our [pgvector 0.5.0 performance](/blog/increase-performance-pgvector-hnsw) and [pgvector 0.4.0 performance](/blog/pgvector-performance) blog posts to see what pgvector is capable of and how the above technique can be used to achieve the best results.+The chart below plots requests-per-second against compute size.+<Image- alt="multi database"+ alt="Chart plotting requests-per-second against Supabase compute size."src={{light: '/docs/img/ai/going-prod/size-to-rps--light.png',dark: '/docs/img/ai/going-prod/size-to-rps--dark.png',diff --git a/apps/docs/content/guides/ai/vector-indexes/hnsw-indexes.mdx b/apps/docs/content/guides/ai/vector-indexes/hnsw-indexes.mdxindex 6390b7260bb..420b32fd48e 100644--- a/apps/docs/content/guides/ai/vector-indexes/hnsw-indexes.mdx+++ b/apps/docs/content/guides/ai/vector-indexes/hnsw-indexes.mdx@@ -75,8 +75,10 @@ The hierarchical aspect of HNSW builds off of the idea of skip lists.Skip lists are multi-layer linked lists. The bottom layer is a regular linked list connecting an ordered sequence of elements. Each new layer above removes some elements from the underlying layer (based on a fixed probability), producing a sparser subsequence that “skips” over elements.+The diagram below shows a multi-layer skip list. The bottom layer links every ordered element, and each layer above keeps a sparser subset that skips over elements.+<Image- alt="visual of an example skip list"+ alt="Diagram of a multi-layer skip list: the bottom layer is a linked list of all ordered elements, and each higher layer keeps a sparser subset that skips over elements."src={{light: '/docs/img/ai/vector-indexes/hnsw-indexes/skip-list--light.png',dark: '/docs/img/ai/vector-indexes/hnsw-indexes/skip-list--dark.png',@@ -91,8 +93,10 @@ When searching for an element, the algorithm begins at the top layer and traversA navigable small world (NSW) is a special type of proximity graph that also includes long-range connections between nodes. These long-range connections support the “small world” property of the graph, meaning almost every node can be reached from any other node within a few hops. Without these additional long-range connections, many hops would be required to reach a far-away node.+The diagram below shows a navigable small world graph. Each node connects to nearby neighbors plus a few long-range links, so almost any node can reach any other in a few hops.+<Image- alt="visual of an example navigable small world graph"+ alt="Diagram of a navigable small world graph, where each node connects to nearby neighbors plus a few long-range links that let almost any node reach any other within a few hops."src="/docs/img/ai/vector-indexes/hnsw-indexes/nsw.png"className="max-h-[600px] mx-auto"width={1016}diff --git a/apps/docs/content/guides/auth/auth-mfa/phone.mdx b/apps/docs/content/guides/auth/auth-mfa/phone.mdxindex 649e87d4b97..3a123e4a59e 100644--- a/apps/docs/content/guides/auth/auth-mfa/phone.mdx+++ b/apps/docs/content/guides/auth/auth-mfa/phone.mdx@@ -32,6 +32,10 @@ flowchart TDListFactors -->|0 factors| Setup[[Setup flow]]```+In the **setup flow**, a session already at AAL1 calls the Enroll API followed by the Challenge API, which sends a code to the user over SMS or WhatsApp. The user enters the code, the Verify API checks it, and on success the session is upgraded to AAL2. An incorrect code returns the user to the code-entry step.++In the **login flow**, the user signs in (upgrading the session to AAL1) and the List Factors API is called. If the user has one or more factors, they select their phone factor and enter the code that was sent, following the same Verify path to reach AAL2. If they have no factors enrolled, they are sent through the setup flow first.+### Add enrollment flowAn enrollment flow provides a UI for users to set up additional authentication factors. Most applications add the enrollment flow in two places within their app:diff --git a/apps/docs/content/guides/auth/auth-mfa/totp.mdx b/apps/docs/content/guides/auth/auth-mfa/totp.mdxindex 906c0b81b14..dacae7becca 100644--- a/apps/docs/content/guides/auth/auth-mfa/totp.mdx+++ b/apps/docs/content/guides/auth/auth-mfa/totp.mdx@@ -32,8 +32,16 @@ flowchart TDListFactors -->|0 factors| Setup[[Setup flow]]```+In the **setup flow**, a session already at AAL1 calls the Enroll API, which returns a QR code for the user to scan with their authenticator app. The user enters the generated code, the Challenge and Verify APIs check it, and on success the session is upgraded to AAL2. If the code is incorrect, the user is prompted to enter it again.++In the **login flow**, the user signs in (upgrading the session to AAL1) and the List Factors API is called. If the user has one or more factors, they open their authenticator and enter a code, which follows the same Challenge and Verify path to reach AAL2. If they have no factors enrolled, they are sent through the setup flow first.++<Admonition type="tip">+[TOTP MFA API](/docs/reference/javascript/auth-mfa-api) is free to use and is enabled on all Supabase projects by default.+</Admonition>+### Add enrollment flowAn enrollment flow provides a UI for users to set up additional authentication factors. Most applications add the enrollment flow in two places within their app:@@ -303,29 +311,6 @@ function AuthMFA() {## Frequently asked questions-<Accordion- type="default"- openBehaviour="multiple"- chevronAlign="right"- justified- size="medium"- className="text-foreground-light mt-8 mb-6 [&>div]:space-y-4"->--<AccordionItem-header={<span className="text-foreground">What's inside the QR code?</span>}-id="what-is-inside-the-qr-code"->--</AccordionItem>--<AccordionItem-header={<span className="text-foreground">How long is the TOTP code valid for?</span>}-id="how-long-is-the-totp-code-valid-for"->+### How long is the TOTP code valid for?In our TOTP implementation, each generated code remains valid for one interval, which spans 30 seconds. To account for minor time discrepancies, we allow for a one-interval clock skew. This ensures that users can successfully authenticate within this timeframe, even if there are slight variations in system clocks.--</AccordionItem>--</Accordion>diff --git a/apps/docs/content/guides/database/connecting-to-postgres.mdx b/apps/docs/content/guides/database/connecting-to-postgres.mdxindex eace71d0811..f18555a9a9f 100644--- a/apps/docs/content/guides/database/connecting-to-postgres.mdx+++ b/apps/docs/content/guides/database/connecting-to-postgres.mdx@@ -328,3 +328,5 @@ flowchart TDH --> J[Use Dedicated Pooler PgBouncer Pro]I --> K[Use Supavisor Transaction Mode]```++The decision depends on where you connect from. For a **persistent backend**, use a direct connection if you can reach the database over IPv6 (or have the IPv4 add-on); otherwise use Supavisor in session mode. For **serverless or edge** environments, use the dedicated pooler (PgBouncer, Pro plan) when IPv6 or the IPv4 add-on is available, or Supavisor in transaction mode when you need IPv4.diff --git a/apps/docs/content/guides/database/partitions.mdx b/apps/docs/content/guides/database/partitions.mdxindex 8b18ef2c070..0f6164c4922 100644--- a/apps/docs/content/guides/database/partitions.mdx+++ b/apps/docs/content/guides/database/partitions.mdx@@ -6,8 +6,10 @@ description: 'Organizing tables into partitions in Postgres.'Table partitioning is a technique that allows you to divide a large table into smaller, more manageable parts called “partitions”.+The diagram below shows a single large table split into several smaller partitions, each holding a subset of its rows.+<Image- alt="multi database"+ alt="Diagram showing a single large table divided into several smaller partitions, each holding a subset of the table's rows."src={{light: '/docs/img/database/partitions-light.png',dark: '/docs/img/database/partitions-dark.png',diff --git a/apps/docs/content/guides/integrations/partner-integration-guide.mdx b/apps/docs/content/guides/integrations/partner-integration-guide.mdxindex 3cf4bd56726..6df0fa75f51 100644--- a/apps/docs/content/guides/integrations/partner-integration-guide.mdx+++ b/apps/docs/content/guides/integrations/partner-integration-guide.mdx@@ -55,6 +55,8 @@ sequenceDiagramBrowser->>User: Display "Integration Installed" Message```+The user clicks **Install Integration** in the Supabase Dashboard, which routes them through the partner's click-handler page and on to the Supabase authorization page. Supabase shows a consent screen. Once the user consents, Supabase redirects back to the partner with an authorization code. The partner exchanges that code for a token, uses the token to request Management API resources, and finally shows the user an "Integration Installed" message.+### Step 1: Implement the redirect endpointExpose a `GET` endpoint at any URL you control:@@ -136,6 +138,8 @@ sequenceDiagramBrowser->>User: Display "Integration Installed" Message```+Walking through the sequence: when the user clicks **Install Integration**, Supabase sends the partner a signed JWT and asks it to generate a redirect URL. The partner validates the JWT, generates a unique redirect record and URL, and returns it. Supabase redirects the user to that URL; the partner validates the redirect record, optionally has the user complete extra steps, and then sends them to the Supabase authorization page. From there the flow matches Method 1: the user consents, Supabase returns an authorization code, the partner exchanges it for a token, requests Management API resources, and the integration completes.+### Step 1: Exchange public keys with SupabaseSupabase generates two key-pairs, one for staging, one for production, and shares the public keys with you. Save both public keys and their key IDs in your system. The keys are PEM-encoded EC P-256.diff --git a/apps/docs/content/guides/local-development/seeding-your-database.mdx b/apps/docs/content/guides/local-development/seeding-your-database.mdxindex 0bce7ba4064..48e55d531a2 100644--- a/apps/docs/content/guides/local-development/seeding-your-database.mdx+++ b/apps/docs/content/guides/local-development/seeding-your-database.mdx@@ -122,6 +122,8 @@ erDiagram}```+This example schema has three tables. A `User` can author many `Post` rows (`Post.createdBy` references `User.id`) and many `Comment` rows (`Comment.userId` references `User.id`), and each `Post` can have many `Comment` rows (`Comment.postId` references `Post.id`). In other words, users create posts and comments, and every comment belongs to a post.+You can use the seed script example generated by Snaplet `seed.ts` to define the values you want to generate. For example:- A `Post` with the title `"There is a lot of snow around here!"`diff --git a/apps/docs/content/guides/platform/read-replicas.mdx b/apps/docs/content/guides/platform/read-replicas.mdxindex 212ee1bea9a..12133addca9 100644--- a/apps/docs/content/guides/platform/read-replicas.mdx+++ b/apps/docs/content/guides/platform/read-replicas.mdx@@ -45,21 +45,23 @@ You can only read data from a Read Replica. This is in contrast to a Primary datWhen your database starts slowing down, you face a choice: make your existing database bigger (scale vertically), or spread the load across multiple databases (scale horizontally). Both approaches work. Neither is universally correct. The right answer depends on your workload, your budget, and where the bottleneck actually is.-```mermaid-flowchart TD- A[Database slowing down] --> B{CPU above 70% sustained?}- B -->|No| C[Monitor, do not scale yet]- B -->|Yes| D{Queries optimized? Indexes in place?}- D -->|No| E[Run EXPLAIN ANALYZE<br/>Add missing indexes<br/>Optimize first]- E --> D- D -->|Yes| F{Workload 80%+ reads?}- F -->|No| G[Upgrade compute<br/>Replicas will not help writes]- F -->|Yes| H{Already at 16XL?}- H -->|Yes| I[Read Replicas<br/>Only horizontal option left]- H -->|No| J{Need workload isolation<br/>or geo-distribution?}- J -->|Yes| K[Read Replicas]- J -->|No| L[Either works<br/>Compute is simpler<br/>Replicas scale further]-```+ ```mermaid+ flowchart TD+ A[Database slowing down] --> B{CPU above 70% sustained?}+ B -->|No| C[Monitor, do not scale yet]+ B -->|Yes| D{Queries optimized? Indexes in place?}+ D -->|No| E[Run EXPLAIN ANALYZE<br/>Add missing indexes<br/>Optimize first]+ E --> D+ D -->|Yes| F{Workload 80%+ reads?}+ F -->|No| G[Upgrade compute<br/>Replicas will not help writes]+ F -->|Yes| H{Already at 16XL?}+ H -->|Yes| I[Read Replicas<br/>Only horizontal option left]+ H -->|No| J{Need workload isolation<br/>or geo-distribution?}+ J -->|Yes| K[Read Replicas]+ J -->|No| L[Either works<br/>Compute is simpler<br/>Replicas scale further]+ ```++ Supabase recommends not scaling until CPU is sustained above 70%. After it is, confirm your queries are already optimized and properly indexed with `EXPLAIN ANALYZE` before adding hardware. If your workload is less than roughly 80% reads, upgrade compute. Read Replicas only serve reads and won't help writes. If it's read-heavy, Read Replicas become the right choice after you reach the largest compute size of 16XL or earlier if you need workload isolation or geographic distribution. Below 16XL with no isolation need, either option works. While compute is simpler, Read Replicas scale further.</AccordionItem>diff --git a/apps/docs/content/guides/storage/schema/design.mdx b/apps/docs/content/guides/storage/schema/design.mdxindex e0f06401c90..a7e1905a721 100644--- a/apps/docs/content/guides/storage/schema/design.mdx+++ b/apps/docs/content/guides/storage/schema/design.mdx@@ -16,7 +16,7 @@ This is important because the storage schema only stores the metadata and the ac</Admonition>-Here is the schema that represents the Storage service:+Here is the schema that represents the Storage service, you have the option to query this table directly to retrieve information about your files in Storage without the need to go through our API.```mermaiderDiagram@@ -50,7 +50,7 @@ erDiagram}```-You have the option to query this table directly to retrieve information about your files in Storage without the need to go through our API.+The schema centers on three tables. Each `buckets` row can own many `objects` rows by a one-to-many relationship that joins `buckets.id` to `objects.bucket_id`. The `buckets` table holds bucket configuration. Its `id` and `name`, whether the bucket is `public`, and constraints such as `file_size_limit` and `allowed_mime_types`. The `objects` table holds per-file metadata: the owning `bucket_id`, the object `name` and `path_tokens`, a `metadata` JSON blob, and version information. The `migrations` table is standalone and tracks the schema migrations applied to the storage service.## Modifying the schemadiff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.tomlindex a870771011f..afa263dd7c6 100644--- a/supa-mdx-lint/Rule003Spelling.toml+++ b/supa-mdx-lint/Rule003Spelling.toml@@ -52,6 +52,7 @@ allow_list = ["[Cc]ryptosystem","[Cc]utover","[Dd]ata[Ff]rames?",+ "dbpedia","[Dd]atasets?","[Dd]atasources?","[Dd]atetime",