saward · saward · Mar 16, 2026 · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ LLM disclaimer: I (Mark) estimate that 90% of the code/design/architecture has b
 [![License](https://img.shields.io/badge/license-AGPL-blue.svg)](LICENSE)
 [![Docs](https://img.shields.io/badge/docs-spawn.dev-green)](https://docs.spawn.dev)
 
-**Stop treating your database like a script runner. Start treating it like a codebase.**
+**Treat your database code like a codebase.**
 
 I like to lean heavily on the database. I don't like tools that abstract away the raw power of databases like PostgreSQL. Spawn is designed for developers who want to use the full breadth of modern database features: Functions, Views, Triggers, RLS – while keeping the maintenance nightmares to a minimum.
 
@@ -243,7 +243,7 @@ Spawn supports **Provider Commands** – configure it to use `gcloud`, `aws`, or
 
 ```toml
 # spawn.toml
-[databases.prod]
+[targets.prod]
 command = {
     kind = "provider",
     provider = ["gcloud", "compute", "ssh", "--dry-run", ...],

diff --git a/docs/src/components/cli-options.ts b/docs/src/components/cli-options.ts
@@ -12,19 +12,19 @@ export const globalOptions: CLIOption[] = [
   { flag: "-d, --debug", description: "Turn on debug output." },
 ];
 
-/** The --database flag. Relevant to commands that read or validate the database config. */
-export const databaseOption: CLIOption[] = [
+/** The --target flag. Relevant to commands that read or validate the target config. */
+export const targetOption: CLIOption[] = [
   {
-    flag: "--database <name>",
-    description: "Select which database from spawn.toml to use.",
+    flag: "--target <name>",
+    description: "Select which target from spawn.toml to use.",
   },
 ];
 
 /** The --environment flag used by migration subcommands. */
 export const environmentOption: CLIOption[] = [
   {
     flag: "-e, --environment <name>",
-    description: "Override the environment for the database config.",
+    description: "Override the environment for the target config.",
   },
 ];
 

diff --git a/docs/src/content/docs/cli/check.mdx b/docs/src/content/docs/cli/check.mdx
@@ -4,11 +4,11 @@ description: Check your project for potential issues.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption } from "../../../components/cli-options";
+import { globalOptions, targetOption } from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn check"
-  options={[...databaseOption, ...globalOptions]}
+  options={[...targetOption, ...globalOptions]}
   exitCodes={[
     { code: "0", description: "No warnings found." },
     { code: "1", description: "One or more warnings found." },

diff --git a/docs/src/content/docs/cli/migration-adopt.mdx b/docs/src/content/docs/cli/migration-adopt.mdx
@@ -4,15 +4,19 @@ description: Mark a migration as applied without running it.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption, environmentOption } from "../../../components/cli-options";
+import {
+  globalOptions,
+  targetOption,
+  environmentOption,
+} from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn migration adopt [migration] [options]"
   options={[
     { flag: "--yes", description: "Skip confirmation prompt" },
     { flag: "--description <text>", description: "Reason for adoption (recorded in history)" },
     ...environmentOption,
-    ...databaseOption,
+    ...targetOption,
     ...globalOptions
   ]}
 >
@@ -32,6 +36,7 @@ Records a migration as applied in `_spawn.migration_history` without executing t
 ## Behavior
 
 Adoption creates a history entry with:
+
 - Status: `success`
 - Activity: `ADOPT`
 - Optional description explaining why it was adopted

diff --git a/docs/src/content/docs/cli/migration-apply.mdx b/docs/src/content/docs/cli/migration-apply.mdx
@@ -6,7 +6,7 @@ description: Apply migrations to the database.
 import CLICommand from "../../../components/CLICommand.astro";
 import {
   globalOptions,
-  databaseOption,
+  targetOption,
   environmentOption,
   variablesOption,
 } from "../../../components/cli-options";
@@ -19,7 +19,7 @@ import {
     { flag: "--yes", description: "Skip confirmation prompt" },
     { flag: "--retry", description: "Retry a previous migration" },
     ...environmentOption,
-    ...databaseOption,
+    ...targetOption,
     ...globalOptions
   ]}
 >

diff --git a/docs/src/content/docs/cli/migration-build.mdx b/docs/src/content/docs/cli/migration-build.mdx
@@ -6,7 +6,7 @@ description: Build a migration into final SQL.
 import CLICommand from "../../../components/CLICommand.astro";
 import {
   globalOptions,
-  databaseOption,
+  targetOption,
   environmentOption,
   variablesOption,
 } from "../../../components/cli-options";
@@ -17,7 +17,7 @@ import {
     { flag: "--pinned", description: "Use pinned component versions from lock.toml" },
     ...variablesOption,
     ...environmentOption,
-    ...databaseOption,
+    ...targetOption,
     ...globalOptions
   ]}
 >

diff --git a/docs/src/content/docs/cli/migration-new.mdx b/docs/src/content/docs/cli/migration-new.mdx
@@ -4,11 +4,15 @@ description: Create a new migration.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption, environmentOption } from "../../../components/cli-options";
+import {
+  globalOptions,
+  targetOption,
+  environmentOption,
+} from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn migration new <name>"
-  options={[...environmentOption, ...databaseOption, ...globalOptions]}
+  options={[...environmentOption, ...targetOption, ...globalOptions]}
 >
 
 Creates a new timestamped migration directory with a template `up.sql` file.

diff --git a/docs/src/content/docs/cli/migration-pin.mdx b/docs/src/content/docs/cli/migration-pin.mdx
@@ -4,11 +4,15 @@ description: Pin a migration to current component versions.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption, environmentOption } from "../../../components/cli-options";
+import {
+  globalOptions,
+  targetOption,
+  environmentOption,
+} from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn migration pin <migration>"
-  options={[...environmentOption, ...databaseOption, ...globalOptions]}
+  options={[...environmentOption, ...targetOption, ...globalOptions]}
 >
 
 Creates a snapshot of all components referenced by the migration and stores them in the content-addressable `pinned/` directory. Writes a `lock.toml` file in the migration folder with the snapshot hash.

diff --git a/docs/src/content/docs/cli/migration-status.mdx b/docs/src/content/docs/cli/migration-status.mdx
@@ -4,11 +4,15 @@ description: Show migration status across filesystem and database.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption, environmentOption } from "../../../components/cli-options";
+import {
+  globalOptions,
+  targetOption,
+  environmentOption,
+} from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn migration status"
-  options={[...environmentOption, ...databaseOption, ...globalOptions]}
+  options={[...environmentOption, ...targetOption, ...globalOptions]}
 >
 
 Displays a table showing the status of all migrations from both the filesystem and database.

diff --git a/docs/src/content/docs/cli/test-build.mdx b/docs/src/content/docs/cli/test-build.mdx
@@ -4,11 +4,11 @@ description: Build a test into final SQL.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption } from "../../../components/cli-options";
+import { globalOptions, targetOption } from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn test build <name>"
-  options={[...databaseOption, ...globalOptions]}
+  options={[...targetOption, ...globalOptions]}
 >
 
 Renders a test's `test.sql` template into final SQL, resolving component includes and template variables. Outputs to stdout.

diff --git a/docs/src/content/docs/cli/test-compare.mdx b/docs/src/content/docs/cli/test-compare.mdx
@@ -4,11 +4,11 @@ description: Run tests and compare output to expected results.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption } from "../../../components/cli-options";
+import { globalOptions, targetOption } from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn test compare <name>"
-  options={[...databaseOption, ...globalOptions]}
+  options={[...targetOption, ...globalOptions]}
 >
 
 Runs tests and compares their output against saved expected results, reporting any differences.

diff --git a/docs/src/content/docs/cli/test-expect.mdx b/docs/src/content/docs/cli/test-expect.mdx
@@ -4,11 +4,11 @@ description: Update expected test output.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption } from "../../../components/cli-options";
+import { globalOptions, targetOption } from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn test expect <name>"
-  options={[...databaseOption, ...globalOptions]}
+  options={[...targetOption, ...globalOptions]}
 >
 
 Runs a test and saves its output as the new expected result for future comparisons.

diff --git a/docs/src/content/docs/cli/test-new.mdx b/docs/src/content/docs/cli/test-new.mdx
@@ -4,11 +4,11 @@ description: Create a new test.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption } from "../../../components/cli-options";
+import { globalOptions, targetOption } from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn test new <name>"
-  options={[...databaseOption, ...globalOptions]}
+  options={[...targetOption, ...globalOptions]}
 >
 
 Creates a new test directory with a template `test.sql` file.

diff --git a/docs/src/content/docs/cli/test-run.mdx b/docs/src/content/docs/cli/test-run.mdx
@@ -4,11 +4,11 @@ description: Run tests against the database.
 ---
 
 import CLICommand from "../../../components/CLICommand.astro";
-import { globalOptions, databaseOption } from "../../../components/cli-options";
+import { globalOptions, targetOption } from "../../../components/cli-options";
 
 <CLICommand
   usage="spawn test run <name>"
-  options={[...databaseOption, ...globalOptions]}
+  options={[...targetOption, ...globalOptions]}
 >
 
 Executes one or all tests against the configured database and displays the results.

diff --git a/docs/src/content/docs/getting-started/magic.mdx b/docs/src/content/docs/getting-started/magic.mdx
@@ -582,11 +582,11 @@ $$ LANGUAGE plpgsql;
 COMMIT;
 ```
 
-But if we edit the database in `spawn.toml` to specify that it is a dev environment, like so:
+But if we edit the target in `spawn.toml` to specify that it is a dev environment, like so:
 
 ```toml {6}
 ...
-[databases.postgres_psql]
+[targets.postgres_psql]
 engine = "postgres-psql"
 spawn_database = "postgres"
 spawn_schema = "_spawn"

diff --git a/docs/src/content/docs/guides/manage-databases.md b/docs/src/content/docs/guides/manage-databases.md
@@ -3,15 +3,15 @@ title: Database Connections
 description: How to configure database connections in spawn.toml
 ---
 
-Spawn requires a database connection to apply migrations and run tests. Database connections are configured in your `spawn.toml` file under the `[databases]` section. See the [configuration reference](/reference/config/#database-configurations) for the full list of database fields.
+Spawn requires a database connection to apply migrations and run tests. Database connections are configured in your `spawn.toml` file under the `[targets]` section. See the [configuration reference](/reference/config/#target-configurations) for the full list of target fields.
 
 ## Basic Configuration
 
-Each database configuration requires:
+Each target configuration requires:
 
 - `engine`: The database engine type (currently only `"postgres-psql"`)
-- `spawn_database`: The database name to connect to
-- `spawn_schema`: The schema where spawn stores migration tracking (default: `"_spawn"`)
+- `spawn_database`: The database where spawn stores migration tracking (defaults to using whichever database your command connects to by default). This database must already exist.
+- `spawn_schema`: The schema where spawn stores migration tracking (default: `"_spawn"`). This schema will be created if it does not exist.
 - `environment`: Environment name (e.g., `"dev"`, `"prod"`)
 - `command`: How to execute SQL commands (see below)
 
@@ -24,7 +24,7 @@ The `command` field specifies how spawn should execute SQL against your database
 Use a direct command when you have a straightforward way to connect to your database.
 
 ```toml
-[databases.local]
+[targets.local]
 engine = "postgres-psql"
 spawn_database = "myapp"
 spawn_schema = "_spawn"
@@ -37,7 +37,7 @@ command = { kind = "direct", direct = ["psql", "-U", "postgres", "myapp"] }
 For databases running in Docker:
 
 ```toml
-[databases.docker_local]
+[targets.docker_local]
 engine = "postgres-psql"
 spawn_database = "myapp"
 spawn_schema = "_spawn"
@@ -56,7 +56,7 @@ command = {
 Provider commands are useful when the connection details need to be resolved dynamically, such as with cloud providers where connection setup is slow but the underlying connection is fast.
 
 ```toml
-[databases.staging]
+[targets.staging]
 engine = "postgres-psql"
 spawn_database = "myapp"
 spawn_schema = "_spawn"
@@ -93,7 +93,7 @@ The provider pattern resolves the SSH command once using `gcloud compute ssh --d
 You can use the gcloud command directly, but this will be called multiple times during a single `spawn migration apply` command.
 
 ```toml
-[databases.staging_slow]
+[targets.staging_slow]
 engine = "postgres-psql"
 spawn_database = "myapp"
 spawn_schema = "_spawn"
@@ -118,7 +118,7 @@ command = {
 You can also use gcloud to provide the underlying ssh command needed to connect, which will be resolved just once, and then every connection to the database will use the provided ssh command directly.
 
 ```toml
-[databases.staging]
+[targets.staging]
 engine = "postgres-psql"
 spawn_database = "myapp"
 spawn_schema = "_spawn"
@@ -178,10 +178,10 @@ ssh-add ~/.ssh/your_key
 ```toml
 # spawn.toml
 spawn_folder = "spawn"
-database = "local"  # Default database
+target = "local"  # Default target
 
 # Local development (Docker)
-[databases.local]
+[targets.local]
 engine = "postgres-psql"
 spawn_database = "myapp"
 spawn_schema = "_spawn"
@@ -192,7 +192,7 @@ command = {
 }
 
 # Staging (Google Cloud via provider - fast!)
-[databases.staging]
+[targets.staging]
 engine = "postgres-psql"
 spawn_database = "myapp"
 spawn_schema = "_spawn"
@@ -210,7 +210,7 @@ command = {
 }
 
 # Production (Google Cloud via provider - fast!)
-[databases.production]
+[targets.production]
 engine = "postgres-psql"
 spawn_database = "myapp"
 spawn_schema = "_spawn"
@@ -231,28 +231,28 @@ command = {
 Usage:
 
 ```bash
-# Use local database (default)
+# Use local target (default)
 spawn migration apply <migration name>
 
-# Use staging database
-spawn --database staging migration apply <migration name>
+# Use staging target
+spawn --target staging migration apply <migration name>
 
-# Use production database
-spawn --database production migration apply <migration name>
+# Use production target
+spawn --target production migration apply <migration name>
 ```
 
 ## Advanced Configuration
 
-### Multiple Databases
+### Multiple Targets
 
-You can configure multiple databases and switch between them:
+You can configure multiple targets and switch between them:
 
 ```bash
-# Use specific database
-spawn --database staging migration build my-migration
+# Use specific target
+spawn --target staging migration build my-migration
 
 # Override in environment variable
-export SPAWN_DATABASE=production
+export SPAWN_TARGET=production
 spawn migration apply
 ```