chore: update docs with more migration examples (#912) · devhkr/cli@8acc7a3 · GitHub
Skip to content

Commit 8acc7a3

Browse files
sweatybridgesweatybridge
authored
chore: update docs with more migration examples (supabase#912)
* chore: update docs with more migration examples * chore: more detailed migration docs * chore: update command requirements * chore: misc improvements * chore: update functions docs
1 parent e4604db commit 8acc7a3

9 files changed

Lines changed: 115 additions & 4 deletions

File tree

‎cmd/functions.go‎

Lines changed: 2 additions & 2 deletions

‎docs/main.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ func main() {
3838
Clispec: "001",
3939
Info: InfoDoc{
4040
Id: "cli",
41-
Version: "1.34.5",
41+
Version: "1.42.0",
4242
Title: strings.TrimSpace(root.Short),
4343
Description: forceMultiLine("Supabase CLI provides you with tools to develop your application locally, and deploy your application to the Supabase platform."),
4444
Language: "sh",

‎docs/supabase/init.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,6 @@ Initialize configurations for Supabase local development.
44

55
A `supabase/config.toml` file is created in your current working directory. This configuration is specific to each local project.
66

7-
> You may override the directory path by specifying the `SUPABASE_WORKDIR` environment variable.
7+
> You may override the directory path by specifying the `SUPABASE_WORKDIR` environment variable or `--workdir` flag.
88
99
In addition to `config.toml`, the `supabase` directory may also contain other Supabase objects, such as `migrations`, `functions`, `tests`, etc.

‎docs/supabase/link.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,6 @@ PostgREST configurations are fetched from the Supabase platform and validated ag
66

77
Optionally, database settings can be validated if you provide a password. Your database password is saved in native credentials storage if available.
88

9+
> If you do not want to be prompted for the database password, such as in a CI environment, you may specify it explicitly via the `SUPABASE_DB_PASSWORD` environment variable.
10+
911
Some commands like `db dump`, `db push`, and `db remote commit` require your project to be linked first.

‎docs/supabase/migration/list.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## supabase-migration-list
2+
3+
Lists migration history in both local and remote databases.
4+
5+
Requires your local project to be linked to a remote database by running `supabase link`. For self-hosted databases, you can pass in the connection parameters using `--db-url` flag.
6+
7+
> Note that URL strings must be escaped according to [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986).
8+
9+
Local migrations are stored in `supabase/migrations` directory while remote migrations are tracked in `supabase_migrations.schema_migrations` table. Only the timestamps are compared to identify any differences.
10+
11+
In case of discrepancies between the local and remote migration history, you can resolve them using the `migration repair` command.

‎docs/supabase/migration/new.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
## supabase-migration-new
2+
3+
Creates a new migration file locally.
4+
5+
A `supabase/migrations` directory will be created if it does not already exists in your current `workdir`. All schema migration files must be created in this directory following the pattern `<timestamp>_<name>.sql`.
6+
7+
Outputs from other commands like `db diff` may be piped to `migration new <name>` via stdin.

‎docs/supabase/migration/repair.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## supabase-migration-repair
2+
3+
Repairs the remote migration history table.
4+
5+
Requires your local project to be linked to a remote database by running `supabase link`.
6+
7+
If your local and remote migration history goes out of sync, you can repair the remote history by marking specific migrations as `--status applied` or `--status reverted`. Marking as `reverted` will delete an existing record from the migration history table while marking as `applied` will insert a new record.
8+
9+
For example, your migration history table may look like this after running `db remote commit` for the first time.
10+
11+
```bash
12+
$ supabase migration list
13+
LOCAL │ REMOTE │ TIME (UTC)
14+
─────────────────┼────────────────┼──────────────────────
15+
20230103054303 │ 20230103054303 │ 2023-01-03 05:43:03
16+
```
17+
18+
To reset your migration history to a clean state, first delete your local migration file.
19+
20+
```bash
21+
$ rm supabase/migrations/20230103054303_remote_commit.sql
22+
$ supabase migration list
23+
LOCAL │ REMOTE │ TIME (UTC)
24+
─────────────────┼────────────────┼──────────────────────
25+
│ 20230103054303 │ 2023-01-03 05:43:03
26+
```
27+
28+
Then mark the remote migration `20230103054303` as reverted.
29+
30+
```bash
31+
$ supabase migration repair 20230103054303 --status reverted
32+
Repaired migration history: 20230103054303 => reverted
33+
$ supabase migration list
34+
LOCAL │ REMOTE │ TIME (UTC)
35+
─────────────────┼────────────────┼──────────────────────
36+
```
37+
38+
Now you can run `db remote commit` again to dump the remote schema as a local migration file.

‎docs/supabase/status.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
## supabase-status
2+
3+
Shows status of the Supabase local development stack.
4+
5+
Requires the local development stack to be started by running `supabase start` or `supabase db start`.
6+
7+
You can export the connection parameters for [initializing supabase-js](https://supabase.com/docs/reference/javascript/initializing) locally by specifying the `-o env` flag. Supported parameters include `JWT_SECRET`, `ANON_KEY`, and `SERVICE_ROLE_KEY`.

‎docs/templates/examples.yaml‎

Lines changed: 46 additions & 0 deletions

0 commit comments

Comments
 (0)