Check the Database Target Before Cloudflare D1 Migrations

Before applying Cloudflare D1 migrations, check which database and environment the command will change. A D1 migration command needs an explicit database target: --local selects local SQLite state, while --remote selects an actual remote D1 database. Before applying SQL, separate the database name, application binding, execution location, and pending migrations. Then list migrations against the same target you intend to change.

Here is the answer in a form you can keep beside your terminal:

Identify: Match the database name to the intended project configuration; keep the binding separate.
Select: Choose --local or --remote explicitly, then list migrations for that target.
Decide: Review the pending SQL and apply only when the database, location, and intended changes agree.

This is a documentation-based operating system for a narrow problem: avoiding migration work against the wrong database. It does not cover the full installation process.

The receipt is documentation, not a production run

Documentation reviewed: 2026-09-09.

Test conditions: Documentation review only. No migration execution, customer database access, or production installation is evidenced here. The commands below are templates, and every example database name is hypothetical.

The D1 migrations reference establishes that migrations use versioned SQL files and support create, list, and apply operations. It also recommends using the database name rather than a binding name for migration commands because bindings may change.

The official D1 integration guide supplies the local-versus-remote distinction used here.

Those facts support a target-checking method. They do not establish that your configuration is correct or that your SQL is suitable for production.

A valid migration command still needs a verified destination.

Give each label a separate job

A database name and an application binding belong in different boxes on your checklist.

For migration commands, use the configured database name, following the official recommendation. Record the binding separately so you can reconcile the application configuration without treating that label as your preferred command target.

The execution flag answers another question: whether the operation concerns local SQLite state or the actual remote database.

Remote does not, by itself, mean production. Establish which remote database serves production from your actual configuration. Do not infer that role from the flag or from a reassuring name.

Finally, inspect the pending SQL. Knowing where a command will run does not tell you whether its changes belong there.

Check	What to record	Hold the operation when
Database name	The configured name of the intended database	The name was copied without checking the active project
Binding	The application binding associated with that database	You cannot reconcile the binding with the database configuration
Execution location	Explicit --local or --remote	The command leaves the intended location unclear
Remote role	Whether the selected remote database is production or another environment	You are assuming every remote database is production
Pending SQL	The migrations listed for the selected target and their file contents	You have not reviewed what would be applied

Artifact caption: Database target decision table. Complete it from the actual project configuration before choosing an apply command.

The table is deliberately repetitive about identity. A familiar label is useful for navigation, but it is weak evidence on its own.

Start from configuration, then construct the command

Open the configuration used by the project you are installing or maintaining. Locate the intended database entry and record its database name and binding.

If the project contains different deployment environments, establish which configuration context the intended command uses. Keep that context attached to the checklist. Consult the current official documentation for the options required by your setup.

For a hypothetical project, your note might read:

• Database name: example-journal-db
• Application binding: APP_DATABASE
• Intended operation: inspect local migration state
• Execution location: --local

These invented labels illustrate the distinction. They are not values to paste into an existing installation.

Construct the inspection command from the checked note. Avoid starting with an old apply command and editing whichever word looks relevant. That leaves too much of the decision hidden in terminal history.

List against the destination you actually mean

Use a list operation before deciding whether to apply:

npx wrangler d1 migrations list example-journal-db --local

For an intended remote inspection, the corresponding template is:

npx wrangler d1 migrations list example-journal-db --remote

Replace the hypothetical name with the checked database name. These are alternative target examples, not a sequence everyone must run.

Record which command produced the pending-migration list. Keep the database name, location flag, and relevant configuration context alongside the result.

Then open the listed SQL files and compare their changes with your intended operation. A filename can help you find a migration; the SQL is what you need to review.

A local list is evidence about the local target. It does not establish the pending migrations on a remote target. Likewise, inspecting one remote database does not verify another.

The list result belongs to the target that produced it.

If the result is surprising, pause. Recheck the configuration and migration files before interpreting the surprise as a reason to apply anything.

Make apply a separate decision

After inspection, choose the outcome explicitly:

Inspection result	Decision
Target identity is unresolved	Hold and resolve the configuration
Pending SQL does not match the intended change	Hold and review the migration files
No pending migration is reported	No pending SQL has been identified for that inspected target
Target and pending SQL match the intended change	Proceed to the applicable migration review and apply decision

An empty pending list does not prove application health, installation success, or agreement between local and remote databases.

When application is justified, preserve the checked destination. For the hypothetical local example:

npx wrangler d1 migrations apply example-journal-db --local

For an independently checked remote target:

npx wrangler d1 migrations apply example-journal-db --remote

Changing the location flag changes the destination under review. Repeat the target check when moving from local work to remote work.

Keep a receipt you can reuse

Copy this artifact into a private installation note:

D1 migration target check

Review date:
Project and configuration context:
Intended database role:
Configured database name:
Application binding:
Explicit location flag:
Exact list command:
Pending migration files:
SQL reviewed:
Unresolved questions:
Decision: hold / no pending SQL identified / ready for apply review
Exact proposed apply command:

This method addresses target confusion. It does not prove SQL correctness, runtime compatibility, or recovery readiness. No wrong-target incident or successful recovery is claimed here.

As an optional installation example, the Saju source license covers a Korean Saju web-app source package for a single project. Its product page supplies current deliverables and installation requirements. It does not establish that a buyer’s database has been checked.

The final decision is straightforward: complete the target receipt before applying migrations. If a field remains uncertain, resolve it before changing database state.

Related build logs

• Local AI Agent: Check the 24 GB Requirement Before Downloading

Evidence and scope

Evidence	What it supports	Boundary
Google Autocomplete, reviewed 2026-09-09	The exact query Cloudflare D1 migrations appeared in the current suggestion surface	A query-surface signal only; not search volume, ranking, purchase intent, or an outcome
Synthetic editorial example	Shows the fields or decision path discussed here	Not a measured production result

Reviewed on 2026-09-09 under a synthetic editorial condition; no private data, external send, or production outcome was used.

Limits and stop rule. This bounded example cannot establish every tool, data, permission, or maintenance condition. Stop when the input is sensitive, the expected output is unclear, or a person cannot review the result.