Skip to content

Commit 6245ba5

Browse files
kiwicopplesweatybridge
kiwicopple
and
sweatybridge
authored
chore: update cli reference doc (supabase#39469)
* chore: update cli reference doc * chore: update cli reference doc * chore: update cli reference doc * chore: update common sections for cli commands --------- Co-authored-by: Qiao Han <[email protected]>
1 parent c26231a commit 6245ba5

File tree

2 files changed

+92
-69
lines changed

2 files changed

+92
-69
lines changed

‎apps/docs/spec/cli_v1_commands.yaml‎

Lines changed: 62 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
clispec: '001'
22
info:
33
id: cli
4-
version: 2.48.3
4+
version: 2.54.10
55
title: Supabase CLI
66
language: sh
77
source: https://github.com/supabase/cli
@@ -78,7 +78,7 @@ flags:
7878
name: --workdir <string>
7979
description: path to a Supabase project directory
8080
default_value: ''
81-
- id: 'yes'
81+
- id: "yes"
8282
name: --yes
8383
description: answer yes to all prompts
8484
default_value: 'false'
@@ -1772,6 +1772,10 @@ commands:
17721772
name: --project-ref <string>
17731773
description: Project ref of the Supabase project.
17741774
default_value: ''
1775+
- id: skip-pooler
1776+
name: --skip-pooler
1777+
description: Use direct connection instead of pooler.
1778+
default_value: 'false'
17751779
- id: supabase-inspect
17761780
title: supabase inspect
17771781
summary: Tools to inspect your Supabase project
@@ -1824,6 +1828,7 @@ commands:
18241828
- supabase-inspect-db-replication-slots
18251829
- supabase-inspect-db-role-stats
18261830
- supabase-inspect-db-table-stats
1831+
- supabase-inspect-db-traffic-profile
18271832
- supabase-inspect-db-vacuum-stats
18281833
flags: []
18291834
- id: supabase-inspect-db-vacuum-stats
@@ -1865,6 +1870,52 @@ commands:
18651870
name: --local
18661871
description: Inspect the local database.
18671872
default_value: 'false'
1873+
- id: supabase-inspect-db-traffic-profile
1874+
title: supabase inspect db traffic-profile
1875+
summary: |
1876+
Show read/write activity ratio for tables based on block I/O operations
1877+
description: |2+
1878+
1879+
This command analyzes table I/O patterns to show read/write activity ratios based on block-level operations. It combines data from PostgreSQL's `pg_stat_user_tables` (for tuple operations) and `pg_statio_user_tables` (for block I/O) to categorize each table's workload profile.
1880+
1881+
1882+
The command classifies tables into categories:
1883+
- **Read-Heavy** - Read operations are more than 5x write operations (e.g., 1:10, 1:50)
1884+
- **Write-Heavy** - Write operations are more than 20% of read operations (e.g., 1:2, 1:4, 2:1, 10:1)
1885+
- **Balanced** - Mixed workload where writes are between 20% and 500% of reads
1886+
- **Read-Only** - Only read operations detected
1887+
- **Write-Only** - Only write operations detected
1888+
1889+
```
1890+
SCHEMA │ TABLE │ BLOCKS READ │ WRITE TUPLES │ BLOCKS WRITE │ ACTIVITY RATIO
1891+
───────┼──────────────┼─────────────┼──────────────┼──────────────┼────────────────────
1892+
public │ user_events │ 450,234 │ 9,004,680│ 23,450 │ 20:1 (Write-Heavy)
1893+
public │ users │ 89,203 │ 12,451│ 1,203 │ 7.2:1 (Read-Heavy)
1894+
public │ sessions │ 15,402 │ 14,823│ 2,341 │ ≈1:1 (Balanced)
1895+
public │ cache_data │ 123,456 │ 0│ 0 │ Read-Only
1896+
auth │ audit_logs │ 0 │ 98,234│ 12,341 │ Write-Only
1897+
```
1898+
1899+
**Note:** This command only displays tables that have had both read and write activity. Tables with no I/O operations are not shown. The classification ratio threshold (default: 5:1) determines when a table is considered "heavy" in one direction versus balanced.
1900+
1901+
tags: []
1902+
links: []
1903+
usage: supabase inspect db traffic-profile
1904+
subcommands: []
1905+
flags:
1906+
- id: db-url
1907+
name: --db-url <string>
1908+
description: |
1909+
Inspect the database specified by the connection string (must be percent-encoded).
1910+
default_value: ''
1911+
- id: linked
1912+
name: --linked
1913+
description: Inspect the linked project.
1914+
default_value: 'true'
1915+
- id: local
1916+
name: --local
1917+
description: Inspect the local database.
1918+
default_value: 'false'
18681919
- id: supabase-inspect-db-table-stats
18691920
title: supabase inspect db table-stats
18701921
summary: |
@@ -3114,7 +3165,7 @@ commands:
31143165
default_value: '[]'
31153166
- id: use-copy
31163167
name: --use-copy
3117-
description: Uses copy statements in place of inserts.
3168+
description: Use copy statements in place of inserts.
31183169
default_value: 'false'
31193170
- id: supabase-db-diff
31203171
title: supabase db diff
@@ -3391,6 +3442,10 @@ commands:
33913442
name: --name <string>
33923443
description: Rename the preview branch.
33933444
default_value: ''
3445+
- id: notify-url
3446+
name: --notify-url <string>
3447+
description: URL to notify when branch is active healthy.
3448+
default_value: ''
33943449
- id: persistent
33953450
name: --persistent
33963451
description: Switch between ephemeral and persistent branch.
@@ -3491,6 +3546,10 @@ commands:
34913546
usage: supabase branches create [name] [flags]
34923547
subcommands: []
34933548
flags:
3549+
- id: notify-url
3550+
name: --notify-url <string>
3551+
description: URL to notify when branch is active healthy.
3552+
default_value: ''
34943553
- id: persistent
34953554
name: --persistent
34963555
description: Whether to create a persistent branch.

‎apps/docs/spec/common-cli-sections.json‎

Lines changed: 30 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -240,21 +240,9 @@
240240
"type": "cli-command",
241241
"items": [
242242
{
243-
"id": "supabase-inspect-db-calls",
244-
"title": "Show most frequently run queries",
245-
"slug": "supabase-inspect-db-calls",
246-
"type": "cli-command"
247-
},
248-
{
249-
"id": "supabase-inspect-db-long-running-queries",
250-
"title": "Show long running queries",
251-
"slug": "supabase-inspect-db-long-running-queries",
252-
"type": "cli-command"
253-
},
254-
{
255-
"id": "supabase-inspect-db-outliers",
256-
"title": "Show queries ordered by total execution time",
257-
"slug": "supabase-inspect-db-outliers",
243+
"id": "supabase-inspect-db-bloat",
244+
"title": "Show estimated database bloat",
245+
"slug": "supabase-inspect-db-bloat",
258246
"type": "cli-command"
259247
},
260248
{
@@ -264,69 +252,39 @@
264252
"type": "cli-command"
265253
},
266254
{
267-
"id": "supabase-inspect-db-locks",
268-
"title": "Show queries taking exclusive locks",
269-
"slug": "supabase-inspect-db-locks",
255+
"id": "supabase-inspect-db-calls",
256+
"title": "Show most frequently run queries",
257+
"slug": "supabase-inspect-db-calls",
270258
"type": "cli-command"
271259
},
272260
{
273-
"id": "supabase-inspect-db-total-index-size",
274-
"title": "Show total size of all indexes",
275-
"slug": "supabase-inspect-db-total-index-size",
261+
"id": "supabase-inspect-db-db-stats",
262+
"title": "Show statistics related to database usage",
263+
"slug": "supabase-inspect-db-db-stats",
276264
"type": "cli-command"
277265
},
278266
{
279-
"id": "supabase-inspect-db-index-sizes",
267+
"id": "supabase-inspect-db-index-stats",
280268
"title": "Show sizes of individual indexes",
281-
"slug": "supabase-inspect-db-index-sizes",
282-
"type": "cli-command"
283-
},
284-
{
285-
"id": "supabase-inspect-db-index-usage",
286-
"title": "Show information about index efficiency",
287-
"slug": "supabase-inspect-db-index-usage",
288-
"type": "cli-command"
289-
},
290-
{
291-
"id": "supabase-inspect-db-unused-indexes",
292-
"title": "Show indexes with low usage",
293-
"slug": "supabase-inspect-db-unused-indexes",
294-
"type": "cli-command"
295-
},
296-
{
297-
"id": "supabase-inspect-db-total-table-sizes",
298-
"title": "Show total size of all tables",
299-
"slug": "supabase-inspect-db-total-table-sizes",
300-
"type": "cli-command"
301-
},
302-
{
303-
"id": "supabase-inspect-db-table-sizes",
304-
"title": "Show sizes of individual tables",
305-
"slug": "supabase-inspect-db-table-sizes",
269+
"slug": "supabase-inspect-db-index-stats",
306270
"type": "cli-command"
307271
},
308272
{
309-
"id": "supabase-inspect-db-table-index-sizes",
310-
"title": "Show index sizes of individual tables",
311-
"slug": "supabase-inspect-db-table-index-sizes",
312-
"type": "cli-command"
313-
},
314-
{
315-
"id": "supabase-inspect-db-cache-hit",
316-
"title": "Show cache hit rates for tables and indices",
317-
"slug": "supabase-inspect-db-cache-hit",
273+
"id": "supabase-inspect-db-locks",
274+
"title": "Show queries taking exclusive locks",
275+
"slug": "supabase-inspect-db-locks",
318276
"type": "cli-command"
319277
},
320278
{
321-
"id": "supabase-inspect-db-table-record-counts",
322-
"title": "Show estimated number of rows per table",
323-
"slug": "supabase-inspect-db-table-record-counts",
279+
"id": "supabase-inspect-db-long-running-queries",
280+
"title": "Show long running queries",
281+
"slug": "supabase-inspect-db-long-running-queries",
324282
"type": "cli-command"
325283
},
326284
{
327-
"id": "supabase-inspect-db-seq-scans",
328-
"title": "Show number of sequential scans for all tables",
329-
"slug": "supabase-inspect-db-seq-scans",
285+
"id": "supabase-inspect-db-outliers",
286+
"title": "Show queries ordered by total execution time",
287+
"slug": "supabase-inspect-db-outliers",
330288
"type": "cli-command"
331289
},
332290
{
@@ -336,15 +294,21 @@
336294
"type": "cli-command"
337295
},
338296
{
339-
"id": "supabase-inspect-db-role-connections",
297+
"id": "supabase-inspect-db-role-stats",
340298
"title": "Show number of active connections",
341299
"slug": "supabase-inspect-db-role-connections",
342300
"type": "cli-command"
343301
},
344302
{
345-
"id": "supabase-inspect-db-bloat",
346-
"title": "Show estimated database bloat",
347-
"slug": "supabase-inspect-db-bloat",
303+
"id": "supabase-inspect-db-table-stats",
304+
"title": "Show sizes of individual tables",
305+
"slug": "supabase-inspect-db-table-stats",
306+
"type": "cli-command"
307+
},
308+
{
309+
"id": "supabase-inspect-db-traffic-profile",
310+
"title": "Show read / write activity ratio for tables",
311+
"slug": "supabase-inspect-db-traffic-profile",
348312
"type": "cli-command"
349313
},
350314
{

0 commit comments

Comments
 (0)