From bc27a0fbc196927b228119abe8ec88e8e50b68ec Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 28 Mar 2024 16:44:58 -0400 Subject: [PATCH 1/7] Explain how to rename a table --- src/content/docs/en/guides/astro-db.mdx | 38 +++++++++++++++++++++---- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/guides/astro-db.mdx b/src/content/docs/en/guides/astro-db.mdx index e0398358dc5d4..3e1fd10b0ccfb 100644 --- a/src/content/docs/en/guides/astro-db.mdx +++ b/src/content/docs/en/guides/astro-db.mdx @@ -351,27 +351,55 @@ Your table schema will change overtime as your project grows. You can safely tes When [creating a Studio project from the dashboard](#astro-studio), you will have the option to create a GitHub CI action. This will automatically migrate schema changes when merging with your repository's main branch. -You can also push schema changes via the CLI using the `astro db push` command: +You can also push schema changes via the CLI using the `astro db push --remote` command: ```sh - npm run astro db push + npm run astro db push --remote ``` ```sh - pnpm astro db push + pnpm astro db push --remote ``` ```sh - yarn astro db push + yarn astro db push --remote ``` -This command will verify changes can be made without data loss and guide on recommended schema changes to resolve conflicts. If a breaking schema change _must_ be made, add the `--force-reset` flag to reset all production data. +This command will verify changes can be made without data loss and guide on recommended schema changes to resolve conflicts. + +:::note +If a breaking schema change _must_ be made, add the `--force-reset` flag to reset all production data. __This will destroy your database__, so only do so if you do not have important user data already. +::: + + +### Renaming tables + + +If you have already pushed your schema to Astro Studio and want to rename a table you can take one of thes approaches: + +If you *do __not__ have production data* then you can reset your database using the `--force-reset` flag. This flag will drop all of the tables in the database and create new ones so that it matches your current schema exactly. + +If you __do__ have production data you need to be more careful. You can perform a rename with the following steps: + +1. Keep the __old table__ schema in your config and add the `deprecated: true` property: + + ```ts + const Ingredient = defineTable({ + deprecated: true + // ... + }); + ``` +2. Add the __new table__ schema alongside the old table. +3. Push to Astro Studio with `astro db push --remote`. This will add the new table and mark the old as deprecated. +4. __Important__: Update any of your code to use the new table instead of the old table. You might need to migrate data to the new table as well. +5. Once you are confident at the old table is no longer used you can remove it. Remove the schema from your `config.ts`. +6. Push to Astro Studio with `astro db push --remote`. The old table will be dropped, leaving only the new, renamed table. ### Pushing data From 04ea113e6976f422bd978b5869c99c98541dc127 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 3 Apr 2024 13:14:05 -0400 Subject: [PATCH 2/7] Update src/content/docs/en/guides/astro-db.mdx Co-authored-by: Sarah Rainsberger --- src/content/docs/en/guides/astro-db.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/astro-db.mdx b/src/content/docs/en/guides/astro-db.mdx index 3e1fd10b0ccfb..543fea5fc47c0 100644 --- a/src/content/docs/en/guides/astro-db.mdx +++ b/src/content/docs/en/guides/astro-db.mdx @@ -351,7 +351,7 @@ Your table schema will change overtime as your project grows. You can safely tes When [creating a Studio project from the dashboard](#astro-studio), you will have the option to create a GitHub CI action. This will automatically migrate schema changes when merging with your repository's main branch. -You can also push schema changes via the CLI using the `astro db push --remote` command: +You can also push your local schema changes to Astro Studio via the CLI using the `astro db push --remote` command: From 3afd39dbcb6fc7e6704ce1c73dc537d5b0fdcc36 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 3 Apr 2024 13:14:26 -0400 Subject: [PATCH 3/7] Update src/content/docs/en/guides/astro-db.mdx Co-authored-by: Sarah Rainsberger --- src/content/docs/en/guides/astro-db.mdx | 62 ++++++++++++++++++++----- 1 file changed, 50 insertions(+), 12 deletions(-) diff --git a/src/content/docs/en/guides/astro-db.mdx b/src/content/docs/en/guides/astro-db.mdx index 543fea5fc47c0..580bc3be10387 100644 --- a/src/content/docs/en/guides/astro-db.mdx +++ b/src/content/docs/en/guides/astro-db.mdx @@ -381,25 +381,63 @@ If a breaking schema change _must_ be made, add the `--force-reset` flag to rese ### Renaming tables -If you have already pushed your schema to Astro Studio and want to rename a table you can take one of thes approaches: +It is possible to rename a table after pushing your schema to Astro Studio. -If you *do __not__ have production data* then you can reset your database using the `--force-reset` flag. This flag will drop all of the tables in the database and create new ones so that it matches your current schema exactly. +If you **do not have any important production data**, then you can [reset your database](#pushing-breaking-schema-changes) using the `--force-reset` flag. This flag will drop all of the tables in the database and create new ones so that it matches your current schema exactly. -If you __do__ have production data you need to be more careful. You can perform a rename with the following steps: +To rename a table while preserving your production data, you must perform a series of non-breaking changes to push your local schema to Astro studio safely. -1. Keep the __old table__ schema in your config and add the `deprecated: true` property: +The following example renames a table from `Comment` to `Feedback`: - ```ts - const Ingredient = defineTable({ +1. In your database config file, add the `deprecated: true` property to the table you want to rename: + + ```ts title="db/config.ts" ins={2} + const Comment = defineTable({ deprecated: true - // ... + columns: { + author: column.text(), + body: column.text(), + } }); ``` -2. Add the __new table__ schema alongside the old table. -3. Push to Astro Studio with `astro db push --remote`. This will add the new table and mark the old as deprecated. -4. __Important__: Update any of your code to use the new table instead of the old table. You might need to migrate data to the new table as well. -5. Once you are confident at the old table is no longer used you can remove it. Remove the schema from your `config.ts`. -6. Push to Astro Studio with `astro db push --remote`. The old table will be dropped, leaving only the new, renamed table. +2. Add a new table schema (matching the existing table's properties exactly) with the new name: + + ```ts title="db/config.ts" ins={9-14} + const Comment = defineTable({ + deprecated: true + columns: { + author: column.text(), + body: column.text(), + } + }); + + const Feedback = defineTable({ + columns: { + author: column.text(), + body: column.text(), + } + }); + ``` +3. [Push to Astro Studio](#pushing-table-schemas) with `astro db push --remote`. This will add the new table and mark the old as deprecated. +5. Update any of your local project code to use the new table instead of the old table. You might need to migrate data to the new table as well. +6. Once you are confident at the old table is no longer used in your project, you can remove the schema from your `config.ts`: + ```ts title="db/config.ts" del={1-7} + const Comment = defineTable({ + deprecated: true + columns: { + author: column.text(), + body: column.text(), + } + }); + + const Feedback = defineTable({ + columns: { + author: column.text(), + body: column.text(), + } + }); + ``` +7. Push to Astro Studio again with `astro db push --remote`. The old table will be dropped, leaving only the new, renamed table. ### Pushing data From a73f5a3640443dfa490f6f7efe5019d33ee3101e Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 3 Apr 2024 13:15:29 -0400 Subject: [PATCH 4/7] Update src/content/docs/en/guides/astro-db.mdx Co-authored-by: Sarah Rainsberger --- src/content/docs/en/guides/astro-db.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/astro-db.mdx b/src/content/docs/en/guides/astro-db.mdx index 580bc3be10387..63e6767a18bae 100644 --- a/src/content/docs/en/guides/astro-db.mdx +++ b/src/content/docs/en/guides/astro-db.mdx @@ -371,7 +371,7 @@ You can also push your local schema changes to Astro Studio via the CLI using th -This command will verify changes can be made without data loss and guide on recommended schema changes to resolve conflicts. +This command will verify that your local changes can be made without data loss and, if necessary, suggest how to safely make changes to your schema in order to resolve conflicts. :::note If a breaking schema change _must_ be made, add the `--force-reset` flag to reset all production data. __This will destroy your database__, so only do so if you do not have important user data already. From 7453d709d48ca1322e1de773f93dc22519e06964 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 3 Apr 2024 16:28:51 -0400 Subject: [PATCH 5/7] Update src/content/docs/en/guides/astro-db.mdx Co-authored-by: Sarah Rainsberger --- src/content/docs/en/guides/astro-db.mdx | 28 +++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/astro-db.mdx b/src/content/docs/en/guides/astro-db.mdx index 63e6767a18bae..54fdf0b7c3437 100644 --- a/src/content/docs/en/guides/astro-db.mdx +++ b/src/content/docs/en/guides/astro-db.mdx @@ -373,10 +373,34 @@ You can also push your local schema changes to Astro Studio via the CLI using th This command will verify that your local changes can be made without data loss and, if necessary, suggest how to safely make changes to your schema in order to resolve conflicts. -:::note -If a breaking schema change _must_ be made, add the `--force-reset` flag to reset all production data. __This will destroy your database__, so only do so if you do not have important user data already. +#### Pushing breaking schema changes + +:::caution +__This will destroy your database__. Only perform this command if you do not need your production data. ::: +If you must change your table schema in a way that is incompatible with your existing data hosted at Astro Studio, you will need to reset your production database. + +To push a table schema update that includes a breaking change, add the `--force-reset` flag to reset all production data: + + + + ```sh + npm run astro db push --remote --force-reset + ``` + + + ```sh + pnpm astro db push --remote --force-reset + ``` + + + ```sh + yarn astro db push --remote --force-reset + ``` + + + ### Renaming tables From eb6edfb88d8f0e74cefb0038b6f48aebed5f4b6c Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 3 Apr 2024 22:09:50 +0000 Subject: [PATCH 6/7] add Steps component and fiddle with code snippet indentation --- src/content/docs/en/guides/astro-db.mdx | 53 ++++++++++++++----------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/src/content/docs/en/guides/astro-db.mdx b/src/content/docs/en/guides/astro-db.mdx index 54fdf0b7c3437..b3b463f332354 100644 --- a/src/content/docs/en/guides/astro-db.mdx +++ b/src/content/docs/en/guides/astro-db.mdx @@ -8,6 +8,7 @@ import { FileTree } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import ReadMore from '~/components/ReadMore.astro'; import StudioHeading from '~/components/StudioHeading.astro'; +import { Steps } from '@astrojs/starlight/components'; Astro DB is a fully-managed SQL database designed exclusively for Astro. Develop locally or connect to a hosted database managed on our [Astro Studio](/en/recipes/studio/) platform. @@ -413,55 +414,59 @@ To rename a table while preserving your production data, you must perform a seri The following example renames a table from `Comment` to `Feedback`: + + 1. In your database config file, add the `deprecated: true` property to the table you want to rename: ```ts title="db/config.ts" ins={2} const Comment = defineTable({ - deprecated: true + deprecated: true, columns: { author: column.text(), body: column.text(), } }); ``` + 2. Add a new table schema (matching the existing table's properties exactly) with the new name: ```ts title="db/config.ts" ins={9-14} const Comment = defineTable({ - deprecated: true + deprecated: true, columns: { author: column.text(), body: column.text(), } - }); + }); - const Feedback = defineTable({ - columns: { - author: column.text(), - body: column.text(), - } - }); + const Feedback = defineTable({ + columns: { + author: column.text(), + body: column.text(), + } + }); ``` 3. [Push to Astro Studio](#pushing-table-schemas) with `astro db push --remote`. This will add the new table and mark the old as deprecated. -5. Update any of your local project code to use the new table instead of the old table. You might need to migrate data to the new table as well. -6. Once you are confident at the old table is no longer used in your project, you can remove the schema from your `config.ts`: +4. Update any of your local project code to use the new table instead of the old table. You might need to migrate data to the new table as well. +5. Once you are confident at the old table is no longer used in your project, you can remove the schema from your `config.ts`: ```ts title="db/config.ts" del={1-7} const Comment = defineTable({ - deprecated: true - columns: { - author: column.text(), - body: column.text(), - } - }); + deprecated: true, + columns: { + author: column.text(), + body: column.text(), + } + }); - const Feedback = defineTable({ - columns: { - author: column.text(), - body: column.text(), - } - }); + const Feedback = defineTable({ + columns: { + author: column.text(), + body: column.text(), + } + }); ``` -7. Push to Astro Studio again with `astro db push --remote`. The old table will be dropped, leaving only the new, renamed table. +6. Push to Astro Studio again with `astro db push --remote`. The old table will be dropped, leaving only the new, renamed table. + ### Pushing data From d83a6862bb22eadd0e765c6750ce5c2a5f8e74ba Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Thu, 4 Apr 2024 07:40:45 -0300 Subject: [PATCH 7/7] fix typo --- src/content/docs/en/guides/astro-db.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/astro-db.mdx b/src/content/docs/en/guides/astro-db.mdx index b3b463f332354..ac82141493467 100644 --- a/src/content/docs/en/guides/astro-db.mdx +++ b/src/content/docs/en/guides/astro-db.mdx @@ -448,7 +448,7 @@ The following example renames a table from `Comment` to `Feedback`: ``` 3. [Push to Astro Studio](#pushing-table-schemas) with `astro db push --remote`. This will add the new table and mark the old as deprecated. 4. Update any of your local project code to use the new table instead of the old table. You might need to migrate data to the new table as well. -5. Once you are confident at the old table is no longer used in your project, you can remove the schema from your `config.ts`: +5. Once you are confident that the old table is no longer used in your project, you can remove the schema from your `config.ts`: ```ts title="db/config.ts" del={1-7} const Comment = defineTable({ deprecated: true,