feat: various improvements to database commands (#8200)

##
fd77a17

Reworks the human-friendly output of `netlify database status ` into a
single _Migrations_ section (replacing the previous separate "Applied
migrations" and "Migrations not applied" sections).

Also fixed the apply-guidance: the `netlify database migrations apply`
hint only appears when truly targeting the local dev DB, and switches to
"Deploy these files to apply the migrations." when using a remote
database.

The `--json` output is now affected.

##
60c162d

Fixed `netlify database migrations pull` to match the server's new split
API. The list endpoint (`/database/migrations`) is now metadata-only and
a new per-migration endpoint (`/database/migrations/{name}`) returns the
SQL content, so the command now makes a list call followed by parallel
content fetches.

##
9bb834f

Added a shared `readApiErrorMessage` helper used by every CLI call site
that hits `/database/*`, which extracts the server's message field from
JSON error bodies so users see clean messages instead of raw JSON.

Author: eduardoboucas

src/commands/database/db-migration-pull.ts

@@ -6,6 +6,7 @@ import inquirer from 'inquirer'
 import { log, logJson } from '../../utils/command-helpers.js'
 import execa from '../../utils/execa.js'
 import BaseCommand from '../base-command.js'
+import { readApiErrorMessage } from './util/api-errors.js'
 import { PRODUCTION_BRANCH } from './util/constants.js'
 import { resolveMigrationsDirectory } from './util/migrations-path.js'
 
@@ -15,15 +16,28 @@ export interface MigrationPullOptions {
   json?: boolean
 }
 
-interface MigrationFile {
+interface MigrationListItem {
   version: number
   name: string
   path: string
-  content: string
+  applied: boolean
 }
 
 interface ListMigrationsResponse {
-  migrations: MigrationFile[]
+  migrations: MigrationListItem[]
+}
+
+interface MigrationDetailResponse {
+  version: number
+  name: string
+  path: string
+  content: string
+}
+
+interface ApiContext {
+  siteId: string
+  token: string
+  basePath: string
 }
 
 const getLocalGitBranch = async (): Promise<string> => {
@@ -45,7 +59,7 @@ const resolveBranch = async (branchOption: string | true | undefined): Promise<s
   return branchOption
 }
 
-const fetchMigrations = async (command: BaseCommand, branch: string | undefined): Promise<MigrationFile[]> => {
+const getApiContext = (command: BaseCommand): ApiContext => {
   const siteId = command.siteId
   if (!siteId) {
     throw new Error('The project must be linked with netlify link before pulling migrations.')
@@ -56,35 +70,60 @@ const fetchMigrations = async (command: BaseCommand, branch: string | undefined)
     throw new Error('You must be logged in with netlify login to pull migrations.')
   }
 
-  const token = accessToken.replace('Bearer ', '')
-  const basePath = command.netlify.api.basePath
+  return {
+    siteId,
+    token: accessToken.replace('Bearer ', ''),
+    basePath: command.netlify.api.basePath,
+  }
+}
 
-  const url = new URL(`${basePath}/sites/${encodeURIComponent(siteId)}/database/migrations`)
+const fetchMigrations = async (ctx: ApiContext, branch: string | undefined): Promise<MigrationListItem[]> => {
+  const url = new URL(`${ctx.basePath}/sites/${encodeURIComponent(ctx.siteId)}/database/migrations`)
   if (branch) {
     url.searchParams.set('branch', branch)
   }
 
   const response = await fetch(url, {
-    headers: {
-      Authorization: `Bearer ${token}`,
-    },
+    headers: { Authorization: `Bearer ${ctx.token}` },
   })
 
   if (!response.ok) {
-    const text = await response.text()
-    throw new Error(`Failed to fetch migrations (${String(response.status)}): ${text}`)
+    const message = await readApiErrorMessage(response)
+    throw new Error(`Failed to fetch migrations (${String(response.status)}): ${message}`)
   }
 
   const data = (await response.json()) as ListMigrationsResponse
   return data.migrations
 }
 
+const fetchMigrationContent = async (ctx: ApiContext, name: string, branch: string | undefined): Promise<string> => {
+  const url = new URL(
+    `${ctx.basePath}/sites/${encodeURIComponent(ctx.siteId)}/database/migrations/${encodeURIComponent(name)}`,
+  )
+  if (branch) {
+    url.searchParams.set('branch', branch)
+  }
+
+  const response = await fetch(url, {
+    headers: { Authorization: `Bearer ${ctx.token}` },
+  })
+
+  if (!response.ok) {
+    const message = await readApiErrorMessage(response)
+    throw new Error(`Failed to fetch content for migration "${name}" (${String(response.status)}): ${message}`)
+  }
+
+  const data = (await response.json()) as MigrationDetailResponse
+  return data.content
+}
+
 export const migrationPull = async (options: MigrationPullOptions, command: BaseCommand) => {
   const { force, json } = options
 
   const branch = (await resolveBranch(options.branch)) ?? process.env.NETLIFY_DB_BRANCH
   const source = branch ?? PRODUCTION_BRANCH
-  const migrations = await fetchMigrations(command, branch)
+  const ctx = getApiContext(command)
+  const migrations = await fetchMigrations(ctx, branch)
 
   if (migrations.length === 0) {
     if (json) {
@@ -96,6 +135,18 @@ export const migrationPull = async (options: MigrationPullOptions, command: Base
   }
 
   const migrationsDirectory = resolveMigrationsDirectory(command)
+  const canonicalMigrationsDir = resolve(migrationsDirectory)
+
+  const resolvedPaths = migrations.map((migration) => {
+    if (isAbsolute(migration.path) || migration.path.split(/[/\\]/).includes('..')) {
+      throw new Error(`Migration path "${migration.path}" contains invalid path segments.`)
+    }
+    const filePath = resolve(canonicalMigrationsDir, migration.path)
+    if (!filePath.startsWith(canonicalMigrationsDir)) {
+      throw new Error(`Migration path "${migration.path}" resolves outside the migrations directory.`)
+    }
+    return filePath
+  })
 
   if (!force) {
     const { confirmed } = await inquirer.prompt<{ confirmed: boolean }>([
@@ -115,22 +166,13 @@ export const migrationPull = async (options: MigrationPullOptions, command: Base
     }
   }
 
-  const canonicalMigrationsDir = resolve(migrationsDirectory)
+  const contents = await Promise.all(migrations.map((migration) => fetchMigrationContent(ctx, migration.name, branch)))
 
   await rm(canonicalMigrationsDir, { recursive: true, force: true })
 
-  for (const migration of migrations) {
-    if (isAbsolute(migration.path) || migration.path.split(/[/\\]/).includes('..')) {
-      throw new Error(`Migration path "${migration.path}" contains invalid path segments.`)
-    }
-
-    const filePath = resolve(canonicalMigrationsDir, migration.path)
-    if (!filePath.startsWith(canonicalMigrationsDir)) {
-      throw new Error(`Migration path "${migration.path}" resolves outside the migrations directory.`)
-    }
-
+  for (const [index, filePath] of resolvedPaths.entries()) {
     await mkdir(dirname(filePath), { recursive: true })
-    await writeFile(filePath, migration.content)
+    await writeFile(filePath, contents[index])
   }
 
   if (json) {

src/commands/database/db-status.ts

@@ -1,5 +1,5 @@
 import { readFile, readdir } from 'fs/promises'
-import { join } from 'path'
+import { join, relative, sep } from 'path'
 
 import { chalk, log, logJson, netlifyCommand } from '../../utils/command-helpers.js'
 import BaseCommand from '../base-command.js'
@@ -9,6 +9,7 @@ import {
   type MigrationFile,
   remoteAppliedMigrations,
 } from './util/applied-migrations.js'
+import { readApiErrorMessage } from './util/api-errors.js'
 import { connectToDatabase, detectExistingLocalConnectionString } from './util/db-connection.js'
 import { resolveMigrationsDirectory } from './util/migrations-path.js'
 import { fileExistsAsync } from '../../lib/fs.js'
@@ -48,7 +49,7 @@ const formatCommand = (suffix: string): string => chalk.cyanBright.bold(`${netli
 
 const logConnectCommands = () => {
   secondary(`Run ${formatCommand('database connect')} to start an interactive database client`)
-  secondary(`Run ${formatCommand('database connect --query "<SQL>"')} to run a one-shot query`)
+  secondary(`Run ${formatCommand(`database connect --query "SELECT 'SQL goes here'"`)} to run a one-shot query`)
 }
 
 const parseVersion = (name: string): number | null => {
@@ -176,8 +177,8 @@ const fetchBranchConnectionString = async (ctx: ServerContext, branchId: string)
   }
 
   if (!response.ok) {
-    const text = await response.text()
-    throw new Error(`Failed to fetch database branch "${branchId}" (${String(response.status)}): ${text}`)
+    const message = await readApiErrorMessage(response)
+    throw new Error(`Failed to fetch database branch "${branchId}" (${String(response.status)}): ${message}`)
   }
 
   const data = (await response.json()) as { connection_string?: string }
@@ -213,11 +214,11 @@ const fetchSiteDatabase = async (ctx: ServerContext): Promise<{ connectionString
   return { connectionString: data.connection_string }
 }
 
-const renderList = (items: MigrationEntry[]): string => {
+const renderList = (items: MigrationEntry[], indent = '  '): string => {
   if (items.length === 0) {
-    return chalk.dim('  (none)')
+    return chalk.dim(`${indent}(none)`)
   }
-  return items.map((m) => `  • ${m.name}`).join('\n')
+  return items.map((m) => `${indent}• ${m.name}`).join('\n')
 }
 
 interface RenderParams {
@@ -228,7 +229,9 @@ interface RenderParams {
   showCredentials: boolean
   status: MigrationsStatus
   isLocal: boolean
+  hasUrlOverride: boolean
   migrationsDirectory: string
+  projectRoot: string
   adminUrl?: string
 }
 
@@ -237,7 +240,8 @@ interface RenderParams {
 const INDENT = '     '
 const STATUS_GOOD = '🟢'
 const STATUS_WARN = '🟡'
-const STATUS_PAUSED = '⏸️ '
+const STATUS_NONE = '⚪'
+const STATUS_INFO = 'ℹ️ '
 
 const primary = (emoji: string, text: string): void => {
   log(`  ${emoji} ${text}`)
@@ -255,7 +259,9 @@ const renderPretty = (params: RenderParams) => {
     showCredentials,
     status,
     isLocal,
+    hasUrlOverride,
     migrationsDirectory,
+    projectRoot,
     adminUrl,
   } = params
 
@@ -301,7 +307,7 @@ const renderPretty = (params: RenderParams) => {
       secondary(`To connect to the database directly, use the connection string: ${displayed}`)
     }
   } else if (isLocal) {
-    primary(STATUS_PAUSED, 'The local database is not running')
+    primary(STATUS_INFO, 'The local database is not running')
     secondary(
       `It starts automatically when you run ${formatCommand(
         'dev',
@@ -311,29 +317,17 @@ const renderPretty = (params: RenderParams) => {
   }
 
   log('')
-  log(`Migrations directory: ${chalk.bold(migrationsDirectory)}`)
-
-  log('')
-  log(chalk.bold('Applied migrations'))
-  log(chalk.gray('Migrations that have been applied to the database branch'))
+  log(chalk.bold('Migrations'))
+  log(chalk.gray('Database migrations managed by Netlify'))
   log('')
-  log(renderList(status.applied))
-  log('')
-  log(
-    chalk.gray(
-      'Note that these migrations cannot be removed or edited. To change anything, you should generate a new migration.',
-    ),
-  )
 
   log('')
-  log(chalk.bold('Migrations not applied'))
-  log(chalk.gray("Migrations that exist locally that haven't yet been applied"))
-  log('')
-  log(renderList(status.pending))
-  if (isLocal && status.pending.length > 0 && status.outOfOrder.length === 0) {
-    log('')
-    log(chalk.gray(`Run ${formatCommand('database migrations apply')} to apply these to the local database.`))
-  }
+  const relativePath = relative(projectRoot, migrationsDirectory)
+  const isInsideProject = relativePath !== '' && !relativePath.startsWith('..')
+  const displayPath = (isInsideProject ? relativePath : migrationsDirectory).split(sep).join('/')
+  log(`  ${STATUS_INFO} ${chalk.bold('Migrations directory')}`)
+  log(chalk.gray(`${INDENT}Migration files in this directory are automatically applied when deploying to Netlify.`))
+  log(`${INDENT}${displayPath}`)
 
   if (status.missingOnDisk.length > 0 || status.outOfOrder.length > 0) {
     log('')
@@ -357,6 +351,35 @@ const renderPretty = (params: RenderParams) => {
       )
     }
   }
+
+  const appliedEmoji = status.applied.length > 0 ? STATUS_GOOD : STATUS_NONE
+  log('')
+  log(`  ${appliedEmoji} ${chalk.bold(`Applied migrations (${String(status.applied.length)})`)}`)
+  log(
+    chalk.gray(
+      `${INDENT}These migrations have been applied and cannot be edited or deleted. Any changes to the schema must involve a new migration.`,
+    ),
+  )
+  log(renderList(status.applied, INDENT))
+
+  log('')
+  const pendingEmoji = status.pending.length === 0 ? STATUS_GOOD : STATUS_WARN
+  log(`  ${pendingEmoji} ${chalk.bold(`Pending migrations (${String(status.pending.length)})`)}`)
+  log(
+    chalk.gray(
+      `${INDENT}These migrations are defined locally but haven't been applied, and you can change them or delete them.`,
+    ),
+  )
+  log(renderList(status.pending, INDENT))
+  if (status.pending.length > 0 && status.outOfOrder.length === 0) {
+    const canApplyLocally = isLocal && !hasUrlOverride
+    log('')
+    if (canApplyLocally) {
+      log(chalk.gray(`${INDENT}Run ${formatCommand('database migrations apply')} to apply them to the local database.`))
+    } else {
+      log(chalk.gray(`${INDENT}Deploy these files to apply the migrations.`))
+    }
+  }
 }
 
 export const statusDb = async (options: DatabaseStatusOptions, command: BaseCommand) => {
@@ -459,7 +482,9 @@ export const statusDb = async (options: DatabaseStatusOptions, command: BaseComm
     showCredentials: options.showCredentials ?? false,
     status,
     isLocal,
+    hasUrlOverride: Boolean(envUrl),
     migrationsDirectory,
+    projectRoot: buildDir,
     adminUrl: siteInfo?.admin_url,
   })
 }

src/commands/database/util/api-errors.ts

@@ -0,0 +1,20 @@
+interface ApiErrorBody {
+  code?: number
+  message?: string
+}
+
+export const readApiErrorMessage = async (response: Response): Promise<string> => {
+  const text = await response.text()
+  if (!text) {
+    return ''
+  }
+  try {
+    const body = JSON.parse(text) as ApiErrorBody
+    if (typeof body.message === 'string' && body.message.trim()) {
+      return body.message
+    }
+  } catch {
+    // body is not JSON; fall through to raw text
+  }
+  return text
+}

src/commands/database/util/applied-migrations.ts

@@ -1,5 +1,6 @@
 import { type SQLExecutor } from '@netlify/dev'
 
+import { readApiErrorMessage } from './api-errors.js'
 import { MIGRATIONS_TABLE } from './constants.js'
 
 export interface MigrationFile {
@@ -53,8 +54,8 @@ export const remoteAppliedMigrations =
     })
 
     if (!response.ok) {
-      const text = await response.text()
-      throw new Error(`Failed to fetch applied migrations (${String(response.status)}): ${text}`)
+      const message = await readApiErrorMessage(response)
+      throw new Error(`Failed to fetch applied migrations (${String(response.status)}): ${message}`)
     }
 
     const data = (await response.json()) as ListMigrationsResponse