diff --git a/docs/getting-started.qmd b/docs/getting-started.qmd
index a56fa1b7..1198eaa3 100644
--- a/docs/getting-started.qmd
+++ b/docs/getting-started.qmd
@@ -157,7 +157,7 @@ In the `server()` function in the **app.R** file, add rich functionality to your
## 5. Setup your database connection
-Setup your database connection using the `sd_db_config()` function. Once your configuration credentials are created (they get saved in a `.env` file), make a connection to your database using the `sd_db_connect()` function in the global settings at the top of the **app.R** file. You can also use `sd_db_connect(ignore = TRUE)` to run the survey without storing data. See the [Storing Data](storing-data.qmd) page for more details.
+Setup your database connection using the `sd_db_config()` function. Once your configuration credentials are created (they get saved in a `.env` file), make a connection to your database using the `sd_db_connect()` function in the global settings at the top of the **app.R** file. To run the survey locally without storing data to a database, set `mode: preview` in your `survey.qmd` YAML. See the [Storing Data](storing-data.qmd) page for more details on the available modes.
## 6. Locally preview
diff --git a/docs/storing-data.qmd b/docs/storing-data.qmd
index aac90b6f..5345c74b 100644
--- a/docs/storing-data.qmd
+++ b/docs/storing-data.qmd
@@ -4,11 +4,11 @@ title: "Storing Data"
Survey response data is stored in a PostgreSQL database. We recommend using {{< var supabase >}} as a free and open-source option, though you can use any service you want. In this guide, we'll walk you through the steps for setting up a Supabase project and connecting your surveydown survey to it.
-## Local data preview
+## Survey modes
-When you run a survey without a database connection, response data will be locally stored in a `preview_data.csv` file. As the name suggests, this is for preview purposes only. It is there to help you understand what the actual survey response data will look like once you get your database connection properly configured.
+surveydown supports three operating modes — `database`, `preview`, and `local` — controlled by the `mode` setting in your `survey.qmd` YAML header. These modes determine how and where your response data is stored. See the [Survey Settings](survey-settings.qmd#mode) page for full documentation on each mode.
-This file is **not** where your actual survey response data will be saved. If you deploy your survey live without a database connection, no responses will be saved.
+In short: set `mode: preview` while building your survey, which stores data locally, then remove it (or set it to `database`) before deploying to store in a database, or set it to `local` to run the survey on a single computer and store data locally.
## Setting up a Supabase project
@@ -92,23 +92,21 @@ This will open a new browser window where you can navigate to the dashboard for
See the [Local Dashboard](local-dashboard.html) page for more information.
-## Connecting to your database in surveydown
+## Connecting to the database
-Now that you have set your credentials stored, you can connect to your database in surveydown by running the following code in your **app.R** file:
+Once your credentials are stored in a `.env` file, add the following to your **app.R** file in the global scope to connect your survey to the database:
-```{r}
+```r
db <- sd_db_connect()
```
-You do not need to specify any arguments to this function as it will automatically use the credentials stored in your `.env` file. If the connection is successful, you should see a message in the console that says "✔ Successfully connected to the database."
-
-You can also ignore the database connection by setting `ignore = TRUE` in `sd_db_connect()`:
+This reads your credentials from the `.env` file. If the connection is successful, a message prints to the console confirming it. The survey mode (`database`, `preview`, or `local`) is controlled via the `mode` key in your `survey.qmd` YAML — not by `sd_db_connect()`.
-```{r}
-db <- sd_db_connect(ignore = TRUE)
-```
+If the database connection fails (e.g. no `.env` file or incorrect credentials), a red banner appears at the bottom of every survey page. See [Trouble connecting?](#trouble-connecting) below if this happens unexpectedly.
-With this setting, no database connection will be attempted, and the `db` object will store the value `NULL`. Instead, data will be stored in a local `preview_data.csv` file for previewing purposes only. This is useful when you are still editing your survey and do not want to store any data in your database yet.
+::: {.callout-note}
+The `ignore = TRUE` argument in `sd_db_connect()` is deprecated. Use `mode: preview` in your YAML instead.
+:::
## Table creation and data operations
diff --git a/docs/survey-settings.qmd b/docs/survey-settings.qmd
index 6b359e7b..2082c4ce 100644
--- a/docs/survey-settings.qmd
+++ b/docs/survey-settings.qmd
@@ -26,6 +26,7 @@ theme-settings:
footer-right: ''
survey-settings:
+ mode: database
show-previous: no
use-cookies: yes
auto-scroll: no
@@ -131,6 +132,45 @@ footer-right: Footer Right Test
## Survey settings
+### Mode
+
+The `mode` setting controls how your survey stores response data. There are three options:
+
+| Mode | CSV file | Banner | Use case |
+|------|----------|--------|----------|
+| `database` (default) | — | Red footer banner if connection fails | Live deployment; responses stored in PostgreSQL. |
+| `preview` | `preview_data.csv` | Yellow footer banner on every page | Testing before deployment. |
+| `local` | `local_data.csv` | None | Intentional offline data collection. |
+
+Set the mode in the `survey-settings` section of your `survey.qmd` YAML header:
+
+``` yaml
+survey-settings:
+ mode: preview
+```
+
+Since `database` is the default, you only need to set `mode` when using `preview` or `local`. When you are ready to deploy, remove the `mode` key (or set it back to `database`), then run the app once locally so the change is picked up before deploying.
+
+**Preview mode** shows a yellow banner at the bottom of every page, making it immediately obvious that responses are not being saved to the database:
+
+
+
+
+
+
+
+**Local mode** is for intentional offline data collection — no internet connection required, no banner shown, and responses are saved to a `local_data.csv` file in your project folder.
+
+If `mode` is set to `database` but the connection fails (e.g. no `.env` file or incorrect credentials), a red banner appears instead:
+
+
+
+
+
+
+
+See the [Storing Data](storing-data.qmd) page for full details on database setup and connection configuration.
+
### Cookies
Cookies are used to store user sessions, including their session ID, survey data storage (backend), and their survey progress (frontend).
diff --git a/images/screenshots/mode-db-fail.png b/images/screenshots/mode-db-fail.png
new file mode 100644
index 00000000..a1e157ac
Binary files /dev/null and b/images/screenshots/mode-db-fail.png differ
diff --git a/images/screenshots/mode-preview.png b/images/screenshots/mode-preview.png
new file mode 100644
index 00000000..4314a889
Binary files /dev/null and b/images/screenshots/mode-preview.png differ