feat: add db connect command (#8134)

Closes https://linear.app/netlify/issue/RUN-2706/cli-connect-command.

Author: eduardoboucas

src/commands/database/connect.ts

@@ -0,0 +1,133 @@
+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'
+
+export interface ConnectOptions {
+  query?: string
+  json?: boolean
+}
+
+export const connect = async (options: ConnectOptions, command: BaseCommand): Promise<void> => {
+  const buildDir = command.netlify.site.root ?? command.project.root ?? command.project.baseDirectory
+  if (!buildDir) {
+    throw new Error('Could not determine the project root directory.')
+  }
+
+  const { client, connectionString, cleanup } = await connectRawClient(buildDir)
+
+  // --json without --query: print connection details
+  if (options.json && !options.query) {
+    logJson({ connection_string: connectionString, context: 'dev' })
+    await cleanup()
+    return
+  }
+
+  log(`Connected to ${connectionString}`)
+
+  // --query: one-shot mode
+  if (options.query) {
+    try {
+      const result = await client.query<Record<string, unknown>>(options.query)
+      if (options.json) {
+        logJson(result.rows)
+      } else {
+        log(formatQueryResult(result.fields, result.rows, result.rowCount, result.command))
+      }
+    } finally {
+      await cleanup()
+    }
+    return
+  }
+
+  // Interactive REPL
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: 'netlifydb=> ',
+  })
+
+  let buffer = ''
+
+  const handleCleanup = async () => {
+    rl.close()
+    await cleanup()
+  }
+
+  process.on('SIGINT', () => {
+    if (buffer) {
+      // Cancel current multi-line input
+      buffer = ''
+      process.stdout.write('\n')
+      rl.setPrompt('netlifydb=> ')
+      rl.prompt()
+    } else {
+      log('')
+      void handleCleanup()
+    }
+  })
+
+  rl.on('close', () => {
+    void handleCleanup()
+  })
+
+  rl.on('line', (line: string) => {
+    // Meta-commands are only recognized at the start of input (not mid-statement)
+    if (buffer === '' && line.trimStart().startsWith('\\')) {
+      rl.pause()
+      void (async () => {
+        try {
+          const result = await executeMetaCommand(line, client)
+          switch (result.type) {
+            case 'quit':
+              await handleCleanup()
+              return
+            case 'help':
+              log(result.text)
+              break
+            case 'unknown':
+              log(`Invalid command ${result.command}. Try \\? for help.`)
+              break
+            case 'query':
+              log(formatQueryResult(result.fields, result.rows, result.rowCount, result.command))
+              break
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err)
+          log(`ERROR:  ${message}`)
+        }
+        rl.resume()
+        rl.prompt()
+      })()
+      return
+    }
+
+    buffer += (buffer ? '\n' : '') + line
+
+    if (buffer.trimEnd().endsWith(';')) {
+      const sql = buffer
+      buffer = ''
+      rl.setPrompt('netlifydb=> ')
+      rl.pause()
+      void (async () => {
+        try {
+          const result = await client.query<Record<string, unknown>>(sql)
+          log(formatQueryResult(result.fields, result.rows, result.rowCount, result.command))
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err)
+          log(`ERROR:  ${message}`)
+        }
+        rl.resume()
+        rl.prompt()
+      })()
+    } else {
+      rl.setPrompt('netlifydb-> ')
+      rl.prompt()
+    }
+  })
+
+  rl.prompt()
+}

src/commands/database/database.ts

@@ -90,6 +90,25 @@ export const createDatabaseCommand = (program: BaseCommand) => {
     })
 
   if (process.env.EXPERIMENTAL_NETLIFY_DB_ENABLED === '1') {
+    dbCommand
+      .command('connect')
+      .description('Connect to the database')
+      .option('-q, --query <sql>', 'Execute a single query and exit')
+      .option(
+        '--json',
+        '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')
+        await connect(options, command)
+      })
+      .addExamples([
+        'netlify db connect',
+        'netlify db connect --query "SELECT * FROM users"',
+        'netlify db connect --json --query "SELECT * FROM users"',
+        'netlify db connect --json',
+      ])
+
     dbCommand
       .command('migrate')
       .description('Apply database migrations to the local development database')

src/commands/database/db-connection.ts

@@ -11,14 +11,29 @@ interface DBConnection {
 }
 
 export async function connectToDatabase(buildDir: string): Promise<DBConnection> {
+  const { client, cleanup } = await connectRawClient(buildDir)
+  return {
+    executor: new PgClientExecutor(client),
+    cleanup,
+  }
+}
+
+interface RawDBConnection {
+  client: Client
+  connectionString: string
+  cleanup: () => Promise<void>
+}
+
+export async function connectRawClient(buildDir: string): Promise<RawDBConnection> {
   const state = new LocalState(buildDir)
-  const connectionString = state.get('dbConnectionString')
+  const storedConnectionString = state.get('dbConnectionString')
 
-  if (connectionString) {
-    const client = new Client({ connectionString })
+  if (storedConnectionString) {
+    const client = new Client({ connectionString: storedConnectionString })
     await client.connect()
     return {
-      executor: new PgClientExecutor(client),
+      client,
+      connectionString: storedConnectionString,
       cleanup: () => client.end(),
     }
   }
@@ -40,14 +55,21 @@ export async function connectToDatabase(buildDir: string): Promise<DBConnection>
 
   await netlifyDev.start()
 
-  const { db } = netlifyDev
-  if (!db) {
+  const connectionString = state.get('dbConnectionString')
+  if (!connectionString) {
     await netlifyDev.stop()
     throw new Error('Local database failed to start. Set EXPERIMENTAL_NETLIFY_DB_ENABLED=1 to enable.')
   }
 
+  const client = new Client({ connectionString })
+  await client.connect()
+
   return {
-    executor: db,
-    cleanup: () => netlifyDev.stop(),
+    client,
+    connectionString,
+    cleanup: async () => {
+      await client.end()
+      await netlifyDev.stop()
+    },
   }
 }

src/commands/database/meta-commands.ts

@@ -0,0 +1,72 @@
+import type { Client, FieldDef } from 'pg'
+
+export type MetaCommandResult =
+  | { type: 'query'; fields: FieldDef[]; rows: Record<string, unknown>[]; rowCount: number | null; command: string }
+  | { type: 'quit' }
+  | { type: 'help'; text: string }
+  | { type: 'unknown'; command: string }
+
+const HELP_TEXT = `Netlify DB interactive client. Supports a subset of psql commands.
+
+General
+  \\q          quit
+
+Informational
+  \\d          list tables
+  \\dt         list tables
+  \\d NAME     describe table
+  \\l          list databases
+  \\?          show this help`
+
+export const executeMetaCommand = async (input: string, client: Client): Promise<MetaCommandResult> => {
+  const trimmed = input.trim()
+  const [cmd, ...args] = trimmed.split(/\s+/)
+
+  if (cmd === '\\q') {
+    return { type: 'quit' }
+  }
+
+  if (cmd === '\\?') {
+    return { type: 'help', text: HELP_TEXT }
+  }
+
+  if (cmd === '\\dt' || (cmd === '\\d' && args.length === 0)) {
+    const result = await client.query<Record<string, unknown>>(
+      `SELECT schemaname AS "Schema", tablename AS "Name", tableowner AS "Owner"
+       FROM pg_tables
+       WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+       ORDER BY schemaname, tablename`,
+    )
+    return { type: 'query', fields: result.fields, rows: result.rows, rowCount: result.rowCount, command: 'SELECT' }
+  }
+
+  if (cmd === '\\d' && args.length > 0) {
+    const tableName = args[0]
+    const result = await client.query<Record<string, unknown>>(
+      `SELECT column_name AS "Column", data_type AS "Type",
+              CASE WHEN is_nullable = 'YES' THEN 'yes' ELSE 'no' END AS "Nullable",
+              column_default AS "Default"
+       FROM information_schema.columns
+       WHERE table_schema = 'public' AND table_name = $1
+       ORDER BY ordinal_position`,
+      [tableName],
+    )
+    if (result.rowCount === 0) {
+      return { type: 'query', fields: result.fields, rows: result.rows, rowCount: 0, command: 'SELECT' }
+    }
+    return { type: 'query', fields: result.fields, rows: result.rows, rowCount: result.rowCount, command: 'SELECT' }
+  }
+
+  if (cmd === '\\l') {
+    const result = await client.query<Record<string, unknown>>(
+      `SELECT datname AS "Name",
+              pg_catalog.pg_get_userbyid(datdba) AS "Owner",
+              pg_catalog.pg_encoding_to_char(encoding) AS "Encoding"
+       FROM pg_catalog.pg_database
+       ORDER BY 1`,
+    )
+    return { type: 'query', fields: result.fields, rows: result.rows, rowCount: result.rowCount, command: 'SELECT' }
+  }
+
+  return { type: 'unknown', command: cmd }
+}

src/commands/database/psql-formatter.ts

@@ -0,0 +1,63 @@
+import type { FieldDef } from 'pg'
+
+const formatValue = (value: unknown): string => {
+  if (value === null || value === undefined) {
+    return ''
+  }
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+  if (typeof value === 'object') {
+    return JSON.stringify(value)
+  }
+  if (typeof value === 'string') {
+    return value
+  }
+  return String(value as number | boolean | bigint)
+}
+
+export const formatQueryResult = (
+  fields: FieldDef[],
+  rows: Record<string, unknown>[],
+  rowCount: number | null,
+  command: string,
+): string => {
+  if (fields.length === 0) {
+    // DDL or DML without returning clause
+    if (command === 'INSERT') {
+      return `INSERT 0 ${String(rowCount ?? 0)}`
+    }
+    if (command === 'UPDATE' || command === 'DELETE') {
+      return `${command} ${String(rowCount ?? 0)}`
+    }
+    return command
+  }
+
+  const headers = fields.map((f) => f.name)
+
+  const stringRows = rows.map((row) => headers.map((h) => formatValue(row[h])))
+
+  const widths = headers.map((header, i) => {
+    const maxDataWidth = stringRows.reduce((max, row) => Math.max(max, row[i].length), 0)
+    return Math.max(header.length, maxDataWidth)
+  })
+
+  const lines: string[] = []
+
+  // Header
+  lines.push(headers.map((h, i) => ` ${h.padEnd(widths[i])} `).join('|'))
+
+  // Separator
+  lines.push(widths.map((w) => '-'.repeat(w + 2)).join('+'))
+
+  // Rows
+  for (const row of stringRows) {
+    lines.push(row.map((val, i) => ` ${val.padEnd(widths[i])} `).join('|'))
+  }
+
+  // Footer
+  const count = rowCount ?? rows.length
+  lines.push(`(${String(count)} ${count === 1 ? 'row' : 'rows'})`)
+
+  return lines.join('\n')
+}