From 52d375f5568fbbf31e978c0f0d190798caf09b9c Mon Sep 17 00:00:00 2001
From: Netlify Bot <mail@eduardoboucas.com>
Date: Mon, 20 Apr 2026 20:34:56 +0100
Subject: [PATCH] feat: support `NETLIFY_DB_BRANCH` env var in `db status`
 command

---
 src/commands/database/status-db.ts            | 15 ++++++----
 .../unit/commands/database/status-db.test.ts  | 29 +++++++++++++++++++
 2 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/src/commands/database/status-db.ts b/src/commands/database/status-db.ts
index 50a21f28882..00f17f3c278 100644
--- a/src/commands/database/status-db.ts
+++ b/src/commands/database/status-db.ts
@@ -361,6 +361,9 @@ export const statusDb = async (options: DatabaseStatusOptions, command: BaseComm
   }
   const enabled = Boolean(envUrl) || siteHasDatabase
 
+  // `--branch` can also be supplied via the NETLIFY_DB_BRANCH env var.
+  const branch = options.branch ?? process.env.NETLIFY_DB_BRANCH
+
   // Resolve what database we're looking at and how to fetch applied migrations.
   let branchLabel: string
   let connectionString: string | null = null
@@ -368,17 +371,17 @@ export const statusDb = async (options: DatabaseStatusOptions, command: BaseComm
   let cleanup: (() => Promise<void>) | undefined
   let isLocal = false
 
-  if (options.branch) {
+  if (branch) {
     if (!siteId) {
-      throw new Error(`The project must be linked with ${netlifyCommand()} link to use --branch.`)
+      throw new Error(`The project must be linked with ${netlifyCommand()} link to target a remote branch.`)
     }
     if (!accessToken) {
-      throw new Error(`You must be logged in with ${netlifyCommand()} login to use --branch.`)
+      throw new Error(`You must be logged in with ${netlifyCommand()} login to target a remote branch.`)
     }
 
-    connectionString = await fetchBranchConnectionString({ siteId, accessToken, basePath }, options.branch)
-    fetchApplied = remoteAppliedMigrations({ siteId, accessToken, basePath, branch: options.branch })
-    branchLabel = options.branch
+    connectionString = await fetchBranchConnectionString({ siteId, accessToken, basePath }, branch)
+    fetchApplied = remoteAppliedMigrations({ siteId, accessToken, basePath, branch })
+    branchLabel = branch
   } else {
     isLocal = true
     branchLabel = 'local'
diff --git a/tests/unit/commands/database/status-db.test.ts b/tests/unit/commands/database/status-db.test.ts
index dc7bc55ad94..0b435e3c960 100644
--- a/tests/unit/commands/database/status-db.test.ts
+++ b/tests/unit/commands/database/status-db.test.ts
@@ -185,10 +185,12 @@ beforeEach(() => {
   mockPackageJson({ dependencies: { '@netlify/database': '^1.0.0' } })
   setLocalDatabaseRunning(LOCAL_CONN_WITH_CREDS)
   delete process.env.NETLIFY_DB_URL
+  delete process.env.NETLIFY_DB_BRANCH
 })
 
 afterEach(() => {
   delete process.env.NETLIFY_DB_URL
+  delete process.env.NETLIFY_DB_BRANCH
 })
 
 describe('statusDb', () => {
@@ -632,5 +634,32 @@ describe('statusDb', () => {
 
       expect(logMessages.join('\n')).not.toContain('netlify db migrations apply')
     })
+
+    test('falls back to NETLIFY_DB_BRANCH env var when --branch is not passed', async () => {
+      process.env.NETLIFY_DB_BRANCH = 'feature-env'
+      setupFetchRouter({
+        siteDatabase: { connection_string: PROD_CONN },
+        branch: { 'feature-env': { connection_string: BRANCH_CONN } },
+        migrations: { 'feature-env': [] },
+      })
+
+      await statusDb({ json: true }, createMockCommand())
+
+      expect(jsonMessages[0]).toMatchObject({ target: 'feature-env' })
+      expect(mockConnectToDatabase).not.toHaveBeenCalled()
+    })
+
+    test('--branch wins over NETLIFY_DB_BRANCH when both are set', async () => {
+      process.env.NETLIFY_DB_BRANCH = 'env-branch'
+      setupFetchRouter({
+        siteDatabase: { connection_string: PROD_CONN },
+        branch: { 'flag-branch': { connection_string: BRANCH_CONN } },
+        migrations: { 'flag-branch': [] },
+      })
+
+      await statusDb({ branch: 'flag-branch', json: true }, createMockCommand())
+
+      expect(jsonMessages[0]).toMatchObject({ target: 'flag-branch' })
+    })
   })
 })