feat: add-generic migration guides (supabase#18182)

* feat: add-generic migration guides

* warning component

* Update apps/docs/pages/guides/resources.mdx

Co-authored-by: Greg Richardson <[email protected]>

* Update apps/docs/pages/guides/resources/migrating-to-supabase/postgres.mdx

Co-authored-by: Greg Richardson <[email protected]>

* Update apps/docs/pages/guides/resources/migrating-to-supabase/mssql.mdx

Co-authored-by: Greg Richardson <[email protected]>

* copy

* Consistency across links

* Icon fix

* Prettier

* Fix import

* docs: fix h2 heading

* docs: fix h2 heading

---------

Co-authored-by: Greg Richardson <[email protected]>

apps/docs/components/MDX/migration_warnings.mdx

@@ -0,0 +1,9 @@
+<Admonition type="caution">
+
+- If you're planning to migrate a database larger than 6 GB, we recommend [upgrading to at least a Large compute add-on](/docs/guides/platform/compute-add-ons). This will ensure you have the necessary resources to handle the migration efficiently.
+
+- For databases smaller than 150 GB, you can increase the size of the disk on paid projects by navigating to [Database Settings](/dashboard/project/_/settings/database).
+
+- If you're dealing with a database larger than 150 GB, we strongly advise you to [contact our support team](/dashboard/support/new) for assistance in provisioning the required resources and ensuring a smooth migration process.
+
+</Admonition>

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

@@ -1324,6 +1324,21 @@ export const resources: NavMenuConstant = {
  url: '/guides/resources/migrating-to-supabase/amazon-rds',
  items: [],
  },
+ {
+ name: 'Postgres',
+ url: '/guides/resources/migrating-to-supabase/postgres',
+ items: [],
+ },
+ {
+ name: 'MySQL',
+ url: '/guides/resources/migrating-to-supabase/mysql',
+ items: [],
+ },
+ {
+ name: 'MSSQL',
+ url: '/guides/resources/migrating-to-supabase/mssql',
+ items: [],
+ },
  ],
  },
  ],

apps/docs/components/index.tsx

@@ -22,6 +22,7 @@ import SocialProviderSettingsSupabase from './MDX/social_provider_settings_supab
 import SocialProviderSetup from './MDX/social_provider_setup.mdx'
 import StorageManagement from './MDX/storage_management.mdx'
 import KotlinProjectSetup from './MDX/kotlin_project_setup.mdx'
+import MigrationWarnings from './MDX/migration_warnings.mdx'
 import { CH } from '@code-hike/mdx/components'
 import RefHeaderSection from './reference/RefHeaderSection'
 
@@ -72,6 +73,7 @@ const components = {
  DatabaseSetup,
  ProjectSetup,
  KotlinProjectSetup,
+ MigrationWarnings,
  SocialProviderSetup,
  SocialProviderSettingsSupabase,
  StepHikeCompact,

apps/docs/pages/guides/resources.mdx

@@ -147,6 +147,24 @@ export const migrationGuides = [
  href: '/guides/resources/migrating-to-supabase/amazon-rds',
  description: 'Migrate your Amazon RDS database to Supabase.',
  },
+ {
+ title: 'Postgres',
+ icon: '/docs/img/icons/postgres-icon',
+ href: '/guides/resources/migrating-to-supabase/postgres',
+ description: 'Migrate your Postgres database to Supabase.',
+ },
+ {
+ title: 'MySQL',
+ icon: '/docs/img/icons/mysql-icon',
+ href: '/guides/resources/migrating-to-supabase/mysql',
+ description: 'Migrate your MySQL database to Supabase.',
+ },
+ {
+ title: 'Microsoft SQL Server',
+ icon: '/docs/img/icons/mssql-icon',
+ href: '/guides/resources/migrating-to-supabase/mssql',
+ description: 'Migrate your Microsoft SQL Server database to Supabase.',
+ },
 ]
 
 export const postgres = [

apps/docs/pages/guides/resources/migrating-to-supabase/amazon-rds.mdx

@@ -35,7 +35,7 @@ Supabase's core is Postgres, enabling the use of row-level security and providin
 The fastest way to migrate your database is with the Supabase migration tool on
 [Google Colab](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Amazon_RDS_to_Supabase.ipynb).
 
-Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a flexible and powerful data migration tool that supports a wide range of source database engines, including MySQL and MS SQL, and migrates the data to a Postgres database. For databases using the Postgres engine, we recommend using the pg_dump and psql command line tools, which are included in a full PostgreSQL installation.
+Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a flexible and powerful data migration tool that supports a wide range of source database engines, including MySQL and MS SQL, and migrates the data to a Postgres database. For databases using the Postgres engine, we recommend using the [`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full PostgreSQL installation.
 
 <Tabs
  scrollable
@@ -94,12 +94,7 @@ pgloader config.load
 </TabPanel>
 </Tabs>
 
-<Admonition type="caution">
-
-- If you plan on migrating a database larger than 6 GB, we recommend [contacting support](https://supabase.com/dashboard/support/new) to ensure that you'll have the proper disk size pre-provisioned. You can read more about how the disk is managed on Supabase on the [Database usage](/docs/guides/platform/database-size#disk-management).
-- We also recommend upgrading to at least a [Large instance](/docs/guides/platform/compute-add-ons) for the migration (you can downgrade later) to avoid running out of IO-Budget.
-
-</Admonition>
+<MigrationWarnings />
 
 export const Page = ({ children }) => <Layout meta={meta} children={children} />
 export default Page

apps/docs/pages/guides/resources/migrating-to-supabase/heroku.mdx

@@ -67,12 +67,7 @@ psql -h $SUPABASE_HOST -U postgres -f heroku_dump.sql
 
 Run `pg_dump --help` for a full list of options.
 
-<Admonition type="caution">
-
-- If you plan on migrating a database larger than 6 GB, we recommend [contacting support](https://supabase.com/dashboard/support/new) to ensure that you'll have the proper disk size pre-provisioned. You can read more about how the disk is managed on Supabase on the [Database usage](/docs/guides/platform/database-size#disk-management).
-- We also recommend upgrading to at least a [Large instance](/docs/guides/platform/compute-add-ons) for the migration (you can downgrade later) to avoid running out of IO-Budget.
-
-</Admonition>
+<MigrationWarnings />
 
 export const Page = ({ children }) => <Layout meta={meta} children={children} />
 

apps/docs/pages/guides/resources/migrating-to-supabase/mssql.mdx

@@ -0,0 +1,77 @@
+import Layout from '~/layouts/DefaultGuideLayout'
+
+export const meta = {
+ title: 'Migrate Your MSSQL Database to Supabase',
+ description: 'Migrate your Microsoft SQL Server database to Supabase Postgres database.',
+}
+
+This guide aims to demonstrate the process of transferring your Microsoft SQL Server database to Supabase's PostgreSQL database. Supabase is a powerful and open-source platform offering a wide range of backend features, including a PostgreSQL database, authentication, instant APIs, edge functions, real-time subscriptions, and storage. Migrating your MSSQL database to Supabase's Postgres enables you to leverage Postgres's capabilities and access all the features you need for your project.
+
+## Retrieve Your MSSQL Database Credentials
+
+Before you begin the migration, you need to collect essential information about your MSSQL database. Follow these steps:
+
+1. Log in to your MSSQL database provider.
+1. Locate and note the following database details:
+ - Hostname or IP address
+ - Database name
+ - Username
+ - Password
+
+## Retrieve your Supabase Host [#retrieve-supabase-host]
+
+1. If you're new to Supabase, [create a project](https://supabase.com/dashboard).
+1. Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.
+1. Under **Connection Info**, note your Host (`$SUPABASE_HOST`).
+1. Save your password or [reset it](https://supabase.com/dashboard/project/_/settings/database) if you forgot it.
+
+![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/amazon-rds/supabase_dashboard.png)
+
+## Migrate the database
+
+The fastest way to migrate your database is with the Supabase migration tool on
+[Google Colab](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Amazon_RDS_to_Supabase.ipynb).
+
+Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a flexible and powerful data migration tool that supports a wide range of source database engines, including MySQL and MS SQL, and migrates the data to a Postgres database. For databases using the Postgres engine, we recommend using the [`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full PostgreSQL installation.
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="colab"
+ queryGroup="migrate-method"
+>
+<TabPanel id="colab" label="Migrate using Colab">
+
+1. Select the Dabase Engine from the Source database in the dropdown.
+1. Set the environment variables (`HOST`, `USER`, `SOURCE_DB`,`PASSWORD`, `SUPABASE_URL`, and `SUPABASE_PASSWORD`) in the Colab notebook.
+1. Run the first two steps in [the notebook](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Amazon_RDS_to_Supabase.ipynb) in order. The first sets engine and installs the necessary files.
+1. Run the third step to start the migration. This will take a few minutes.
+
+</TabPanel>
+<TabPanel id="MS SQL" label="Migrate from MSSQL">
+
+ Install pgloader.
+ Create a configuration file (e.g., config.load).
+
+```sql
+LOAD DATABASE
+ FROM mssql://USER:PASSWORD@HOST/SOURCE_DB
+ INTO postgres://postgres:password@db.xxxx.supabase.co:6543/postgres
+ALTER SCHEMA 'public' OWNER TO 'postgres';
+set wal_buffers = '64MB', max_wal_senders = 0, statement_timeout = 0, work_mem to '2GB';
+```
+
+## Run the migration with pgloader
+
+```bash
+pgloader config.load
+```
+
+</TabPanel>
+</Tabs>
+
+<MigrationWarnings />
+
+export const Page = ({ children }) => <Layout meta={meta} children={children} />
+export default Page

apps/docs/pages/guides/resources/migrating-to-supabase/mysql.mdx

@@ -0,0 +1,78 @@
+import Layout from '~/layouts/DefaultGuideLayout'
+
+export const meta = {
+ title: 'Migrate Your MySQL Database to Supabase',
+ description: 'Migrate your MySQL database to Supabase Postgres database.',
+}
+
+This guide aims to exhibit the process of transferring your MySQL database to Supabase's Postgres database. Supabase is a robust and open-source platform offering a wide range of backend features, including a PostgreSQL database, authentication, instant APIs, edge functions, real-time subscriptions, and storage. Migrating your MySQL database to Supabase's PostgreSQL enables you to leverage PostgreSQL's capabilities and access all the features you need for your project.
+
+## Retrieve Your MySQL Database Credentials
+
+Before you begin the migration, you need to collect essential information about your MySQL database. Follow these steps:
+
+1. Log in to your MySQL database provider.
+
+1. Locate and note the following database details:
+ - Hostname or IP address
+ - Database name
+ - Username
+ - Password
+
+## Retrieve your Supabase Host [#retrieve-supabase-host]
+
+1. If you're new to Supabase, [create a project](https://supabase.com/dashboard).
+1. Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.
+1. Under **Connection Info**, note your Host (`$SUPABASE_HOST`).
+1. Save your password or [reset it](https://supabase.com/dashboard/project/_/settings/database) if you forgot it.
+
+![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/amazon-rds/supabase_dashboard.png)
+
+## Migrate the database
+
+The fastest way to migrate your database is with the Supabase migration tool on
+[Google Colab](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Amazon_RDS_to_Supabase.ipynb).
+
+Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a flexible and powerful data migration tool that supports a wide range of source database engines, including MySQL and MS SQL, and migrates the data to a Postgres database. For databases using the Postgres engine, we recommend using the [`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full PostgreSQL installation.
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="colab"
+ queryGroup="migrate-method"
+>
+<TabPanel id="colab" label="Migrate using Colab">
+
+1. Select the Dabase Engine from the Source database in the dropdown
+1. Set the environment variables (`HOST`, `USER`, `SOURCE_DB`,`PASSWORD`, `SUPABASE_URL`, and `SUPABASE_PASSWORD`) in the Colab notebook.
+1. Run the first two steps in [the notebook](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Amazon_RDS_to_Supabase.ipynb) in order. The first sets engine and installs the necessary files.
+1. Run the third step to start the migration. This will take a few minutes.
+
+</TabPanel>
+<TabPanel id="MySQL" label="Migrate from MySQL with pgloader">
+
+ Install pgloader.
+ Create a configuration file (e.g., config.load).
+
+```sql
+load database
+ from mysql://user:password@host/source_db
+ into postgres://postgres:password@db.xxxx.supabase.co:6543/postgres
+alter schema 'public' owner to 'postgres';
+set wal_buffers = '64MB', max_wal_senders = 0, statement_timeout = 0, work_mem to '2GB';
+```
+
+## Run the migration with pgloader
+
+```bash
+pgloader config.load
+```
+
+</TabPanel>
+</Tabs>
+
+<MigrationWarnings />
+
+export const Page = ({ children }) => <Layout meta={meta} children={children} />
+export default Page

apps/docs/pages/guides/resources/migrating-to-supabase/postgres.mdx

@@ -0,0 +1,87 @@
+import Layout from '~/layouts/DefaultGuideLayout'
+
+export const meta = {
+ title: 'Migrate from Postgres to Supabase',
+ description: 'Migrate your Postgres database to Supabase.',
+}
+
+This is a guide for migrating your Postgres database to [Supabase](https://supabase.com).
+Supabase is a robust and open-source platform. Supabase provide all the backend features developers need to build a product: a Postgres database, authentication, instant APIs, edge functions, realtime subscriptions, and storage. Postgres is the core of Supabase—for example, you can use row-level security and there are more than 40 Postgres extensions available.
+
+This guide demonstrates how to migrate your Postgres database to Supabase to get the most out of Postgres while gaining access to all the features you need to build a project.
+
+## Retrieve your Postgres database credentials [#retrieve-credentials]
+
+1. Log in to your provider to get the connection details for your Postgres database.
+1. Click on **PSQL Command** and edit it adding the content after `PSQL_COMMAND=`.
+
+Example:
+
+```bash
+%env PSQL_COMMAND=PGPASSWORD=RgaMDfTS_password_FTPa7 psql -h dpg-a_server_in.oregon-postgres.provider.com -U my_db_pxl0_user my_db_pxl0
+```
+
+## Retrieve your Supabase Host [#retrieve-supabase-host]
+
+1. If you're new to Supabase, [create a project](https://supabase.com/dashboard).
+1. Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.
+1. Under **Connection Info**, note your Host (`$SUPABASE_HOST`).
+1. Save your password or [reset it](https://supabase.com/dashboard/project/_/settings/database) if you forgot it.
+
+![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/render/supabase_dashboard.png)
+
+## Migrate the database
+
+The fastest way to migrate your database is with the Supabase migration tool on [Google Colab](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Migrate_Postgres_Supabase.ipynb). Alternatively, you can use the [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full PostgreSQL installation.
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="colab"
+ queryGroup="migrate-method"
+>
+<TabPanel id="colab" label="Migrate using Colab">
+
+1. Set the environment variables (`PSQL_COMMAND`, `SUPABASE_HOST`, `SUPABASE_PASSWORD`) in the Colab notebook.
+1. Run the first two steps in [the notebook](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Migrate_Postgres_Supabase.ipynb) in order. The first sets the variables and the second installs PSQL and the migration script.
+1. Run the third step to start the migration. This will take a few minutes.
+
+</TabPanel>
+<TabPanel id="cli" label="Migrate using CLI tools">
+
+### Export your database to a file in console [#export-database]
+
+Use `pg_dump` with your Postgres credentials to export your database to a file (e.g., `dump.sql`).
+
+```bash
+pg_dump --clean --if-exists --quote-all-identifiers \
+ -h $HOST -U $USER -d $DATABASE \
+ --no-owner --no-privileges > dump.sql
+```
+
+### Import the database to your Supabase project [#import-database-to-supabase]
+
+Use `psql` to import the Postgres database file to your Supabase project.
+
+```bash
+psql -h $SUPA_URL -U postgres --file dump.sql -p 6543 -d postgres
+```
+
+### Additional options
+
+- To only migrate a single database schema, add the `--schema=PATTERN` parameter to your `pg_dump` command.
+- To exclude a schema: `--exclude-schema=PATTERN`.
+- To only migrate a single table: `--table=PATTERN`.
+- To exclude a table: `--exclude-table=PATTERN`.
+
+Run `pg_dump --help` for a full list of options.
+
+</TabPanel>
+</Tabs>
+
+<MigrationWarnings />
+
+export const Page = ({ children }) => <Layout meta={meta} children={children} />
+
+export default Page

apps/docs/pages/guides/resources/migrating-to-supabase/render.mdx

@@ -84,12 +84,7 @@ Run `pg_dump --help` for a full list of options.
 </TabPanel>
 </Tabs>
 
-<Admonition type="caution">
-
-- If you plan on migrating a database larger than 6 GB, we recommend [contacting support](https://supabase.com/dashboard/support/new) to ensure that you'll have the proper disk size pre-provisioned. You can read more about how the disk is managed on Supabase on the [Database usage](/docs/guides/platform/database-size#disk-management).
-- We also recommend upgrading to at least a [Large instance](/docs/guides/platform/compute-add-ons) for the migration (you can downgrade later) to avoid running out of IO-Budget.
-
-</Admonition>
+<MigrationWarnings />
 
 export const Page = ({ children }) => <Layout meta={meta} children={children} />
 

apps/docs/pages/index.mdx

@@ -271,6 +271,21 @@ export const migrationGuides = [
  icon: '/docs/img/icons/aws-rds-icon',
  href: '/guides/resources/migrating-to-supabase/amazon-rds',
  },
+ {
+ title: 'Postgres',
+ icon: '/docs/img/icons/postgres-icon',
+ href: '/guides/resources/migrating-to-supabase/postgres',
+ },
+ {
+ title: 'MySQL',
+ icon: '/docs/img/icons/mysql-icon',
+ href: '/guides/resources/migrating-to-supabase/MySQL',
+ },
+ {
+ title: 'MSSQL',
+ icon: '/docs/img/icons/mssql-icon',
+ href: '/guides/resources/migrating-to-supabase/mssql',
+ },
 ]
 
 export const selfHostingOptions = [