From d2d40a76b483ae5487c303d5d967af3de2ad00ed Mon Sep 17 00:00:00 2001
From: Netlify Bot <mail@eduardoboucas.com>
Date: Mon, 20 Apr 2026 22:47:32 +0100
Subject: [PATCH] feat: restructure db command files

---
 src/commands/database/database.ts             | 41 ++++++-------------
 .../database/{connect.ts => db-connect.ts}    |  6 +--
 .../database/{migrate.ts => db-migrate.ts}    |  5 ++-
 .../{migration-new.ts => db-migration-new.ts} | 17 +-------
 ...migration-pull.ts => db-migration-pull.ts} |  2 +-
 .../database/{reset.ts => db-reset.ts}        |  2 +-
 .../database/{status-db.ts => db-status.ts}   | 20 ++-------
 .../database/{ => legacy}/constants.ts        |  2 -
 .../database/{init.ts => legacy/db-init.ts}   |  6 +--
 .../{status.ts => legacy/db-status.ts}        |  6 +--
 src/commands/database/{ => legacy}/drizzle.ts |  2 +-
 src/commands/database/legacy/types.ts         | 16 ++++++++
 src/commands/database/{ => legacy}/utils.ts   |  4 +-
 .../database/{ => util}/applied-migrations.ts |  0
 src/commands/database/util/constants.ts       |  2 +
 .../database/{ => util}/db-connection.ts      |  0
 .../database/{ => util}/meta-commands.ts      |  0
 src/commands/database/util/migrations-path.ts | 24 +++++++++++
 .../database/{ => util}/pg-client-executor.ts |  0
 .../database/{ => util}/psql-formatter.ts     |  0
 .../{migrate.test.ts => db-migrate.test.ts}   |  6 +--
 ...n-new.test.ts => db-migration-new.test.ts} | 16 ++++----
 ...pull.test.ts => db-migration-pull.test.ts} |  6 +--
 .../{reset.test.ts => db-reset.test.ts}       |  4 +-
 .../{status-db.test.ts => db-status.test.ts}  |  6 +--
 25 files changed, 94 insertions(+), 99 deletions(-)
 rename src/commands/database/{connect.ts => db-connect.ts} (95%)
 rename src/commands/database/{migrate.ts => db-migrate.ts} (81%)
 rename src/commands/database/{migration-new.ts => db-migration-new.ts} (89%)
 rename src/commands/database/{migration-pull.ts => db-migration-pull.ts} (98%)
 rename src/commands/database/{reset.ts => db-reset.ts} (92%)
 rename src/commands/database/{status-db.ts => db-status.ts} (96%)
 rename src/commands/database/{ => legacy}/constants.ts (69%)
 rename src/commands/database/{init.ts => legacy/db-init.ts} (97%)
 rename src/commands/database/{status.ts => legacy/db-status.ts} (95%)
 rename src/commands/database/{ => legacy}/drizzle.ts (98%)
 create mode 100644 src/commands/database/legacy/types.ts
 rename src/commands/database/{ => legacy}/utils.ts (98%)
 rename src/commands/database/{ => util}/applied-migrations.ts (100%)
 create mode 100644 src/commands/database/util/constants.ts
 rename src/commands/database/{ => util}/db-connection.ts (100%)
 rename src/commands/database/{ => util}/meta-commands.ts (100%)
 create mode 100644 src/commands/database/util/migrations-path.ts
 rename src/commands/database/{ => util}/pg-client-executor.ts (100%)
 rename src/commands/database/{ => util}/psql-formatter.ts (100%)
 rename tests/unit/commands/database/{migrate.test.ts => db-migrate.test.ts} (95%)
 rename tests/unit/commands/database/{migration-new.test.ts => db-migration-new.test.ts} (94%)
 rename tests/unit/commands/database/{migration-pull.test.ts => db-migration-pull.test.ts} (98%)
 rename tests/unit/commands/database/{reset.test.ts => db-reset.test.ts} (95%)
 rename tests/unit/commands/database/{status-db.test.ts => db-status.test.ts} (99%)

diff --git a/src/commands/database/database.ts b/src/commands/database/database.ts
index 7ccc40d9865..aa0e809b931 100644
--- a/src/commands/database/database.ts
+++ b/src/commands/database/database.ts
@@ -1,27 +1,10 @@
 import { Option } from 'commander'
 import inquirer from 'inquirer'
 import BaseCommand from '../base-command.js'
-import type { DatabaseBoilerplateType, DatabaseInitOptions } from './init.js'
-import type { MigrationNewOptions } from './migration-new.js'
-import type { MigrationPullOptions } from './migration-pull.js'
-import type { DatabaseStatusOptions } from './status-db.js'
-
-export type Extension = {
-  id: string
-  name: string
-  slug: string
-  hostSiteUrl: string
-  installedOnTeam: boolean
-}
-
-export type SiteInfo = {
-  id: string
-  name: string
-  account_id: string
-  admin_url: string
-  url: string
-  ssl_url: string
-}
+import type { DatabaseBoilerplateType, DatabaseInitOptions } from './legacy/db-init.js'
+import type { MigrationNewOptions } from './db-migration-new.js'
+import type { MigrationPullOptions } from './db-migration-pull.js'
+import type { DatabaseStatusOptions } from './db-status.js'
 
 const supportedBoilerplates = new Set<DatabaseBoilerplateType>(['drizzle'])
 
@@ -54,7 +37,7 @@ export const createDatabaseCommand = (program: BaseCommand) => {
       .option('--no-boilerplate', "Don't add any boilerplate to your project.")
       .option('-o, --overwrite', 'Overwrites existing files that would be created when setting up boilerplate')
       .action(async (_options: Record<string, unknown>, command: BaseCommand) => {
-        const { init } = await import('./init.js')
+        const { init } = await import('./legacy/db-init.js')
 
         // Only prompt for drizzle if the user did not specify a boilerplate option, and if we're in
         // interactive mode
@@ -85,7 +68,7 @@ export const createDatabaseCommand = (program: BaseCommand) => {
       .command('status')
       .description(`Check the status of the database`)
       .action(async (options, command) => {
-        const { status } = await import('./status.js')
+        const { status } = await import('./legacy/db-status.js')
         // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
         await status(options, command)
       })
@@ -103,7 +86,7 @@ export const createDatabaseCommand = (program: BaseCommand) => {
       )
       .option('--json', 'Output result as JSON')
       .action(async (options: DatabaseStatusOptions, command: BaseCommand) => {
-        const { statusDb } = await import('./status-db.js')
+        const { statusDb } = await import('./db-status.js')
         await statusDb(options, command)
       })
       .addExamples([
@@ -122,7 +105,7 @@ export const createDatabaseCommand = (program: BaseCommand) => {
         'Output query results as JSON. When used without --query, prints the connection details as JSON instead.',
       )
       .action(async (options: { query?: string; json?: boolean }, command: BaseCommand) => {
-        const { connect } = await import('./connect.js')
+        const { connect } = await import('./db-connect.js')
         await connect(options, command)
       })
       .addExamples([
@@ -137,7 +120,7 @@ export const createDatabaseCommand = (program: BaseCommand) => {
       .description('Reset the local development database, removing all data and tables')
       .option('--json', 'Output result as JSON')
       .action(async (options: { json?: boolean }, command: BaseCommand) => {
-        const { reset } = await import('./reset.js')
+        const { reset } = await import('./db-reset.js')
         await reset(options, command)
       })
 
@@ -149,7 +132,7 @@ export const createDatabaseCommand = (program: BaseCommand) => {
       .option('--to <name>', 'Target migration name or prefix to apply up to (applies all if omitted)')
       .option('--json', 'Output result as JSON')
       .action(async (options: { to?: string; json?: boolean }, command: BaseCommand) => {
-        const { migrate } = await import('./migrate.js')
+        const { migrate } = await import('./db-migrate.js')
         await migrate(options, command)
       })
 
@@ -165,7 +148,7 @@ export const createDatabaseCommand = (program: BaseCommand) => {
       )
       .option('--json', 'Output result as JSON')
       .action(async (options: MigrationNewOptions, command: BaseCommand) => {
-        const { migrationNew } = await import('./migration-new.js')
+        const { migrationNew } = await import('./db-migration-new.js')
         await migrationNew(options, command)
       })
       .addExamples([
@@ -183,7 +166,7 @@ export const createDatabaseCommand = (program: BaseCommand) => {
       .option('--force', 'Skip confirmation prompt', false)
       .option('--json', 'Output result as JSON')
       .action(async (options: MigrationPullOptions, command: BaseCommand) => {
-        const { migrationPull } = await import('./migration-pull.js')
+        const { migrationPull } = await import('./db-migration-pull.js')
         await migrationPull(options, command)
       })
       .addExamples([
diff --git a/src/commands/database/connect.ts b/src/commands/database/db-connect.ts
similarity index 95%
rename from src/commands/database/connect.ts
rename to src/commands/database/db-connect.ts
index f56bf4e71d9..c7577294b90 100644
--- a/src/commands/database/connect.ts
+++ b/src/commands/database/db-connect.ts
@@ -2,9 +2,9 @@ import readline from 'readline'
 
 import { log, logJson } from '../../utils/command-helpers.js'
 import BaseCommand from '../base-command.js'
-import { connectRawClient } from './db-connection.js'
-import { executeMetaCommand } from './meta-commands.js'
-import { formatQueryResult } from './psql-formatter.js'
+import { connectRawClient } from './util/db-connection.js'
+import { executeMetaCommand } from './util/meta-commands.js'
+import { formatQueryResult } from './util/psql-formatter.js'
 
 export interface ConnectOptions {
   query?: string
diff --git a/src/commands/database/migrate.ts b/src/commands/database/db-migrate.ts
similarity index 81%
rename from src/commands/database/migrate.ts
rename to src/commands/database/db-migrate.ts
index 4404a8b4c70..c99943822b6 100644
--- a/src/commands/database/migrate.ts
+++ b/src/commands/database/db-migrate.ts
@@ -2,7 +2,8 @@ import { applyMigrations } from '@netlify/dev'
 
 import { log, logJson } from '../../utils/command-helpers.js'
 import BaseCommand from '../base-command.js'
-import { connectToDatabase } from './db-connection.js'
+import { connectToDatabase } from './util/db-connection.js'
+import { DEFAULT_MIGRATIONS_PATH } from './util/migrations-path.js'
 
 export interface MigrateOptions {
   to?: string
@@ -19,7 +20,7 @@ export const migrate = async (options: MigrateOptions, command: BaseCommand) =>
   const migrationsDirectory = command.netlify.config.db?.migrations?.path
   if (!migrationsDirectory) {
     throw new Error(
-      'No migrations directory found. Create a directory at netlify/db/migrations or set `db.migrations.path` in `netlify.toml`.',
+      `No migrations directory found. Create a directory at ${DEFAULT_MIGRATIONS_PATH} or set \`db.migrations.path\` in \`netlify.toml\`.`,
     )
   }
 
diff --git a/src/commands/database/migration-new.ts b/src/commands/database/db-migration-new.ts
similarity index 89%
rename from src/commands/database/migration-new.ts
rename to src/commands/database/db-migration-new.ts
index ebfab8886e1..79bf624bbbb 100644
--- a/src/commands/database/migration-new.ts
+++ b/src/commands/database/db-migration-new.ts
@@ -5,6 +5,7 @@ import inquirer from 'inquirer'
 
 import { log, logJson } from '../../utils/command-helpers.js'
 import BaseCommand from '../base-command.js'
+import { resolveMigrationsDirectory } from './util/migrations-path.js'
 
 export type NumberingScheme = 'sequential' | 'timestamp'
 
@@ -80,22 +81,6 @@ const getExistingMigrationNames = async (migrationsDirectory: string): Promise<s
   }
 }
 
-const DEFAULT_MIGRATIONS_PATH = 'netlify/db/migrations'
-
-export const resolveMigrationsDirectory = (command: BaseCommand): string => {
-  const configuredPath = command.netlify.config.db?.migrations?.path
-  if (configuredPath) {
-    return configuredPath
-  }
-
-  const projectRoot = command.netlify.site.root ?? command.project.root ?? command.project.baseDirectory
-  if (!projectRoot) {
-    throw new Error('Could not determine the project root directory.')
-  }
-
-  return join(projectRoot, DEFAULT_MIGRATIONS_PATH)
-}
-
 export const migrationNew = async (options: MigrationNewOptions, command: BaseCommand) => {
   const { json } = options
 
diff --git a/src/commands/database/migration-pull.ts b/src/commands/database/db-migration-pull.ts
similarity index 98%
rename from src/commands/database/migration-pull.ts
rename to src/commands/database/db-migration-pull.ts
index f4e3a793fa4..8a9b55a92ed 100644
--- a/src/commands/database/migration-pull.ts
+++ b/src/commands/database/db-migration-pull.ts
@@ -6,7 +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 { resolveMigrationsDirectory } from './migration-new.js'
+import { resolveMigrationsDirectory } from './util/migrations-path.js'
 
 export interface MigrationPullOptions {
   branch?: string | true
diff --git a/src/commands/database/reset.ts b/src/commands/database/db-reset.ts
similarity index 92%
rename from src/commands/database/reset.ts
rename to src/commands/database/db-reset.ts
index e75a37d976f..4a54d678183 100644
--- a/src/commands/database/reset.ts
+++ b/src/commands/database/db-reset.ts
@@ -2,7 +2,7 @@ import { resetDatabase } from '@netlify/dev'
 
 import { log, logJson } from '../../utils/command-helpers.js'
 import BaseCommand from '../base-command.js'
-import { connectToDatabase } from './db-connection.js'
+import { connectToDatabase } from './util/db-connection.js'
 
 export interface ResetOptions {
   json?: boolean
diff --git a/src/commands/database/status-db.ts b/src/commands/database/db-status.ts
similarity index 96%
rename from src/commands/database/status-db.ts
rename to src/commands/database/db-status.ts
index 00f17f3c278..feb020cc9ca 100644
--- a/src/commands/database/status-db.ts
+++ b/src/commands/database/db-status.ts
@@ -7,8 +7,9 @@ import {
   localAppliedMigrations,
   type MigrationFile,
   remoteAppliedMigrations,
-} from './applied-migrations.js'
-import { connectToDatabase, detectExistingLocalConnectionString } from './db-connection.js'
+} from './util/applied-migrations.js'
+import { connectToDatabase, detectExistingLocalConnectionString } from './util/db-connection.js'
+import { resolveMigrationsDirectory } from './util/migrations-path.js'
 
 export interface DatabaseStatusOptions {
   branch?: string
@@ -38,7 +39,6 @@ interface ServerContext {
   basePath: string
 }
 
-const DEFAULT_MIGRATIONS_PATH = 'netlify/db/migrations'
 const DOCS_URL = 'https://ntl.fyi/database'
 const NETLIFY_DATABASE_PACKAGE = '@netlify/database'
 
@@ -58,20 +58,6 @@ const parseVersion = (name: string): number | null => {
   return Number.isFinite(parsed) ? parsed : null
 }
 
-const resolveMigrationsDirectory = (command: BaseCommand): string => {
-  const configuredPath = command.netlify.config.db?.migrations?.path
-  if (configuredPath) {
-    return configuredPath
-  }
-
-  const projectRoot = command.netlify.site.root ?? command.project.root ?? command.project.baseDirectory
-  if (!projectRoot) {
-    throw new Error('Could not determine the project root directory.')
-  }
-
-  return `${projectRoot}/${DEFAULT_MIGRATIONS_PATH}`
-}
-
 const readLocalMigrations = async (migrationsDirectory: string): Promise<MigrationEntry[]> => {
   let entries
   try {
diff --git a/src/commands/database/constants.ts b/src/commands/database/legacy/constants.ts
similarity index 69%
rename from src/commands/database/constants.ts
rename to src/commands/database/legacy/constants.ts
index a6ac5f85dd6..3512f40e303 100644
--- a/src/commands/database/constants.ts
+++ b/src/commands/database/legacy/constants.ts
@@ -1,5 +1,3 @@
 export const NEON_DATABASE_EXTENSION_SLUG = process.env.NEON_DATABASE_EXTENSION_SLUG ?? 'neon'
 export const JIGSAW_URL = process.env.JIGSAW_URL ?? 'https://jigsaw.services-prod.nsvcs.net'
 export const NETLIFY_NEON_PACKAGE_NAME = '@netlify/neon'
-export const MIGRATIONS_SCHEMA = 'netlify'
-export const MIGRATIONS_TABLE = `${MIGRATIONS_SCHEMA}.migrations`
diff --git a/src/commands/database/init.ts b/src/commands/database/legacy/db-init.ts
similarity index 97%
rename from src/commands/database/init.ts
rename to src/commands/database/legacy/db-init.ts
index 7e6f6cd52c7..84b2fee7c15 100644
--- a/src/commands/database/init.ts
+++ b/src/commands/database/legacy/db-init.ts
@@ -1,10 +1,10 @@
-import BaseCommand from '../base-command.js'
+import BaseCommand from '../../base-command.js'
 import { getAccount, getExtension, getJigsawToken, getPackageJSON, installExtension, spawnAsync } from './utils.js'
 import { initDrizzle } from './drizzle.js'
 import { NEON_DATABASE_EXTENSION_SLUG, NETLIFY_NEON_PACKAGE_NAME } from './constants.js'
 import prettyjson from 'prettyjson'
-import { log } from '../../utils/command-helpers.js'
-import { SiteInfo } from './database.js'
+import { log } from '../../../utils/command-helpers.js'
+import { SiteInfo } from './types.js'
 
 export type DatabaseInitOptions = {
   assumeNo: boolean
diff --git a/src/commands/database/status.ts b/src/commands/database/legacy/db-status.ts
similarity index 95%
rename from src/commands/database/status.ts
rename to src/commands/database/legacy/db-status.ts
index 723cff0b66e..a2d2118f288 100644
--- a/src/commands/database/status.ts
+++ b/src/commands/database/legacy/db-status.ts
@@ -1,10 +1,10 @@
 import { OptionValues } from 'commander'
-import { SiteInfo } from './database.js'
-import BaseCommand from '../base-command.js'
+import { SiteInfo } from './types.js'
+import BaseCommand from '../../base-command.js'
 import { getAccount, getExtension, getSiteConfiguration } from './utils.js'
 import { NEON_DATABASE_EXTENSION_SLUG } from './constants.js'
 import prettyjson from 'prettyjson'
-import { chalk, log } from '../../utils/command-helpers.js'
+import { chalk, log } from '../../../utils/command-helpers.js'
 
 export const status = async (_options: OptionValues, command: BaseCommand) => {
   const siteInfo = command.netlify.siteInfo as SiteInfo
diff --git a/src/commands/database/drizzle.ts b/src/commands/database/legacy/drizzle.ts
similarity index 98%
rename from src/commands/database/drizzle.ts
rename to src/commands/database/legacy/drizzle.ts
index 01d07f75348..74a7e6f2b4c 100644
--- a/src/commands/database/drizzle.ts
+++ b/src/commands/database/legacy/drizzle.ts
@@ -1,5 +1,5 @@
 import { carefullyWriteFile, getPackageJSON, spawnAsync } from './utils.js'
-import BaseCommand from '../base-command.js'
+import BaseCommand from '../../base-command.js'
 import path from 'path'
 import fs from 'fs/promises'
 import inquirer from 'inquirer'
diff --git a/src/commands/database/legacy/types.ts b/src/commands/database/legacy/types.ts
new file mode 100644
index 00000000000..0ef5a08cc33
--- /dev/null
+++ b/src/commands/database/legacy/types.ts
@@ -0,0 +1,16 @@
+export type Extension = {
+  id: string
+  name: string
+  slug: string
+  hostSiteUrl: string
+  installedOnTeam: boolean
+}
+
+export type SiteInfo = {
+  id: string
+  name: string
+  account_id: string
+  admin_url: string
+  url: string
+  ssl_url: string
+}
diff --git a/src/commands/database/utils.ts b/src/commands/database/legacy/utils.ts
similarity index 98%
rename from src/commands/database/utils.ts
rename to src/commands/database/legacy/utils.ts
index 4260bf14016..56a7461060e 100644
--- a/src/commands/database/utils.ts
+++ b/src/commands/database/legacy/utils.ts
@@ -6,8 +6,8 @@ import fs from 'fs'
 import inquirer from 'inquirer'
 
 import { JIGSAW_URL } from './constants.js'
-import BaseCommand from '../base-command.js'
-import { Extension } from './database.js'
+import BaseCommand from '../../base-command.js'
+import { Extension } from './types.js'
 import { spawn } from 'child_process'
 
 type PackageJSON = {
diff --git a/src/commands/database/applied-migrations.ts b/src/commands/database/util/applied-migrations.ts
similarity index 100%
rename from src/commands/database/applied-migrations.ts
rename to src/commands/database/util/applied-migrations.ts
diff --git a/src/commands/database/util/constants.ts b/src/commands/database/util/constants.ts
new file mode 100644
index 00000000000..9c69ee94dc9
--- /dev/null
+++ b/src/commands/database/util/constants.ts
@@ -0,0 +1,2 @@
+export const MIGRATIONS_SCHEMA = 'netlify'
+export const MIGRATIONS_TABLE = `${MIGRATIONS_SCHEMA}.migrations`
diff --git a/src/commands/database/db-connection.ts b/src/commands/database/util/db-connection.ts
similarity index 100%
rename from src/commands/database/db-connection.ts
rename to src/commands/database/util/db-connection.ts
diff --git a/src/commands/database/meta-commands.ts b/src/commands/database/util/meta-commands.ts
similarity index 100%
rename from src/commands/database/meta-commands.ts
rename to src/commands/database/util/meta-commands.ts
diff --git a/src/commands/database/util/migrations-path.ts b/src/commands/database/util/migrations-path.ts
new file mode 100644
index 00000000000..860d6f1cda9
--- /dev/null
+++ b/src/commands/database/util/migrations-path.ts
@@ -0,0 +1,24 @@
+import { join } from 'path'
+
+import BaseCommand from '../../base-command.js'
+
+// Default on-disk location for migration files, relative to the project root.
+// Can be overridden by setting `db.migrations.path` in `netlify.toml`.
+export const DEFAULT_MIGRATIONS_PATH = 'netlify/database/migrations'
+
+// Resolves the absolute path of the project's migrations directory. Prefers
+// the `db.migrations.path` override from `netlify.toml` when present; falls
+// back to `<project-root>/netlify/database/migrations`.
+export const resolveMigrationsDirectory = (command: BaseCommand): string => {
+  const configuredPath = command.netlify.config.db?.migrations?.path
+  if (configuredPath) {
+    return configuredPath
+  }
+
+  const projectRoot = command.netlify.site.root ?? command.project.root ?? command.project.baseDirectory
+  if (!projectRoot) {
+    throw new Error('Could not determine the project root directory.')
+  }
+
+  return join(projectRoot, DEFAULT_MIGRATIONS_PATH)
+}
diff --git a/src/commands/database/pg-client-executor.ts b/src/commands/database/util/pg-client-executor.ts
similarity index 100%
rename from src/commands/database/pg-client-executor.ts
rename to src/commands/database/util/pg-client-executor.ts
diff --git a/src/commands/database/psql-formatter.ts b/src/commands/database/util/psql-formatter.ts
similarity index 100%
rename from src/commands/database/psql-formatter.ts
rename to src/commands/database/util/psql-formatter.ts
diff --git a/tests/unit/commands/database/migrate.test.ts b/tests/unit/commands/database/db-migrate.test.ts
similarity index 95%
rename from tests/unit/commands/database/migrate.test.ts
rename to tests/unit/commands/database/db-migrate.test.ts
index 7d5efd246ba..488df92be1e 100644
--- a/tests/unit/commands/database/migrate.test.ts
+++ b/tests/unit/commands/database/db-migrate.test.ts
@@ -14,7 +14,7 @@ vi.mock('@netlify/dev', () => ({
   applyMigrations: (...args: unknown[]) => mockApplyMigrations(...args),
 }))
 
-vi.mock('../../../../src/commands/database/db-connection.js', () => ({
+vi.mock('../../../../src/commands/database/util/db-connection.js', () => ({
   connectToDatabase: vi.fn().mockImplementation(() =>
     Promise.resolve({
       executor: mockExecutor,
@@ -33,13 +33,13 @@ vi.mock('../../../../src/utils/command-helpers.js', async () => ({
   },
 }))
 
-import { migrate } from '../../../../src/commands/database/migrate.js'
+import { migrate } from '../../../../src/commands/database/db-migrate.js'
 
 function createMockCommand(overrides: { buildDir?: string; projectRoot?: string; migrationsPath?: string } = {}) {
   const {
     buildDir = '/project',
     projectRoot = '/project',
-    migrationsPath = '/project/netlify/db/migrations',
+    migrationsPath = '/project/netlify/database/migrations',
   } = overrides
 
   return {
diff --git a/tests/unit/commands/database/migration-new.test.ts b/tests/unit/commands/database/db-migration-new.test.ts
similarity index 94%
rename from tests/unit/commands/database/migration-new.test.ts
rename to tests/unit/commands/database/db-migration-new.test.ts
index f618b82520b..64d102e0148 100644
--- a/tests/unit/commands/database/migration-new.test.ts
+++ b/tests/unit/commands/database/db-migration-new.test.ts
@@ -44,11 +44,11 @@ import {
   generateSlug,
   detectNumberingScheme,
   generateNextPrefix,
-  resolveMigrationsDirectory,
-} from '../../../../src/commands/database/migration-new.js'
+} from '../../../../src/commands/database/db-migration-new.js'
+import { resolveMigrationsDirectory } from '../../../../src/commands/database/util/migrations-path.js'
 
 function createMockCommand(overrides: { migrationsPath?: string | undefined } = {}) {
-  const { migrationsPath = '/project/netlify/db/migrations' } = overrides
+  const { migrationsPath = '/project/netlify/database/migrations' } = overrides
 
   return {
     project: { root: '/project', baseDirectory: undefined },
@@ -128,7 +128,7 @@ describe('resolveMigrationsDirectory', () => {
       netlify: { site: { root: '/project' }, config: {} },
     } as unknown as Parameters<typeof resolveMigrationsDirectory>[0]
 
-    expect(resolveMigrationsDirectory(command)).toBe(join('/project', 'netlify', 'db', 'migrations'))
+    expect(resolveMigrationsDirectory(command)).toBe(join('/project', 'netlify', 'database', 'migrations'))
   })
 
   test('throws when no config path and no project root', () => {
@@ -157,7 +157,7 @@ describe('migrationNew', () => {
 
     await migrationNew({ description: 'add users', scheme: 'sequential' }, command)
 
-    expect(mockMkdir).toHaveBeenCalledWith(join('/project', 'netlify', 'db', 'migrations', '0001_add-users'), {
+    expect(mockMkdir).toHaveBeenCalledWith(join('/project', 'netlify', 'database', 'migrations', '0001_add-users'), {
       recursive: true,
     })
   })
@@ -167,7 +167,7 @@ describe('migrationNew', () => {
 
     await migrationNew({ description: 'add posts table', scheme: 'sequential' }, createMockCommand())
 
-    const expectedFolder = join('/project/netlify/db/migrations', '0002_add-posts-table')
+    const expectedFolder = join('/project/netlify/database/migrations', '0002_add-posts-table')
     expect(mockMkdir).toHaveBeenCalledWith(expectedFolder, { recursive: true })
     expect(mockWriteFile).toHaveBeenCalledWith(
       join(expectedFolder, 'migration.sql'),
@@ -189,7 +189,7 @@ describe('migrationNew', () => {
 
     expect(jsonMessages).toHaveLength(1)
     expect(jsonMessages[0]).toEqual({
-      path: join('/project/netlify/db/migrations', '0001_add-posts-table'),
+      path: join('/project/netlify/database/migrations', '0001_add-posts-table'),
       name: '0001_add-posts-table',
     })
   })
@@ -249,7 +249,7 @@ describe('migrationNew', () => {
 
     await migrationNew({ description: 'initial migration', scheme: 'sequential' }, createMockCommand())
 
-    expect(mockMkdir).toHaveBeenCalledWith(join('/project/netlify/db/migrations', '0001_initial-migration'), {
+    expect(mockMkdir).toHaveBeenCalledWith(join('/project/netlify/database/migrations', '0001_initial-migration'), {
       recursive: true,
     })
   })
diff --git a/tests/unit/commands/database/migration-pull.test.ts b/tests/unit/commands/database/db-migration-pull.test.ts
similarity index 98%
rename from tests/unit/commands/database/migration-pull.test.ts
rename to tests/unit/commands/database/db-migration-pull.test.ts
index f04f6c5f1af..5170272b9ce 100644
--- a/tests/unit/commands/database/migration-pull.test.ts
+++ b/tests/unit/commands/database/db-migration-pull.test.ts
@@ -48,7 +48,7 @@ vi.stubGlobal('fetch', mockFetch)
 import { resolve } from 'path'
 
 import inquirer from 'inquirer'
-import { migrationPull } from '../../../../src/commands/database/migration-pull.js'
+import { migrationPull } from '../../../../src/commands/database/db-migration-pull.js'
 
 const sampleMigrations = [
   {
@@ -70,7 +70,7 @@ function createMockCommand(
 ) {
   const siteId = overrides.siteId === null ? undefined : overrides.siteId ?? 'site-123'
   const accessToken = overrides.accessToken === null ? undefined : overrides.accessToken ?? 'Bearer test-token'
-  const migrationsPath = overrides.migrationsPath ?? '/project/netlify/db/migrations'
+  const migrationsPath = overrides.migrationsPath ?? '/project/netlify/database/migrations'
 
   return {
     siteId,
@@ -164,7 +164,7 @@ describe('migrationPull', () => {
     mockFetchResponse(sampleMigrations)
     vi.mocked(inquirer.prompt).mockResolvedValueOnce({ confirmed: true })
 
-    const migrationsPath = '/project/netlify/db/migrations'
+    const migrationsPath = '/project/netlify/database/migrations'
     const resolved = resolve(migrationsPath)
     await migrationPull({}, createMockCommand({ migrationsPath }))
 
diff --git a/tests/unit/commands/database/reset.test.ts b/tests/unit/commands/database/db-reset.test.ts
similarity index 95%
rename from tests/unit/commands/database/reset.test.ts
rename to tests/unit/commands/database/db-reset.test.ts
index 6102b59983b..6e7a31e7913 100644
--- a/tests/unit/commands/database/reset.test.ts
+++ b/tests/unit/commands/database/db-reset.test.ts
@@ -14,7 +14,7 @@ vi.mock('@netlify/dev', () => ({
   resetDatabase: (...args: unknown[]) => mockResetDatabase(...args),
 }))
 
-vi.mock('../../../../src/commands/database/db-connection.js', () => ({
+vi.mock('../../../../src/commands/database/util/db-connection.js', () => ({
   connectToDatabase: vi.fn().mockImplementation(() =>
     Promise.resolve({
       executor: mockExecutor,
@@ -33,7 +33,7 @@ vi.mock('../../../../src/utils/command-helpers.js', async () => ({
   },
 }))
 
-import { reset } from '../../../../src/commands/database/reset.js'
+import { reset } from '../../../../src/commands/database/db-reset.js'
 
 function createMockCommand(overrides: { buildDir?: string; projectRoot?: string } = {}) {
   const { buildDir = '/project', projectRoot = '/project' } = overrides
diff --git a/tests/unit/commands/database/status-db.test.ts b/tests/unit/commands/database/db-status.test.ts
similarity index 99%
rename from tests/unit/commands/database/status-db.test.ts
rename to tests/unit/commands/database/db-status.test.ts
index 0b435e3c960..86469fdbcdf 100644
--- a/tests/unit/commands/database/status-db.test.ts
+++ b/tests/unit/commands/database/db-status.test.ts
@@ -64,7 +64,7 @@ vi.mock('../../../../src/utils/command-helpers.js', async () => ({
   },
 }))
 
-vi.mock('../../../../src/commands/database/db-connection.js', () => ({
+vi.mock('../../../../src/commands/database/util/db-connection.js', () => ({
   // eslint-disable-next-line @typescript-eslint/no-unsafe-return
   connectToDatabase: (...args: unknown[]) => mockConnectToDatabase(...args),
   // eslint-disable-next-line @typescript-eslint/no-unsafe-return
@@ -73,7 +73,7 @@ vi.mock('../../../../src/commands/database/db-connection.js', () => ({
 
 vi.stubGlobal('fetch', mockFetch)
 
-import { statusDb } from '../../../../src/commands/database/status-db.js'
+import { statusDb } from '../../../../src/commands/database/db-status.js'
 
 const SITE_NAME = 'my-site'
 const LOCAL_CONN_WITH_CREDS = 'postgres://user:password@localhost:5432/netlify'
@@ -92,7 +92,7 @@ function createMockCommand(
 ) {
   const siteRoot = overrides.siteRoot === null ? undefined : overrides.siteRoot ?? '/project'
   const migrationsPath =
-    overrides.migrationsPath === null ? undefined : overrides.migrationsPath ?? '/project/netlify/db/migrations'
+    overrides.migrationsPath === null ? undefined : overrides.migrationsPath ?? '/project/netlify/database/migrations'
   const siteId = overrides.siteId === null ? undefined : overrides.siteId ?? 'site-123'
 
   return {