Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs: writeable connection (#70210)

Alex Yarosh6b369ef81840
diff --git a/docs/databases/connections/athena.md b/docs/databases/connections/athena.md
index 670633d34d7..5231b00e860 100644
--- a/docs/databases/connections/athena.md
+++ b/docs/databases/connections/athena.md
@@ -209,6 +209,12 @@ If Metabase also needs to create tables, you'll need additional AWS Glue permiss
}
```
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
There aren't (yet) any model features available for Athena.
diff --git a/docs/databases/connections/bigquery.md b/docs/databases/connections/bigquery.md
index dd00c888fee..59895ffd095 100644
--- a/docs/databases/connections/bigquery.md
+++ b/docs/databases/connections/bigquery.md
@@ -161,6 +161,12 @@ FROM [my_dataset.my_table]
If you're having trouble with your BigQuery connection, you can check out this [troubleshooting guide](../../troubleshooting-guide/bigquery-drive.md) that covers BigQuery issues, [this one](../../troubleshooting-guide/db-connection.md) on data warehouse connections, or visit [Metabase's discussion forum](https://discourse.metabase.com/search?q=bigquery) to see if someone has encountered and resolved a similar issue.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
There aren't (yet) any model features available for BigQuery.
diff --git a/docs/databases/connections/clickhouse.md b/docs/databases/connections/clickhouse.md
index 7dd17946da0..5a763428b89 100644
--- a/docs/databases/connections/clickhouse.md
+++ b/docs/databases/connections/clickhouse.md
@@ -101,6 +101,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
There aren't (yet) any model features for ClickHouse.
diff --git a/docs/databases/connections/databricks.md b/docs/databases/connections/databricks.md
index 9a742a3fb4c..4384ff314fa 100644
--- a/docs/databases/connections/databricks.md
+++ b/docs/databases/connections/databricks.md
@@ -101,6 +101,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
There aren't (yet) any model features available for Databricks.
diff --git a/docs/databases/connections/druid.md b/docs/databases/connections/druid.md
index e50cf218330..89438cebf5c 100644
--- a/docs/databases/connections/druid.md
+++ b/docs/databases/connections/druid.md
@@ -64,6 +64,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
There aren't (yet) any model features available for Druid.
diff --git a/docs/databases/connections/mariadb.md b/docs/databases/connections/mariadb.md
index 367c2478213..d3e42e84171 100644
--- a/docs/databases/connections/mariadb.md
+++ b/docs/databases/connections/mariadb.md
@@ -101,6 +101,12 @@ JSON schema inference doesn't work with MariaDB, due to implementation differenc
If your password contains characters that aren't UTF-8, then you might need to add an additional variable to the connection string `passwordCharacterEncoding=<your_encoding_here>`. This ensures that MariaDB understands the special characters in the password during authentication.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Database routing
With database routing, an admin can build a question once using one database, and the question will run its query against a different database with the same schema depending on who is viewing the question.
diff --git a/docs/databases/connections/mongodb.md b/docs/databases/connections/mongodb.md
index ebd3058213e..599c866652e 100644
--- a/docs/databases/connections/mongodb.md
+++ b/docs/databases/connections/mongodb.md
@@ -130,6 +130,12 @@ Instead, Metabase gets a sample of the fields in a collection by scanning a samp
If you're not seeing all of the fields show up for a collection in Metabase, one workaround is to include all possible keys in the first document of the collection, and give those keys null values. That way, Metabase will be able to recognize the correct schema for the entire collection.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Database routing
With database routing, an admin can build a question once using one database, and the question will run its query against a different database with the same schema depending on who is viewing the question.
diff --git a/docs/databases/connections/mysql.md b/docs/databases/connections/mysql.md
index 6a495d951e1..6b829e8817a 100644
--- a/docs/databases/connections/mysql.md
+++ b/docs/databases/connections/mysql.md
@@ -187,6 +187,12 @@ mysql:
If your password contains characters that aren't UTF-8, then you might need to add an additional variable to the connection string `passwordCharacterEncoding=<your_encoding_here>`. This ensures that MySQL understands the special characters in the password during authentication.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
Choose whether to enable features related to [Metabase models](../../data-modeling/models.md). These features will often require that the database user account, the one you use to connect to your database, has both read and write privileges.
diff --git a/docs/databases/connections/oracle.md b/docs/databases/connections/oracle.md
index 8e114d18c42..33ff8ab30a6 100644
--- a/docs/databases/connections/oracle.md
+++ b/docs/databases/connections/oracle.md
@@ -131,6 +131,12 @@ For example, if you're running Metabase from a directory called `/app/`, you sho
The process for adding plugins when running via Docker is similar, but you'll need to mount the `plugins` directory. Refer to instructions [here](../../installation-and-operation/running-metabase-on-docker.md#adding-external-dependencies-or-plugins) for more details.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Danger zone
See [Danger zone](../danger-zone.md).
diff --git a/docs/databases/connections/postgresql.md b/docs/databases/connections/postgresql.md
index 331fa2f6258..3c26096d9d3 100644
--- a/docs/databases/connections/postgresql.md
+++ b/docs/databases/connections/postgresql.md
@@ -186,6 +186,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
Choose whether to enable features related to [Metabase models](../../data-modeling/models.md). These features will often require that the database user account, the one you use to connect to your database, has both read and write privileges.
diff --git a/docs/databases/connections/presto.md b/docs/databases/connections/presto.md
index 45225450cfe..2f98fa85586 100644
--- a/docs/databases/connections/presto.md
+++ b/docs/databases/connections/presto.md
@@ -94,6 +94,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Database routing
With database routing, an admin can build a question once using one database (data catalog), and the question will run its query against a different data catalog with the same schema depending on who is viewing the question.
diff --git a/docs/databases/connections/redshift.md b/docs/databases/connections/redshift.md
index de562b82fa2..51695d58057 100644
--- a/docs/databases/connections/redshift.md
+++ b/docs/databases/connections/redshift.md
@@ -98,6 +98,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
Choose whether to enable features related to Metabase models. These will often require a write connection.
diff --git a/docs/databases/connections/snowflake.md b/docs/databases/connections/snowflake.md
index a4ab947ae9c..8d469143fd0 100644
--- a/docs/databases/connections/snowflake.md
+++ b/docs/databases/connections/snowflake.md
@@ -14,17 +14,17 @@ You can edit these settings at any time. Just remember to save your changes.
Paste a connection string here to pre-fill the remaining fields below.
-## Display name
+### Display name
The display name for the database in the Metabase interface.
-## Account or hostname
+### Account or hostname
You have the option of using an account name or hostname. Your hostname is your database's IP address or its domain name (e.g., database.example.com).
If your URL includes your database's region, you can connect using an account name, otherwise connect using a hostname.
-### AWS
+#### AWS
Connect with an account name.
@@ -37,7 +37,7 @@ You'd enter `az12345.ca-central-1.aws` as the account name in Metabase.
Not all regions require the cloud platform identifier. If you're in `us-west-2`, you would enter `az12345` as the account name. For the requirements per region, see [the official Snowflake's documentation](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html#non-vps-account-locator-formats-by-cloud-platform-and-region).
-### app.snowflake.com
+#### app.snowflake.com
Connect with a host name.
@@ -47,31 +47,31 @@ You can get your host name by going to Admin > Accounts. The Account name will b
Learn more about [Account Identifiers in Snowflake](https://docs.snowflake.com/en/user-guide/admin-account-identifier).
-## Username
+### Username
The database username for the account that you want to use to connect to your database. You can set up multiple connections to the same database using different user accounts to connect to the same database, each with different sets of [privileges](../users-roles-privileges.md).
On your app.snowflake.com account page, you can find Users and roles under Admin > Users & Roles.
-## Password
+### Password
The password for the username that you use to connect to the database.
-## RSA private key (PEM)
+### RSA private key (PEM)
Not required. You have the option of using a **Local file path** or an **Uploaded file path**. If you're on Metabase Cloud, you'll need to select **Uploaded file path** and upload your certificate.
-## Warehouse
+### Warehouse
Snowflake warehouse. If the user lacks a default warehouse, you'll need to enter the warehouse to connect to.
On app.snowflake.com, you can find warehouses under Admin > Warehouses.
-## Database name (case sensitive)
+### Database name (case sensitive)
The name of the database you want to connect to in Snowflake. On app.snowflake.com you can find databases under Data > Databases.
-## Schemas (optional)
+### Schemas (optional)
You can specify which schemas you want to sync and scan. If no schema is passed, then all schema available to that user and role will be listed as folders in Metabase.
@@ -96,7 +96,7 @@ Let's say you have three schemas: FOO, BAR, and BAZ.
Note that only the `*` wildcard is supported; you can't use other special characters or regexes.
-## Role (optional)
+### Role (optional)
> **WARNING:** Metabase gets _all the permissions_ combined from _every_ role you grant the user in Snowflake. Setting the 'Role' here just adds the role to the connection string to tell Snowflake which role to default to – it **won't restrict** access on its own. So **be careful which roles you assign to the connection user**: if down the line you grant that user broader roles in Snowflake, Metabase will automatically gets those new permissions, potentially showing data you didn't mean for it to see. If instead you want Metabase to issue `SET ROLE` commands before querying anything, check out [connection impersonation](../../permissions/impersonation.md).
@@ -107,25 +107,25 @@ Specify a role to override the database user's default role. For example, if the
You can enter `ANALYTICS` in the Role field to ensure that the `METABASE` user connects to Snowflake using the `ANALYTICS` role by default.
-## Use an SSH tunnel
+### Use an SSH tunnel
See our [guide to SSH tunneling](../ssh-tunnel.md).
-## Additional JDBC connection string options
+### Additional JDBC connection string options
Some databases allow you to append options to the connection string that Metabase uses to connect to your database.
-## Re-run queries for simple explorations
+### Re-run queries for simple explorations
Turn this option **OFF** if people want to click **Run** (the play button) before applying any [Summarize](../../questions/query-builder/summarizing-and-grouping.md) or filter selections.
By default, Metabase will execute a query as soon as you choose an grouping option from the **Summarize** menu or a filter condition from the [drill-through menu](https://www.metabase.com/learn/metabase-basics/querying-and-dashboards/questions/drill-through). If your database is slow, you may want to disable re-running to avoid loading data on each click.
-## Choose when syncs and scans happen
+### Choose when syncs and scans happen
See [syncs and scans](../sync-scan.md#choose-when-syncs-and-scans-happen).
-### Periodically refingerprint tables
+#### Periodically refingerprint tables
> Periodic refingerprinting will increase the load on your database.
@@ -133,6 +133,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
There aren't (yet) any model features available for Snowflake.
diff --git a/docs/databases/connections/sparksql.md b/docs/databases/connections/sparksql.md
index 4b315b7cf2b..f2b9f69fd8f 100644
--- a/docs/databases/connections/sparksql.md
+++ b/docs/databases/connections/sparksql.md
@@ -77,6 +77,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Danger zone
See [Danger zone](../danger-zone.md).
diff --git a/docs/databases/connections/sql-server.md b/docs/databases/connections/sql-server.md
index da0bc24f3dd..beb0a598a13 100644
--- a/docs/databases/connections/sql-server.md
+++ b/docs/databases/connections/sql-server.md
@@ -97,6 +97,12 @@ A fingerprinting query examines the first 10,000 rows from each column and uses
To connect to Azure SQL, you'll need to set the port to 1433.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Database routing
With database routing, an admin can build a question once using one database, and the question will run its query against a different database with the same schema depending on who is viewing the question.
diff --git a/docs/databases/connections/sqlite.md b/docs/databases/connections/sqlite.md
index 50d31079c20..febed811409 100644
--- a/docs/databases/connections/sqlite.md
+++ b/docs/databases/connections/sqlite.md
@@ -61,6 +61,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Database routing
With database routing, an admin can build a question once using one database, and the question will run its query against a different database with the same schema depending on who is viewing the question.
diff --git a/docs/databases/connections/starburst.md b/docs/databases/connections/starburst.md
index b9b55a03502..9120cea5780 100644
--- a/docs/databases/connections/starburst.md
+++ b/docs/databases/connections/starburst.md
@@ -91,6 +91,12 @@ Turn this option **ON** to scan a sample of values every time Metabase runs a [s
A fingerprinting query examines the first 10,000 rows from each column and uses that data to guesstimate how many unique values each column has, what the minimum and maximum values are for numeric and timestamp columns, and so on. If you leave this option **OFF**, Metabase will only fingerprint your columns once during setup.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
There aren't (yet) any model features for Starburst.
diff --git a/docs/databases/connections/vertica.md b/docs/databases/connections/vertica.md
index 4b18122be49..9c1aa78da38 100644
--- a/docs/databases/connections/vertica.md
+++ b/docs/databases/connections/vertica.md
@@ -41,6 +41,12 @@ For example, if you're running Metabase from a directory called `/app/`, you sho
The process for adding plugins when running via Docker is similar, but you'll need to mount the `plugins` directory. Refer to instructions [here](../../installation-and-operation/running-metabase-on-docker.md#adding-external-dependencies-or-plugins) for more details.
+## Writeable connection
+
+{% include plans-blockquote.html feature="Writeable connection" is_plural=true%}
+
+Set up an additional connection used for write operations. See [Writeable connections](../writeable-connection.md).
+
## Model features
There aren't (yet) any model features for Vertica.
diff --git a/docs/databases/images/writeable-connection.png b/docs/databases/images/writeable-connection.png
new file mode 100644
index 00000000000..147657ffb82
Binary files /dev/null and b/docs/databases/images/writeable-connection.png differ
diff --git a/docs/databases/users-roles-privileges.md b/docs/databases/users-roles-privileges.md
index 27f04d55649..7ed8219c58e 100644
--- a/docs/databases/users-roles-privileges.md
+++ b/docs/databases/users-roles-privileges.md
@@ -1,21 +1,28 @@
---
title: Database users, roles, and privileges
+summary: Set up database users and roles for Metabase: read-only access for queries, optional write permissions for transforms, uploads, actions, and model persistence.
---
# Database users, roles, and privileges
-We recommend creating a `metabase` database user with the following database roles:
+## Recommended setup
+
+We recommend creating a dedicated `metabase` database user with the **read-only** access to your database with [minimum database privileges for read access](#minimum-database-privileges) to any schemas or tables used for analysis.
+
+Some Metabase functionality requires write access to the database. Depending on other Metabase features you're planning to use, you might want to create additional roles:
-- [`analytics` for read access](#minimum-database-privileges) to any schemas or tables used for analysis.
-- Optional [`metabase_actions` for write access](#privileges-to-enable-actions-and-editable-table-data) to tables used for Metabase actions.
-- Optional [`metabase_model_persistence` for write access](#privileges-to-enable-model-persistence) to the schema used for Metabase model persistence.
- Optional [`metabase_transforms` for write access](#privileges-to-enable-transforms) to the schema used for Metabase transforms.
+- Optional [`metabase_uploads` for write access](#privileges-to-enable-uploads) to schema used for CSV uploads.
+- Optional [`metabase_actions` for write access](#privileges-to-enable-actions-and-editable-table-data) to tables used for editable tables or Metabase actions .
+- Optional [`metabase_model_persistence` for write access](#privileges-to-enable-model-persistence) to the schema used for Metabase model persistence.
Bundling your privileges into roles based on use cases makes it easier to manage privileges in the future (especially in [multi-tenant situations](#multi-tenant-permissions)). For example, you could:
- Use the same `analytics` role for other BI tools in your [data stack](https://www.metabase.com/learn/grow-your-data-skills/data-fundamentals/data-landscape) that need read-only access to the analytics tables in your database.
- Revoke the write access for `metabase_model_persistence` without affecting the write access for `metabase_actions`.
+On Metabase Pro/Enterprise plans, we recommend using separate [Writeable connections](./writeable-connection.md) for operations that require write access.
+
## Minimum database privileges
In order to view and query your tables in Metabase, you'll have to give Metabase's database user:
@@ -85,17 +92,17 @@ CREATE USER metabase WITH PASSWORD "your_password";
GRANT ALL PRIVILEGES ON "database" TO metabase;
```
-This is a good option if you're connecting to a local database for development or testing.
+This is a good option if you're connecting to a local database for development or testing. Avoid using this setup in production.
## Privileges to enable actions and editable table data
Both [actions](../actions/introduction.md) and the [editable table data](../data-modeling/editable-tables.md) let Metabase write back to specific tables in your database.
-In addition to the [minimum database privileges](#minimum-database-privileges), you'll need to grant write access to any tables you want to be able to write to.
+if you're using actions or editable tables, then in addition to the [minimum database privileges](#minimum-database-privileges), you'll need to grant write access to any tables you want to be able to write to.
- Create a new role called `metabase_writer`.
- Give the role `INSERT`, `UPDATE`, and `DELETE` privileges to the relevant tables.
-- Give the `metabase_writer` role to the `metabase` user.
+- Give the `metabase_writer` role to the user used for your database connection. We recommend using a [writeable connection](./writeable-connection.md) and only granting this role to the user used for the writeable connection.
```sql
-- Create a role to bundle database privileges for Metabase writing to your database.
@@ -117,7 +124,7 @@ In addition to the [minimum database privileges](#minimum-database-privileges):
- Create a new role called `metabase_model_persistence`.
- Give the role `CREATE` access to the database.
- Give the role `INSERT`, `UPDATE`, and `DELETE` privileges to the schema used for model persistence.
-- Give the `metabase_model_persistence` role to the `metabase` user.
+- Give the `metabase_model_persistence` role to the user used for your database connection. We recommend using a [writeable connection](./writeable-connection.md) and only granting this role to the user used for the writeable connection.
```sql
-- Create a role to bundle database privileges for Metabase model persistence.
@@ -137,20 +144,20 @@ GRANT metabase_model_persistence TO metabase;
## Privileges to enable transforms
-[Transforms](../data-studio/transforms/transforms-overview.md) let Metabase write query results back to your database. We suggest that you create a dedicated schema for your transforms. Metabase's database user will need to be able to create and drop transform tables.
+[Transforms](../data-studio/transforms/transforms-overview.md) let Metabase write query results back to your database. We suggest that you create a dedicated schema for your transforms. Metabase's database user will need to be able to create and drop transform tables. We recommend using a [writeable connection](./writeable-connection.md) and only granting write access to the user used for the writeable connection.
In addition to the [minimum database privileges](#minimum-database-privileges):
- Create a new role called `metabase_transforms`.
- Create a dedicated schema for transforms.
- Give the `metabase_transforms` role `CREATE TABLE` / `ALTER` / `DROP` privileges for the specified schema.
-- Give the `metabase_transforms` role to the `metabase` user.
+- Give the `metabase_transforms` role to the user used for your database connection. We recommend using a [writeable connection](./writeable-connection.md) and only granting this role to the user used for the writeable connection.
In certain cases, Metabase will give you an option to create new schemas for transforms, in which case you'll also need `CREATE SCHEMA` privileges for your metabase users (or `CREATE DATABASE` for ClickHouse).
## Privileges to enable uploads
-You can [upload CSVs](../databases/uploads.md) to supported databases. Metabase's database user should have write access (`INSERT`, `UPDATE`, `DELETE`) to the schema where you want to store the uploads.
+You can [upload CSVs](../databases/uploads.md) to supported databases. Metabase's database user should have write access (`INSERT`, `UPDATE`, `DELETE`) to the schema where you want to store the uploads. We recommend using a [writeable connection](./writeable-connection.md) and only granting write access to the user used for the writeable connection.
You'll first need to create a schema to store uploads (or use an existing schema) and tell Metabase that you want to [use that schema to store uploads](./uploads.md#select-the-database-and-schema-that-you-want-to-store-the-data-in).
@@ -158,7 +165,7 @@ In addition to the [minimum database privileges](#minimum-database-privileges):
- Create a new role called `metabase_uploads`.
- Give the role `INSERT`, `UPDATE`, and `DELETE` privileges to the schema where you want to store uploads.
-- Give the `metabase_uploads` role to the `metabase` user.
+- Give the `metabase_uploads` role to the user used for your database connection.
```sql
-- Create a role to bundle database privileges for uploads.
@@ -221,6 +228,7 @@ We recommend bundling privileges into roles based on use cases per customer. Tha
## Further reading
+- [Writeable connections](./writeable-connection.md)
- [Permissions strategies](https://www.metabase.com/learn/metabase-basics/administration/permissions/strategy)
- [Permissions introduction](../permissions/introduction.md)
- [People overview](../people-and-groups/start.md)
diff --git a/docs/databases/writeable-connection.md b/docs/databases/writeable-connection.md
new file mode 100644
index 00000000000..7e417a27064
--- /dev/null
+++ b/docs/databases/writeable-connection.md
@@ -0,0 +1,60 @@
+---
+title: Writeable connections
+summary: Add an optional separate database connection for write operations like transforms or editable tables to keep the main Metabase connection read-only for analytics.
+---
+
+## Writeable connections
+
+{% include plans-blockquote.html feature="Writeable connections" is_plural=true%}
+
+_Admin > Databases > Writeable connection_
+
+Writeable connection is an optional connection that Metabase will use for functionality that involves writing into the database (for example, transforms or CSV uploads). This allows you to keep your main Metabase connection read-only, and only to switch to connection with write permissions for the operations that require write access.
+
+![Writeable connection in database settings](./images/writeable-connection.png)
+
+## How writeable connection works
+
+Writeable connection is an additional connection option added to an existing database connection.
+
+When a writeable connection is configured for a database, Metabase automatically switches between connections behind the scenes based on what people are doing with the database. The main connection is used for querying, and the writeable connection is used for [features that require writes](#features-that-use-writeable-connection).
+
+Writeable connection can use a different database user than the main connection, or even connect to a different database. For example, your main connection (used for querying) can go to a read replica, but the writeable connection can be to a primary database.
+
+## Add a writeable connection
+
+To add a writeable connection to a database:
+
+1. Go to **Admin > Databases**.
+2. Select the database to add a writeable connection to.
+3. Under **Writeable connection**, click **Add writeable connection**.
+4. Metabase will pre-fill some fields with information from your main connection. Input the credentials for the writeable connection.
+5. Click **Save**. Metabase will try to connect using the new connection.
+
+## Remove a writeable connection
+
+To remove a writeable connection from a database:
+
+1. Go to **Admin > Databases**.
+2. Select the database you want to remove the writeable connection from.
+3. Under **Writeable connection**, click **Remove writeable connection**.
+
+Once writeable connection is removed, Metabase will revert to using the main connection for [features that need write access](#features-that-use-writeable-connection), so your main connection will need to have appropriate database permissions, see [Users, roles, and privileges](./users-roles-privileges.md)
+
+## Features that use writeable connection
+
+When configured, writeable connection will be used for:
+
+- [Transforms](../data-studio/transforms/transforms-overview.md)
+- [CSV uploads](../databases/uploads.md)
+- [Editable tables](../data-modeling/editable-tables.md)
+- [Actions](../actions/introduction.md)
+- [Model persistence](../data-modeling/model-persistence.md)
+
+Your writeable connection will need to have the privileges required for these operations. See [Users, roles, and privileges](./users-roles-privileges.md).
+
+## Limitations
+
+- Writeable connection can't be used with [database routing](../permissions/database-routing.md).
+
+- Writeable connection must use the same database engine as the primary connection - so for example, if the primary connection is to a PostgreSQL database, the writeable connection must be to a PostgreSQL database as well.
diff --git a/docs/permissions/database-routing.md b/docs/permissions/database-routing.md
index ca298f1e390..c4d9420a669 100644
--- a/docs/permissions/database-routing.md
+++ b/docs/permissions/database-routing.md
@@ -21,13 +21,32 @@ Database routing is useful for:
## Database routing limitations
-> Database routing is **not supported** on ClickHouse, Oracle, Spark SQL, and Vertica.
+### Driver limitations
+
+Database routing is **not supported** on:
+
+- ClickHouse
+- Oracle
+- Spark SQL
+- Vertica.
Different database have different setups, so _what_ you can route between (database, schema, data catalog, etc.) will differ slightly depending on which data warehouse you're using.
-- [Athena](../databases/connections/athena.md): Only routing between different connections is supported (e.g., different buckets, roles, or catalogs).
-- [BigQuery](../databases/connections/bigquery.md): Only routing between databases in different projects is supported.
-- [Databricks](../databases/connections/databricks.md): When multi-catalog is not enabled, you can route between catalogs on the same host. If multi-catalog is enabled, then you can only route between databases on separate hosts.
+- Athena: Only routing between different connections is supported (e.g., different buckets, roles, or catalogs).
+- BigQuery: Only routing between databases in different projects is supported.
+- Databricks: When multi-catalog is not enabled, you can route between catalogs on the same host. If multi-catalog is enabled, then you can only route between databases on separate hosts.
+
+### Functionality limitations
+
+Database routing **can't be used** on databases with:
+
+- [Writeable connections](../databases/writeable-connection.md)
+- [Editable tables](../data-modeling/editable-tables.md)
+- [Actions](../actions/introduction.md)
+- [CSV uploads](../databases/uploads.md)
+- [Model persistence](../data-modeling/model-persistence.md)
+
+With **guest embedding**, database queries will always be routed to the router database. This is because guest embed users don't have Metabase accounts, so there are no user attributes available to determine which destination database to route to.
## How database routing works