velocious 1.0.579 → 1.0.581

package/README.md

@@ -8,6 +8,7 @@
 * Built-in record auditing for model lifecycle changes (see [docs/auditing.md](docs/auditing.md))
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
 * Migrations for schema changes and UTC datetime storage (see [docs/database-migrations.md](docs/database-migrations.md))
+* Tenant-selected base-model and structure generation with one immutable, fail-closed physical database context; tenant-only model metadata initializes only after that context is active (see [docs/tenant-selected-database-generation.md](docs/tenant-selected-database-generation.md))
 * External packages (engines) that contribute data models, frontend-model resources and migrations to a consuming app (see [docs/packages.md](docs/packages.md))
 * Optional Rampway-owned durable deployment control plane mounted through the standard routes DSL on Velocious 1.0.577 or newer (see [docs/rampway-integration.md](docs/rampway-integration.md))
 * Controllers and views for HTTP endpoints
@@ -1178,6 +1179,30 @@ const results = await Task.insertMultiple(
 console.log(results.succeededRows, results.failedRows, results.errors)
 ```
 
+Large batches are split into multiple `INSERT ... VALUES` statements so each
+statement stays within database limits. Two database-configuration keys control
+the splitting:
+
+- `maxRowsPerInsert` — maximum rows per statement (default: `500`).
+- `maxInsertSqlBytes` — maximum serialized SQL size in bytes per statement
+  (default: `1048576`, i.e. 1 MiB).
+
+A new chunk is started when the next row would exceed either limit. Row order is
+preserved across chunks.
+
+**Important:** when `insertMultiple` is called outside a transaction, each chunk
+commits independently. If a later chunk fails, earlier chunks remain persisted.
+Wrap the call in a transaction when you need all-or-nothing semantics:
+
+```js
+await Task.transaction(async () => {
+  await Task.insertMultiple(
+    ["project_id", "name", "created_at", "updated_at"],
+    thousandsOfTasks
+  )
+})
+```
+
 ### Find or create records
 
 ```js

package/build/cli/command-arguments.js

@@ -0,0 +1,45 @@
+// @ts-check
+
+/**
+ * @typedef {object} CommandArgumentDefinition
+ * @property {string[]} [booleanOptions] - Flags that do not accept a value.
+ * @property {string[]} [valueOptions] - Flags that require one value.
+ */
+
+/**
+ * Parses and validates one command's arguments.
+ * @param {object} args - Parser arguments.
+ * @param {CommandArgumentDefinition} args.definition - Accepted command options.
+ * @param {string[]} args.processArgs - Raw command arguments including the command name.
+ * @returns {Record<string, string | boolean>} - Values keyed by long option name without `--`.
+ */
+export default function commandArguments({definition, processArgs}) {
+  const commandName = processArgs[0] || "command"
+  const booleanOptions = new Set(definition.booleanOptions || [])
+  const valueOptions = new Set(definition.valueOptions || [])
+  /** @type {Record<string, string | boolean>} */
+  const parsed = {}
+
+  for (let index = 1; index < processArgs.length; index++) {
+    const argument = processArgs[index]
+
+    if (booleanOptions.has(argument)) {
+      parsed[argument.slice(2)] = true
+      continue
+    }
+
+    if (valueOptions.has(argument)) {
+      const value = processArgs[index + 1]
+
+      if (!value || value.startsWith("-")) throw new Error(`Missing value for ${argument}`)
+
+      parsed[argument.slice(2)] = value
+      index++
+      continue
+    }
+
+    throw new Error(`Unknown argument for ${commandName}: ${argument}`)
+  }
+
+  return parsed
+}

package/build/cli/index.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+const COMMAND_VALUE_OPTIONS = new Set(["--tenant"])
+
 export default class VelociousCli {
   /**
    * Runs constructor.
@@ -94,6 +96,7 @@ export default class VelociousCli {
      * Current group.
      * @type {string[]} */
     let currentGroup = []
+    let expectsOptionValue = false
 
     for (const processArg of processArgs) {
       if (currentGroup.length == 0) {
@@ -103,11 +106,18 @@ export default class VelociousCli {
         continue
       }
 
+      if (expectsOptionValue) {
+        currentGroup.push(processArg)
+        expectsOptionValue = false
+        continue
+      }
+
       if (!processArg.startsWith("-") && commandNames.has(processArg)) {
         groups.push(currentGroup)
         currentGroup = [processArg]
       } else {
         currentGroup.push(processArg)
+        expectsOptionValue = COMMAND_VALUE_OPTIONS.has(processArg)
       }
     }
 

package/build/configuration-types.js

@@ -73,6 +73,8 @@
  * @property {string} [host] - Database host.
  * @property {boolean} [migrations] - Whether migrations are enabled for this database.
  * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so a whole structure SQL dump loads in one round-trip via `StructureSqlLoader`. Off by default; ordinary queries otherwise reject stacked statements.
+ * @property {number} [maxRowsPerInsert] - Maximum rows per `INSERT ... VALUES (...), (...), ...` statement generated by `Record.insertMultiple`. Defaults to 500.
+ * @property {number} [maxInsertSqlBytes] - Maximum serialized SQL size, in bytes, for a single `INSERT ... VALUES (...), (...), ...` statement. Defaults to 1 MiB (1048576).
  * @property {string} [password] - Password for the database user.
  * @property {number} [port] - Database port.
  * @property {string} [primaryKeyType] - Default type for implicit migration primary keys and references. Defaults to `uuid`.
@@ -659,6 +661,7 @@
 /**
  * @typedef {object} TenantDatabaseProviderType
  * @property {(args: {configuration: import("./configuration.js").default, identifier: string}) => Array<ReturnType<typeof JSON.parse>> | Promise<Array<ReturnType<typeof JSON.parse>>>} listTenants - Lists tenants that should be created, checked, or migrated for this database identifier.
+ * @property {(args: {configuration: import("./configuration.js").default, identifier: string}) => ReturnType<typeof JSON.parse> | void | Promise<ReturnType<typeof JSON.parse> | void>} [resolveGenerationTenant] - Resolves one explicit tenant descriptor for schema/base-model generation without enumerating lifecycle tenants.
  * @property {(args: {configuration: import("./configuration.js").default, identifier: string}) => Array<ReturnType<typeof JSON.parse>> | Promise<Array<ReturnType<typeof JSON.parse>>>} [listRestrictTenants] - Lists existing tenants that should be checked for dependent restrict destroys. Defaults to listTenants.
  * @property {(args: {configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ReturnType<typeof JSON.parse>}) => void | Promise<void>} [createDatabase] - Creates the tenant database/schema for one tenant.
  * @property {(args: {configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ReturnType<typeof JSON.parse>}) => void | Promise<void>} [dropDatabase] - Drops the tenant database/schema for one tenant.

package/build/database/drivers/base.js

@@ -766,8 +766,94 @@ export default class VelociousDatabaseDriversBase {
     await this.query(sql)
   }
 
+  /**
+   * Maximum rows per `INSERT ... VALUES (...), (...), ...` statement. Drivers
+   * that build multi-value inserts must stay below database-specific limits
+   * (SQLite's `MAX_VARIABLE_NUMBER`, SQL Server's 2100 parameters, PostgreSQL's
+   * 65535 parameters, and so on). 500 rows is safely under every major engine
+   * for tables with a moderate number of columns and keeps generated SQL small.
+   *
+   * Override via `maxRowsPerInsert` in the database configuration.
+   * @returns {number} - Maximum rows per insert statement.
+   */
+  maxRowsPerInsert() {
+    return optionalPositiveInteger(this.getArgs().maxRowsPerInsert, "maxRowsPerInsert") ?? 500
+  }
+
+  /**
+   * Maximum serialized SQL size, in bytes, for a single `INSERT ... VALUES`
+   * statement. Large text/JSON payloads can push a modest row count well beyond
+   * database wire/protocol limits, so chunking also stops when the next row
+   * would push the generated string over this threshold.
+   *
+   * Override via `maxInsertSqlBytes` in the database configuration.
+   * @returns {number} - Maximum bytes per insert statement.
+   */
+  maxInsertSqlBytes() {
+    return optionalPositiveInteger(this.getArgs().maxInsertSqlBytes, "maxInsertSqlBytes") ?? 1048576
+  }
+
+  /**
+   * Splits `rows` into chunks that stay within both {@link maxRowsPerInsert}
+   * and {@link maxInsertSqlBytes} while preserving order.
+   *
+   * A chunk always contains at least one row, even if that single row exceeds
+   * the byte limit, so progress is guaranteed.
+   * @param {Array<Array<ReturnType<typeof JSON.parse>>>} rows - Rows to insert.
+   * @param {(rows: Array<Array<ReturnType<typeof JSON.parse>>>) => string} buildSql - Function that builds the full SQL for a candidate chunk; called with `[]` to measure the statement prefix and with `[row]` to measure each row's values tuple.
+   * @returns {Array<Array<Array<ReturnType<typeof JSON.parse>>>>} - Row chunks.
+   */
+  _insertMultipleChunks(rows, buildSql) {
+    const chunks = []
+    const maxRows = this.maxRowsPerInsert()
+    const maxBytes = this.maxInsertSqlBytes()
+    const emptySql = buildSql([])
+    const prefix = `${emptySql} VALUES `
+    const baseByteLength = Buffer.byteLength(prefix, "utf8")
+
+    let currentChunk = []
+    let currentBytes = 0
+
+    for (const row of rows) {
+      const singleRowSql = buildSql([row])
+      const rowValuesSql = singleRowSql.slice(prefix.length)
+      const rowValuesSqlBytes = Buffer.byteLength(rowValuesSql, "utf8")
+
+      if (currentChunk.length > 0) {
+        const candidateRows = currentChunk.length + 1
+        const candidateBytes = currentBytes + 2 + rowValuesSqlBytes // ", " separator
+
+        if (candidateRows > maxRows || candidateBytes > maxBytes) {
+          chunks.push(currentChunk)
+          currentChunk = []
+          currentBytes = 0
+        }
+      }
+
+      if (currentChunk.length === 0) {
+        currentBytes = baseByteLength + rowValuesSqlBytes
+      } else {
+        currentBytes += 2 + rowValuesSqlBytes
+      }
+
+      currentChunk.push(row)
+    }
+
+    if (currentChunk.length > 0) {
+      chunks.push(currentChunk)
+    }
+
+    return chunks
+  }
+
   /**
    * Runs insert multiple.
+   *
+   * Large row sets are split into multiple statements that each stay within
+   * {@link maxRowsPerInsert} rows and {@link maxInsertSqlBytes} serialized
+   * bytes so the generated SQL stays within database parameter and wire limits.
+   * When called outside a transaction each chunk commits independently; callers
+   * that need all-or-nothing semantics should wrap the call in {@link transaction}.
    * @param {string} tableName - Table name.
    * @param {Array<string>} columns - Column names.
    * @param {Array<Array<ReturnType<typeof JSON.parse>>>} rows - Rows to insert.
@@ -776,9 +862,13 @@ export default class VelociousDatabaseDriversBase {
   async insertMultiple(tableName, columns, rows) {
     this._assertNotReadOnly()
 
-    const sql = this.insertSql({columns, tableName, rows})
+    const chunks = this._insertMultipleChunks(rows, (chunkRows) => this.insertSql({columns, tableName, rows: chunkRows}))
 
-    await this.query(sql)
+    for (const chunk of chunks) {
+      const sql = this.insertSql({columns, tableName, rows: chunk})
+
+      await this.query(sql)
+    }
   }
 
   /**

package/build/database/drivers/sqlite/base.js

@@ -218,9 +218,14 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    */
   async insertMultipleWithSingleInsert(tableName, columns, rows) {
     this._assertNotReadOnly()
-    const sql = new Insert({columns, driver: this, rows, tableName}).toSql()
 
-    await this.query(sql)
+    const chunks = this._insertMultipleChunks(rows, (chunkRows) => new Insert({columns, driver: this, rows: chunkRows, tableName}).toSql())
+
+    for (const chunk of chunks) {
+      const sql = new Insert({columns, driver: this, rows: chunk, tableName}).toSql()
+
+      await this.query(sql)
+    }
   }
 
   /**

package/build/database/generation-context.js

@@ -0,0 +1,121 @@
+// @ts-check
+
+import Tenant from "../tenants/tenant.js"
+
+/**
+ * Immutable selection of one logical tenant database and one provider-resolved
+ * physical tenant. Schema tools can share this contract without ambient or
+ * process-global selection state.
+ */
+export default class DatabaseGenerationContext {
+  /**
+   * Resolves one tenant-only database from its provider and captures its physical identity.
+   * @param {object} args - Selection arguments.
+   * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+   * @param {string} args.databaseIdentifier - Logical tenant-only database identifier.
+   * @returns {Promise<DatabaseGenerationContext>} - Immutable selected database context.
+   */
+  static async resolve({configuration, databaseIdentifier}) {
+    const databaseConfiguration = configuration.getDatabaseConfiguration()[databaseIdentifier]
+
+    if (!databaseConfiguration) {
+      throw new Error(`No such tenant database identifier configured: ${databaseIdentifier}`)
+    }
+    if (!databaseConfiguration.tenantOnly) {
+      throw new Error(`Database identifier ${databaseIdentifier} is not configured with tenantOnly: true`)
+    }
+    if (configuration.getDisabledDatabaseIdentifiers().has(databaseIdentifier)) {
+      throw new Error(`Tenant database identifier ${databaseIdentifier} is disabled by VELOCIOUS_DISABLED_DATABASE_IDENTIFIERS`)
+    }
+
+    const provider = configuration.getTenantDatabaseProvider(databaseIdentifier)
+
+    await configuration.initialize({type: "database-generation"})
+
+    const tenants = await configuration.ensureConnections({name: `Resolve database generation context: ${databaseIdentifier}`}, async () => {
+      if (provider.resolveGenerationTenant) {
+        const tenant = await provider.resolveGenerationTenant({configuration, identifier: databaseIdentifier})
+
+        return tenant === undefined ? [] : [tenant]
+      }
+
+      return await provider.listTenants({configuration, identifier: databaseIdentifier})
+    })
+
+    if (!Array.isArray(tenants)) {
+      throw new Error(`Tenant database provider for ${databaseIdentifier} must return an array from listTenants`)
+    }
+    if (tenants.length === 0) {
+      throw new Error(`Tenant database selection ${databaseIdentifier} resolved no tenants`)
+    }
+    if (tenants.length !== 1) {
+      throw new Error(`Tenant database selection ${databaseIdentifier} is ambiguous: provider returned ${tenants.length} tenants`)
+    }
+
+    const tenant = tenants[0]
+
+    if (!tenant || typeof tenant !== "object" || Array.isArray(tenant)) {
+      throw new Error(`Tenant database selection ${databaseIdentifier} returned an invalid tenant descriptor`)
+    }
+
+    const handle = Tenant.handle(tenant, configuration)
+
+    // Resolve now so an inactive/stale descriptor fails before a selected
+    // schema connection can be checked out or read.
+    handle.databaseConfiguration(databaseIdentifier)
+
+    return new DatabaseGenerationContext({configuration, databaseIdentifier, handle})
+  }
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Captured selection.
+   * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+   * @param {string} args.databaseIdentifier - Logical database identifier.
+   * @param {ReturnType<typeof Tenant.handle>} args.handle - Captured tenant handle.
+   */
+  constructor({configuration, databaseIdentifier, handle}) {
+    this._configuration = configuration
+    this._databaseIdentifier = databaseIdentifier
+    this._handle = handle
+
+    Object.freeze(this)
+  }
+
+  /**
+   * Returns the captured logical database identifier.
+   * @returns {string} - Captured logical database identifier.
+   */
+  databaseIdentifier() { return this._databaseIdentifier }
+
+  /**
+   * Returns the captured physical database configuration.
+   * @returns {import("../configuration-types.js").DatabaseConfigurationType} - Captured physical database configuration.
+   */
+  databaseConfiguration() { return this._handle.databaseConfiguration(this._databaseIdentifier) }
+
+  /**
+   * Returns the captured tenant descriptor.
+   * @returns {ReturnType<ReturnType<typeof Tenant.handle>["tenant"]>} - Captured immutable tenant descriptor.
+   */
+  tenant() { return this._handle.tenant() }
+
+  /**
+   * Runs work on one connection pinned to the captured physical database.
+   * @template T
+   * @param {object} args - Work arguments.
+   * @param {(connection: import("./drivers/base.js").default) => Promise<T>} args.callback - Selected database work.
+   * @param {string} args.name - Checkout name.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async run({callback, name}) {
+    return await this._configuration.runWithTenant(this.tenant(), async () => {
+      return await this._configuration.withDatabaseOperation({
+        databaseConfiguration: this.databaseConfiguration(),
+        databaseIdentifier: this.databaseIdentifier(),
+        name,
+        tenant: this.tenant()
+      }, async (operation) => await callback(operation.connection()))
+    })
+  }
+}

package/build/database/initializer-from-require-context.js

@@ -43,6 +43,13 @@ export default class VelociousDatabaseInitializerFromRequireContext {
 
       if (!modelClass) throw new Error(`Model wasn't exported from: ${fileName}`)
 
+      const configuredDatabase = configuration.getDatabaseConfiguration()[modelClass.getConfiguredDatabaseIdentifier()]
+
+      if (configuredDatabase?.tenantOnly && !configuration.isDatabaseIdentifierActive(modelClass.getConfiguredDatabaseIdentifier())) {
+        modelClass.registerRecordClass({configuration})
+        continue
+      }
+
       if (!modelClass.getEagerLoadRecordMetadata()) {
         modelClass.registerRecordClass({configuration})
         await this._bestEffortInitializeDeferredModel({configuration, modelClass})

package/build/environment-handlers/node/cli/commands/db/schema/dump.js

@@ -1,4 +1,6 @@
 import BaseCommand from "../../../../../../cli/base-command.js"
+import commandArguments from "../../../../../../cli/command-arguments.js"
+import DatabaseGenerationContext from "../../../../../../database/generation-context.js"
 import fileExists from "../../../../../../utils/file-exists.js"
 import path from "path"
 
@@ -8,6 +10,29 @@ export default class DbSchemaDump extends BaseCommand {
    * Runs execute.
    * @returns {Promise<void>} */
   async execute() {
+    const parsedArguments = commandArguments({
+      definition: {valueOptions: ["--tenant"]},
+      processArgs: this.processArgs || []
+    })
+    const tenantDatabaseIdentifier = parsedArguments.tenant
+
+    if (typeof tenantDatabaseIdentifier === "string") {
+      const context = await DatabaseGenerationContext.resolve({
+        configuration: this.getConfiguration(),
+        databaseIdentifier: tenantDatabaseIdentifier
+      })
+
+      await context.run({name: "DB selected tenant schema dump", callback: async (db) => {
+        const dbs = {[context.databaseIdentifier()]: db}
+        const shouldGenerate = await this.shouldGenerateStructureSql({dbs})
+
+        if (!shouldGenerate) return
+
+        await this.getEnvironmentHandler().afterMigrations({dbs, reason: "schemaDump"})
+      }})
+      return
+    }
+
     await this.getConfiguration().ensureConnections({name: "DB schema dump"}, async (dbs) => {
       const shouldGenerate = await this.shouldGenerateStructureSql({dbs})
 

package/build/environment-handlers/node/cli/commands/db/schema/load.js

@@ -1,4 +1,6 @@
 import BaseCommand from "../../../../../../cli/base-command.js"
+import commandArguments from "../../../../../../cli/command-arguments.js"
+import DatabaseGenerationContext from "../../../../../../database/generation-context.js"
 import fs from "fs/promises"
 import path from "path"
 import StructureSqlLoader from "../../../../../../database/structure-sql-loader.js"
@@ -9,17 +11,44 @@ export default class DbSchemaLoad extends BaseCommand {
    * Runs execute.
    * @returns {Promise<void>} */
   async execute() {
-    await this.getConfiguration().ensureConnections({name: "DB schema load"}, async (dbs) => {
-      const dbDir = path.join(this.directory(), "db")
-      const loader = new StructureSqlLoader()
+    const parsedArguments = commandArguments({
+      definition: {valueOptions: ["--tenant"]},
+      processArgs: this.processArgs || []
+    })
+    const tenantDatabaseIdentifier = parsedArguments.tenant
 
-      for (const identifier of Object.keys(dbs)) {
-        const db = dbs[identifier]
-        const structureFilePath = path.join(dbDir, `structure-${identifier}.sql`)
-        const structureSql = await fs.readFile(structureFilePath, "utf8")
+    if (typeof tenantDatabaseIdentifier === "string") {
+      const context = await DatabaseGenerationContext.resolve({
+        configuration: this.getConfiguration(),
+        databaseIdentifier: tenantDatabaseIdentifier
+      })
 
-        await loader.load({db, structureSql})
+      await context.run({name: "DB selected tenant schema load", callback: async (db) => {
+        await this.loadStructureSql({db, identifier: context.databaseIdentifier()})
+      }})
+      return
+    }
+
+    await this.getConfiguration().ensureConnections({name: "DB schema load"}, async (dbs) => {
+      for (const identifier of Object.keys(dbs)) {
+        await this.loadStructureSql({db: dbs[identifier], identifier})
       }
     })
   }
+
+  /**
+   * Loads one identifier's explicit structure file into one selected connection.
+   * @param {object} args - Load arguments.
+   * @param {import("../../../../../../database/drivers/base.js").default} args.db - Target connection.
+   * @param {string} args.identifier - Logical database identifier used in the file name.
+   * @returns {Promise<void>} - Resolves after loading.
+   */
+  async loadStructureSql({db, identifier}) {
+    const dbDir = path.join(this.directory(), "db")
+    const loader = new StructureSqlLoader()
+    const structureFilePath = path.join(dbDir, `structure-${identifier}.sql`)
+    const structureSql = await fs.readFile(structureFilePath, "utf8")
+
+    await loader.load({db, structureSql})
+  }
 }

package/build/environment-handlers/node/cli/commands/generate/base-models.js

@@ -1,6 +1,8 @@
 // @ts-check
 
 import BaseCommand from "../../../../../cli/base-command.js"
+import commandArguments from "../../../../../cli/command-arguments.js"
+import DatabaseGenerationContext from "../../../../../database/generation-context.js"
 import deburrColumnName from "../../../../../utils/deburr-column-name.js"
 import fileExists from "../../../../../utils/file-exists.js"
 import fs from "fs/promises"
@@ -62,15 +64,64 @@ function generatedRelationshipMethod({abstract = false, body, name, param, retur
 
 export default class DbGenerateModel extends BaseCommand {
   async execute() {
+    const parsedArguments = commandArguments({
+      definition: {
+        booleanOptions: ["--allow-missing-tables"],
+        valueOptions: ["--tenant"]
+      },
+      processArgs: this.processArgs || []
+    })
+    const allowMissingTables = parsedArguments["allow-missing-tables"] === true
+    const tenantDatabaseIdentifier = parsedArguments.tenant
+
+    if (typeof tenantDatabaseIdentifier === "string") {
+      const context = await DatabaseGenerationContext.resolve({
+        configuration: this.getConfiguration(),
+        databaseIdentifier: tenantDatabaseIdentifier
+      })
+      const selectedModelClasses = Object.values(this.getConfiguration().getModelClasses()).filter((modelClass) => {
+        const databaseIdentifier = modelClass.getDatabaseIdentifier({
+          enforceTenantDatabaseScope: false,
+          tenant: context.tenant()
+        })
+
+        if (databaseIdentifier !== context.databaseIdentifier()) return false
+
+        return modelClass.getDatabaseIdentifier({tenant: context.tenant()}) === context.databaseIdentifier()
+      })
+
+      try {
+        return await context.run({name: "Generate selected tenant base models", callback: async (connection) => {
+          await this.generateBaseModels({allowMissingTables, connections: {[context.databaseIdentifier()]: connection}, context})
+        }})
+      } finally {
+        for (const modelClass of selectedModelClasses) modelClass.resetRecordMetadata()
+      }
+    }
+
     await this.getConfiguration().initializeModels()
 
-    const enforceTenantDatabaseScopes = this.getConfiguration().getEnforceTenantDatabaseScopes()
+    return await this.getConfiguration().ensureConnections({name: "Generate base models"}, async (connections) => {
+      await this.generateBaseModels({allowMissingTables, connections})
+    })
+  }
 
+  /**
+   * Generates model bases from explicit connections.
+   * @param {object} args - Generation arguments.
+   * @param {boolean} args.allowMissingTables - Whether absent tables are skipped.
+   * @param {Record<string, import("../../../../../database/drivers/base.js").default>} args.connections - Connections keyed by logical identifier.
+   * @param {DatabaseGenerationContext} [args.context] - Selected tenant database context.
+   * @returns {Promise<void>} - Resolves after writing generated bases.
+   */
+  async generateBaseModels({allowMissingTables, connections, context}) {
     const rootDirectory = this.directory()
     const modelsDir = `${rootDirectory}/src/models`
     const baseModelsDir = `${rootDirectory}/src/model-bases`
     const modelClasses = this.getConfiguration().getModelClasses()
-    const allowMissingTables = Boolean(this.processArgs?.includes("--allow-missing-tables"))
+    const regenerateCommand = context
+      ? `${BASE_MODELS_REGENERATE_COMMAND} --tenant ${context.databaseIdentifier()}`
+      : BASE_MODELS_REGENERATE_COMMAND
     let devMode = false
 
     if (baseModelsDir.includes("/spec/dummy/src/model-bases")) {
@@ -81,13 +132,33 @@ export default class DbGenerateModel extends BaseCommand {
       await fs.mkdir(baseModelsDir, {recursive: true})
     }
 
-    this.getConfiguration().setEnforceTenantDatabaseScopes(false)
-
-    try {
-      await this.getConfiguration().ensureConnections({name: "Generate base models"}, async () => {
-        for (const modelClassName in modelClasses) {
+    for (const modelClassName in modelClasses) {
         const modelClass = modelClasses[modelClassName]
-        const table = await modelClass.connection().getTableByName(modelClass.tableName(), {throwError: !allowMissingTables})
+        let databaseIdentifier
+
+        if (context) {
+          databaseIdentifier = modelClass.getDatabaseIdentifier({
+            enforceTenantDatabaseScope: false,
+            tenant: context.tenant()
+          })
+
+          if (databaseIdentifier !== context.databaseIdentifier()) continue
+
+          databaseIdentifier = modelClass.getDatabaseIdentifier({tenant: context.tenant()})
+        } else {
+          databaseIdentifier = modelClass.getConfiguredDatabaseIdentifier()
+        }
+
+        if (context && databaseIdentifier !== context.databaseIdentifier()) continue
+
+        const connection = connections[databaseIdentifier]
+
+        // Default generation continues to ignore inactive tenant-only identifiers.
+        if (!connection) continue
+
+        if (context) modelClass.resetRecordMetadata()
+
+        const table = await connection.getTableByName(modelClass.tableName(), {throwError: !allowMissingTables})
 
         if (!table) {
           console.warn(`Skipping base model for '${modelClass.name}': table '${modelClass.tableName()}' was not found (--allow-missing-tables). Keeping any existing base model.`)
@@ -95,6 +166,8 @@ export default class DbGenerateModel extends BaseCommand {
           continue
         }
 
+        await modelClass.ensureInitialized({configuration: this.getConfiguration(), connection})
+
         const modelName = inflection.dasherize(modelClassName)
         const modelNameCamelized = inflection.camelize(modelName.replaceAll("-", "_"))
         const modelBaseFileName = `${inflection.dasherize(inflection.underscore(modelName))}.js`
@@ -111,7 +184,7 @@ export default class DbGenerateModel extends BaseCommand {
           sourceModelFilePath = "velocious/build/src/database/record/index.js"
         }
 
-        let fileContent = generatedFileBanner(BASE_MODELS_REGENERATE_COMMAND)
+        let fileContent = generatedFileBanner(regenerateCommand)
         let velociousPath
 
         if (devMode) {
@@ -454,10 +527,6 @@ export default class DbGenerateModel extends BaseCommand {
       fileContent += "}\n"
 
         await fs.writeFile(modelPath, fileContent)
-        }
-      })
-    } finally {
-      this.getConfiguration().setEnforceTenantDatabaseScopes(enforceTenantDatabaseScopes)
     }
   }
 

package/build/src/cli/command-arguments.d.ts

@@ -0,0 +1,27 @@
+export type CommandArgumentDefinition = {
+    /**
+     * - Flags that do not accept a value.
+     */
+    booleanOptions?: string[];
+    /**
+     * - Flags that require one value.
+     */
+    valueOptions?: string[];
+};
+/**
+ * @typedef {object} CommandArgumentDefinition
+ * @property {string[]} [booleanOptions] - Flags that do not accept a value.
+ * @property {string[]} [valueOptions] - Flags that require one value.
+ */
+/**
+ * Parses and validates one command's arguments.
+ * @param {object} args - Parser arguments.
+ * @param {CommandArgumentDefinition} args.definition - Accepted command options.
+ * @param {string[]} args.processArgs - Raw command arguments including the command name.
+ * @returns {Record<string, string | boolean>} - Values keyed by long option name without `--`.
+ */
+export default function commandArguments({ definition, processArgs }: {
+    definition: CommandArgumentDefinition;
+    processArgs: string[];
+}): Record<string, string | boolean>;
+//# sourceMappingURL=command-arguments.d.ts.map