velocious 1.0.481 → 1.0.483

package/src/database/tenants/data-copier.js

@@ -0,0 +1,269 @@
+// @ts-check
+
+const DEFAULT_INSERT_CHUNK_SIZE = 100
+const DEFAULT_QUERY_CHUNK_SIZE = 500
+
+/**
+ * Splits an array into chunks of at most `chunkSize` items.
+ * @template T
+ * @param {T[]} values
+ * @param {number} chunkSize
+ * @returns {T[][]}
+ */
+function chunks(values, chunkSize) {
+  const chunkedValues = []
+
+  for (let index = 0; index < values.length; index += chunkSize) {
+    chunkedValues.push(values.slice(index, index + chunkSize))
+  }
+
+  return chunkedValues
+}
+
+/**
+ * Stringifies values and returns the distinct, non-blank ones, preserving first-seen order.
+ * @param {unknown[]} values
+ * @returns {string[]}
+ */
+function uniqueStrings(values) {
+  return Array.from(new Set(values.map((value) => String(value)).filter((value) => value.trim())))
+}
+
+/**
+ * Copies a single tenant's rows from a source database into a target database, following a
+ * table plan that partitions each table either by a direct tenant key column or by
+ * parent-id traversal. This is the row-level counterpart to schema cloning: multi-tenant
+ * apps that keep each tenant's data in its own database use it to (re)materialise the
+ * tenant's rows from a global/template database.
+ *
+ * The copy is delete-then-reinsert and therefore idempotent, and it mirrors the source
+ * snapshot: the rows to delete are the tenant's *current* rows in the target (selected with
+ * the same plan traversal run against the target), so a row that was removed from the source
+ * since the last copy is dropped from the target too rather than lingering. The deletes run
+ * children first and the source inserts parents first, all inside one target transaction with
+ * foreign-key enforcement disabled so the ordering never trips a constraint. Reads, deletes
+ * and inserts are chunked to bound statement size.
+ *
+ * The copier is policy-free: the caller supplies the plan, the source/target databases and
+ * the tenant key, and {@link DataCopier#copy} returns the loaded rows keyed by table name so
+ * the caller can perform any app-specific post-copy work (for example registering record
+ * locations) without that policy leaking into the framework.
+ */
+export default class DataCopier {
+  /**
+   * Creates a copier that moves tenant-owned rows from `sourceDb` into `targetDb`.
+   * @param {{
+   *   sourceDb: import("../drivers/base.js").default,
+   *   targetDb: import("../drivers/base.js").default,
+   *   tablePlan: import("./tenant-table-plan.js").TenantTablePlanEntry[],
+   *   idColumn?: string,
+   *   insertChunkSize?: number,
+   *   queryChunkSize?: number,
+   *   onProgress?: (message: string) => void
+   * }} args
+   */
+  constructor({sourceDb, targetDb, tablePlan, idColumn = "id", insertChunkSize = DEFAULT_INSERT_CHUNK_SIZE, queryChunkSize = DEFAULT_QUERY_CHUNK_SIZE, onProgress}) {
+    this.sourceDb = sourceDb
+    this.targetDb = targetDb
+    this.tablePlan = tablePlan
+    this.idColumn = idColumn
+    this.insertChunkSize = insertChunkSize
+    this.queryChunkSize = queryChunkSize
+    this.onProgress = onProgress
+  }
+
+  /**
+   * Copies every plan table's rows for `keyValue` from the source into the target and
+   * returns the copied source rows keyed by table name. The target's current tenant rows
+   * are deleted (children first) and the source rows inserted (parents first) in a single
+   * target transaction with foreign keys disabled.
+   * @param {string} keyValue
+   * @returns {Promise<Map<string, Record<string, unknown>[]>>}
+   */
+  async copy(keyValue) {
+    const sourceRowsByTableName = await this.loadRows(this.sourceDb, keyValue)
+    const targetRowsByTableName = await this.loadRows(this.targetDb, keyValue)
+
+    await this.targetDb.withDisabledForeignKeys(async () => {
+      await this.targetDb.transaction(async () => {
+        await this.deleteTargetRows(targetRowsByTableName)
+        await this.insertTargetRows(sourceRowsByTableName)
+      })
+    })
+
+    return sourceRowsByTableName
+  }
+
+  /**
+   * Loads the rows for `keyValue` for every table in the plan from `db`, resolving
+   * parent-scoped tables from the ids already selected for their parent table. Used for
+   * both the source rows to copy and the target's current tenant rows to delete.
+   * @param {import("../drivers/base.js").default} db
+   * @param {string} keyValue
+   * @returns {Promise<Map<string, Record<string, unknown>[]>>}
+   */
+  async loadRows(db, keyValue) {
+    /** @type {Map<string, string[]>} */
+    const idsByTableName = new Map()
+    /** @type {Map<string, Record<string, unknown>[]>} */
+    const rowsByTableName = new Map()
+
+    for (const tableConfig of this.tablePlan) {
+      let rows
+
+      if (tableConfig.keyColumn) {
+        rows = await this.queryRowsByColumn({
+          columnName: tableConfig.keyColumn,
+          db,
+          tableName: tableConfig.tableName,
+          values: [keyValue]
+        })
+      } else {
+        if (!tableConfig.parentColumn || !tableConfig.parentTableName) {
+          throw new Error(`Expected keyColumn or parentTableName+parentColumn for table ${tableConfig.tableName} in the tenant table plan.`)
+        }
+
+        if (!idsByTableName.has(tableConfig.parentTableName)) {
+          throw new Error(`Tenant table plan entry ${tableConfig.tableName} references parent table ${tableConfig.parentTableName}, which has not been loaded; parent tables must appear before their children in the plan.`)
+        }
+
+        rows = await this.queryRowsByColumn({
+          columnName: tableConfig.parentColumn,
+          db,
+          tableName: tableConfig.tableName,
+          values: idsByTableName.get(tableConfig.parentTableName) || []
+        })
+      }
+
+      if (rows.length > 0) {
+        this.reportProgress(`${tableConfig.tableName}: loaded ${rows.length} row(s)`)
+      }
+
+      idsByTableName.set(tableConfig.tableName, uniqueStrings(rows.map((row) => row[this.idColumn])))
+      rowsByTableName.set(tableConfig.tableName, rows)
+    }
+
+    return rowsByTableName
+  }
+
+  /**
+   * Selects all rows of `tableName` in `db` whose `columnName` is in `values`, chunked.
+   * @param {{columnName: string, db: import("../drivers/base.js").default, tableName: string, values: string[]}} args
+   * @returns {Promise<Record<string, unknown>[]>}
+   */
+  async queryRowsByColumn({columnName, db, tableName, values}) {
+    const normalizedValues = uniqueStrings(values)
+
+    if (normalizedValues.length <= 0) {
+      return []
+    }
+
+    const rows = []
+    const quotedTable = db.quoteTable(tableName)
+    const quotedColumn = db.quoteColumn(columnName)
+
+    for (const valuesChunk of chunks(normalizedValues, this.queryChunkSize)) {
+      const sql = `SELECT ${quotedTable}.* FROM ${quotedTable} WHERE ${quotedColumn} IN (${this.quotedValuesSql(db, valuesChunk)})`
+
+      rows.push(...await this.executeQuietQuery(db, sql))
+    }
+
+    return rows
+  }
+
+  /**
+   * Deletes the matching target rows for every plan table, children before parents, so the
+   * reinsert that follows starts from a clean slate without violating foreign keys.
+   * @param {Map<string, Record<string, unknown>[]>} rowsByTableName
+   * @returns {Promise<void>}
+   */
+  async deleteTargetRows(rowsByTableName) {
+    for (const tableConfig of [...this.tablePlan].reverse()) {
+      const rowIds = uniqueStrings((rowsByTableName.get(tableConfig.tableName) || []).map((row) => row[this.idColumn]))
+
+      if (rowIds.length <= 0) {
+        continue
+      }
+
+      const quotedTable = this.targetDb.quoteTable(tableConfig.tableName)
+      const quotedIdColumn = this.targetDb.quoteColumn(this.idColumn)
+
+      for (const rowIdsChunk of chunks(rowIds, this.queryChunkSize)) {
+        await this.executeQuietQuery(
+          this.targetDb,
+          `DELETE FROM ${quotedTable} WHERE ${quotedIdColumn} IN (${this.quotedValuesSql(this.targetDb, rowIdsChunk)})`
+        )
+      }
+    }
+  }
+
+  /**
+   * Inserts the loaded source rows into the target for every plan table, parents before
+   * children, chunked to bound statement size.
+   * @param {Map<string, Record<string, unknown>[]>} rowsByTableName
+   * @returns {Promise<void>}
+   */
+  async insertTargetRows(rowsByTableName) {
+    for (const tableConfig of this.tablePlan) {
+      const rows = rowsByTableName.get(tableConfig.tableName) || []
+
+      if (rows.length <= 0) {
+        continue
+      }
+
+      const columns = Object.keys(rows[0])
+      const insertChunks = chunks(rows, this.insertChunkSize)
+
+      this.reportProgress(`${tableConfig.tableName}: inserting ${rows.length} row(s) in ${insertChunks.length} chunk(s)`)
+
+      for (const rowsChunk of insertChunks) {
+        await this.insertRowsQuietly({
+          columns,
+          db: this.targetDb,
+          rows: rowsChunk.map((row) => columns.map((column) => row[column])),
+          tableName: tableConfig.tableName
+        })
+      }
+    }
+  }
+
+  /**
+   * Quotes and comma-joins values for an SQL `IN (...)` list against the given database.
+   * @param {import("../drivers/base.js").default} db
+   * @param {string[]} values
+   * @returns {string}
+   */
+  quotedValuesSql(db, values) {
+    return values.map((value) => db.quote(value)).join(", ")
+  }
+
+  /**
+   * Runs a query without per-query logging, used for the high-volume copy statements.
+   * @param {import("../drivers/base.js").default} db
+   * @param {string} sql
+   * @returns {Promise<Record<string, unknown>[]>}
+   */
+  async executeQuietQuery(db, sql) {
+    return await db.query(sql, {logQuery: false})
+  }
+
+  /**
+   * Inserts column-aligned row tuples into a table without per-query logging.
+   * @param {{columns: string[], db: import("../drivers/base.js").default, rows: Array<Array<unknown>>, tableName: string}} args
+   * @returns {Promise<void>}
+   */
+  async insertRowsQuietly({columns, db, rows, tableName}) {
+    await this.executeQuietQuery(db, db.insertSql({columns, tableName, rows}))
+  }
+
+  /**
+   * Forwards a progress message to the optional `onProgress` callback when one was given.
+   * @param {string} message
+   * @returns {void}
+   */
+  reportProgress(message) {
+    if (this.onProgress) {
+      this.onProgress(message)
+    }
+  }
+}

package/src/database/tenants/schema-cloner.js

@@ -0,0 +1,390 @@
+// @ts-check
+
+import MigrationsLedger from "../migrations-ledger.js"
+import TableData from "../table-data/index.js"
+import TableIndex from "../table-data/table-index.js"
+
+const SIMPLE_DEFAULT_PATTERN = /^(?:-?\d+(?:\.\d+)?|[A-Za-z0-9 _.,:/@+-]*)$/
+
+/** @type {Record<string, number>} */
+const TEXT_TYPE_RANKS = {
+  tinytext: 1,
+  text: 2,
+  mediumtext: 3,
+  longtext: 4
+}
+
+/**
+ * Clones table structure (columns, text-type widening, indexes) from a source database
+ * into a target database for a given set of tables, then baselines the target's
+ * `schema_migrations` ledger to the source via {@link MigrationsLedger}. This is the
+ * mechanism multi-tenant apps use to provision a tenant database from a template/global
+ * database without re-running migrations: the structure is copied and the ledger is
+ * recorded as already-applied, so a later `db:tenants:migrate` does not re-run an
+ * `addColumn` whose column already exists.
+ *
+ * The cloner is intentionally policy-free — the caller decides which tables to sync and
+ * which databases are source/target. It is idempotent: missing tables are created,
+ * missing columns added, too-narrow text columns widened, and missing indexes created;
+ * an index whose definition diverges from the source is treated as drift and throws.
+ */
+export default class SchemaCloner {
+  /**
+   * Creates a cloner that copies table structure from `sourceDb` into `targetDb`.
+   * @param {{sourceDb: import("../drivers/base.js").default, targetDb: import("../drivers/base.js").default}} args
+   */
+  constructor({sourceDb, targetDb}) {
+    this.sourceDb = sourceDb
+    this.targetDb = targetDb
+  }
+
+  /**
+   * Clones every given table from the source into the target, then baselines the
+   * target's ledger so the cloned schema is recorded as already-migrated.
+   * @param {string[]} tableNames
+   * @returns {Promise<void>}
+   */
+  async syncTables(tableNames) {
+    for (const tableName of tableNames) {
+      await this.syncTable(tableName)
+    }
+
+    await this.reconcileLedger()
+  }
+
+  /**
+   * Clones a single table from the source into the target, creating it or adding and
+   * widening columns and indexes as needed.
+   * @param {string} tableName
+   * @returns {Promise<void>}
+   */
+  async syncTable(tableName) {
+    const sourceTable = await this.sourceDb.getTableByName(tableName)
+
+    if (!sourceTable) {
+      throw new Error(`Expected source table to exist: ${tableName}`)
+    }
+
+    if (!await this.targetDb.tableExists(tableName)) {
+      await this.createTargetTable({sourceTable, tableName})
+      return
+    }
+
+    const changedColumns = await this.ensureTargetColumns({sourceTable, tableName})
+
+    if (changedColumns) {
+      this.targetDb.clearSchemaCache()
+    }
+
+    await this.ensureTargetIndexes({sourceTable, tableName})
+  }
+
+  /**
+   * Creates the table in the target from the source table's columns and its
+   * non-primary-key indexes.
+   * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args
+   * @returns {Promise<void>}
+   */
+  async createTargetTable({sourceTable, tableName}) {
+    const tableData = new TableData(tableName)
+
+    for (const sourceColumn of await sourceTable.getColumns()) {
+      tableData.addColumn(sourceColumn.getName(), this.columnArgsFromSourceColumn(sourceColumn, {isNewColumn: false}))
+    }
+
+    for (const sourceIndex of await sourceTable.getIndexes()) {
+      if (!sourceIndex.isPrimaryKey()) {
+        tableData.addIndex(this.tableDataIndexFromSourceIndex(sourceIndex))
+      }
+    }
+
+    await this.targetDb.createTable(tableData)
+    this.targetDb.clearSchemaCache()
+  }
+
+  /**
+   * Adds columns present on the source but missing from the target, and widens
+   * too-narrow target text columns.
+   * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args
+   * @returns {Promise<boolean>} Whether any column was added or widened.
+   */
+  async ensureTargetColumns({sourceTable, tableName}) {
+    const sourceColumns = await sourceTable.getColumns()
+    const targetTable = await this.targetDb.getTableByNameOrFail(tableName)
+    const targetColumnsByName = new Map()
+    const missingColumns = []
+    const columnsNeedingWidening = []
+
+    for (const targetColumn of await targetTable.getColumns()) {
+      targetColumnsByName.set(targetColumn.getName(), targetColumn)
+    }
+
+    for (const sourceColumn of sourceColumns) {
+      const targetColumn = targetColumnsByName.get(sourceColumn.getName())
+
+      if (!targetColumn) {
+        missingColumns.push(sourceColumn)
+      } else if (this.columnNeedsWidening(sourceColumn, targetColumn)) {
+        columnsNeedingWidening.push(sourceColumn)
+      }
+    }
+
+    if (missingColumns.length <= 0 && columnsNeedingWidening.length <= 0) {
+      return false
+    }
+
+    const tableData = new TableData(tableName)
+
+    for (const sourceColumn of missingColumns) {
+      tableData.addColumn(sourceColumn.getName(), this.columnArgsFromSourceColumn(sourceColumn, {isNewColumn: true}))
+    }
+
+    for (const sourceColumn of columnsNeedingWidening) {
+      tableData.addColumn(sourceColumn.getName(), this.columnArgsFromSourceColumn(sourceColumn, {isNewColumn: false}))
+    }
+
+    for (const alterSql of await this.targetDb.alterTableSQLs(tableData)) {
+      await this.targetDb.query(alterSql)
+    }
+
+    return true
+  }
+
+  /**
+   * Creates non-primary-key indexes present on the source but missing from the target,
+   * and throws if an existing target index diverges from the source.
+   * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args
+   * @returns {Promise<void>}
+   */
+  async ensureTargetIndexes({sourceTable, tableName}) {
+    const targetTable = await this.targetDb.getTableByNameOrFail(tableName)
+    /** @type {Map<string, import("../drivers/base-columns-index.js").default>} */
+    const targetIndexesByName = new Map()
+    const targetIndexSignatures = new Set()
+    let createdIndex = false
+
+    for (const targetIndex of await targetTable.getIndexes()) {
+      targetIndexesByName.set(targetIndex.getName(), targetIndex)
+      targetIndexSignatures.add(this.indexSignature(targetIndex))
+    }
+
+    for (const sourceIndex of await sourceTable.getIndexes()) {
+      if (sourceIndex.isPrimaryKey()) {
+        continue
+      }
+
+      const sourceIndexSignature = this.indexSignature(sourceIndex)
+
+      // SQLite index names are unique per-database, not per-table, so match cloned
+      // indexes by their column/uniqueness signature rather than their name.
+      if (this.targetDb.getType() === "sqlite" && targetIndexSignatures.has(sourceIndexSignature)) {
+        continue
+      }
+
+      const targetIndex = this.targetDb.getType() === "sqlite" ? undefined : targetIndexesByName.get(sourceIndex.getName())
+
+      if (!targetIndex) {
+        const createIndexSqls = await this.targetDb.createIndexSQLs(this.createIndexArgsFromSourceIndex({sourceIndex, tableName}))
+
+        for (const createIndexSql of createIndexSqls) {
+          await this.targetDb.query(createIndexSql)
+        }
+
+        createdIndex = true
+        targetIndexSignatures.add(sourceIndexSignature)
+        continue
+      }
+
+      if (!this.indexesMatch(sourceIndex, targetIndex)) {
+        throw new Error(`Schema clone index drift for ${tableName}.${sourceIndex.getName()}`)
+      }
+    }
+
+    if (createdIndex) {
+      this.targetDb.clearSchemaCache()
+    }
+  }
+
+  /**
+   * Baselines the target ledger so the cloned schema is recorded as already-applied.
+   * @returns {Promise<string[]>} The versions newly recorded on the target.
+   */
+  async reconcileLedger() {
+    return await MigrationsLedger.baselineFromDatabase({sourceDb: this.sourceDb, targetDb: this.targetDb})
+  }
+
+  /**
+   * Whether the target ledger is missing any version applied on the source — i.e. the
+   * target schema may have been advanced out of band without recording it.
+   * @returns {Promise<boolean>}
+   */
+  async ledgerDriftsFromSource() {
+    if (!await MigrationsLedger.tableExists(this.targetDb)) {
+      return true
+    }
+
+    const sourceVersions = await MigrationsLedger.appliedVersions(this.sourceDb)
+    const targetVersionSet = new Set(await MigrationsLedger.appliedVersions(this.targetDb))
+
+    return sourceVersions.some((version) => !targetVersionSet.has(version))
+  }
+
+  /**
+   * Maps a source index into a TableData index for table creation (SQLite omits the
+   * index name so the driver can generate a unique one).
+   * @param {import("../drivers/base-columns-index.js").default} sourceIndex
+   * @returns {TableIndex}
+   */
+  tableDataIndexFromSourceIndex(sourceIndex) {
+    /** @type {{name?: string, unique: boolean}} */
+    const args = {unique: sourceIndex.isUnique()}
+
+    // SQLite index names are unique per-database, not per-table, so let the driver
+    // generate one; other drivers preserve the source index name. Build the TableIndex
+    // directly (rather than via the driver's getTableDataIndex, which only MySQL and
+    // SQLite implement) so cloning a PostgreSQL or MS-SQL source table works too.
+    if (this.targetDb.getType() !== "sqlite") {
+      args.name = sourceIndex.getName()
+    }
+
+    return new TableIndex(sourceIndex.getColumnNames(), args)
+  }
+
+  /**
+   * Builds driver create-index args from a source index (the index name is omitted on
+   * SQLite, where index names are unique per-database rather than per-table).
+   * @param {{sourceIndex: import("../drivers/base-columns-index.js").default, tableName: string}} args
+   * @returns {{columns: string[], name?: string, tableName: string, unique: boolean}}
+   */
+  createIndexArgsFromSourceIndex({sourceIndex, tableName}) {
+    /** @type {{columns: string[], name?: string, tableName: string, unique: boolean}} */
+    const createIndexArgs = {
+      columns: sourceIndex.getColumnNames(),
+      tableName,
+      unique: sourceIndex.isUnique()
+    }
+
+    if (this.targetDb.getType() !== "sqlite") {
+      createIndexArgs.name = sourceIndex.getName()
+    }
+
+    return createIndexArgs
+  }
+
+  /**
+   * Whether two indexes have the same uniqueness and ordered column list.
+   * @param {import("../drivers/base-columns-index.js").default} sourceIndex
+   * @param {import("../drivers/base-columns-index.js").default} targetIndex
+   * @returns {boolean}
+   */
+  indexesMatch(sourceIndex, targetIndex) {
+    const sourceColumnNames = sourceIndex.getColumnNames()
+    const targetColumnNames = targetIndex.getColumnNames()
+
+    if (sourceIndex.isUnique() !== targetIndex.isUnique()) {
+      return false
+    }
+
+    if (sourceColumnNames.length !== targetColumnNames.length) {
+      return false
+    }
+
+    for (let columnIndex = 0; columnIndex < sourceColumnNames.length; columnIndex++) {
+      if (sourceColumnNames[columnIndex] !== targetColumnNames[columnIndex]) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * A stable signature for an index, used to match cloned indexes by shape.
+   * @param {import("../drivers/base-columns-index.js").default} index
+   * @returns {string}
+   */
+  indexSignature(index) {
+    return `${index.isUnique() ? "unique" : "index"}:${index.getColumnNames().join(",")}`
+  }
+
+  /**
+   * Normalizes a column type to its canonical lowercase form (`int` becomes `integer`).
+   * @param {string} columnType
+   * @returns {string}
+   */
+  normalizedColumnType(columnType) {
+    const normalizedType = columnType.toLowerCase()
+
+    if (normalizedType === "int") {
+      return "integer"
+    }
+
+    return normalizedType
+  }
+
+  /**
+   * The widening rank of a text column type (0 when not a text type).
+   * @param {string} columnType
+   * @returns {number}
+   */
+  textTypeRank(columnType) {
+    return TEXT_TYPE_RANKS[this.normalizedColumnType(columnType)] || 0
+  }
+
+  /**
+   * Whether the target's text column is narrower than the source's and must be widened.
+   * @param {import("../drivers/base-column.js").default} sourceColumn
+   * @param {import("../drivers/base-column.js").default} targetColumn
+   * @returns {boolean}
+   */
+  columnNeedsWidening(sourceColumn, targetColumn) {
+    const sourceRank = this.textTypeRank(sourceColumn.getType())
+    const targetRank = this.textTypeRank(targetColumn.getType())
+
+    return sourceRank > 0 && targetRank > 0 && sourceRank > targetRank
+  }
+
+  /**
+   * Builds TableData column args from a source column, copying type, nullability,
+   * length, notes, simple defaults and (for full clones) primary-key flag.
+   * @param {import("../drivers/base-column.js").default} sourceColumn
+   * @param {{isNewColumn: boolean}} args
+   * @returns {Record<string, unknown>}
+   */
+  columnArgsFromSourceColumn(sourceColumn, {isNewColumn}) {
+    /** @type {{autoIncrement?: boolean, default?: unknown, isNewColumn: boolean, maxLength?: number, notes?: string, null: boolean, primaryKey?: boolean, type: string}} */
+    const columnArgs = {
+      isNewColumn,
+      null: sourceColumn.getNull(),
+      type: this.normalizedColumnType(sourceColumn.getType())
+    }
+    const defaultValue = sourceColumn.getDefault()
+    const maxLength = sourceColumn.getMaxLength()
+    const notes = sourceColumn.getNotes()
+
+    if (!isNewColumn && sourceColumn.getPrimaryKey()) {
+      columnArgs.primaryKey = true
+    }
+
+    if (sourceColumn.getAutoIncrement()) {
+      columnArgs.autoIncrement = true
+    }
+
+    // A maxLength of -1 is the MS-SQL "max" sentinel (NVARCHAR(MAX) / VARBINARY(MAX),
+    // backing Velocious text/json/blob columns); the column type drives the unbounded
+    // SQL, so don't forward -1 as an explicit length (it would emit NVARCHAR(-1)).
+    if (maxLength !== undefined && maxLength >= 0) {
+      columnArgs.maxLength = maxLength
+    }
+
+    if (notes) {
+      columnArgs.notes = notes
+    }
+
+    if (defaultValue !== null && defaultValue !== undefined && SIMPLE_DEFAULT_PATTERN.test(String(defaultValue))) {
+      columnArgs.default = defaultValue
+    }
+
+    return columnArgs
+  }
+}

package/src/database/tenants/tenant-table-plan.js

@@ -0,0 +1,20 @@
+// @ts-check
+
+/**
+ * Describes how one table's rows are partitioned between tenants so a DataCopier can select
+ * the subset that belongs to a given tenant key.
+ *
+ * A row belongs to the tenant when its `keyColumn` equals the tenant key value, or — for
+ * tables that have no direct tenant column — when its `parentColumn` references a row of
+ * `parentTableName` that was itself already selected as belonging to the tenant. Exactly
+ * one of `keyColumn` or the (`parentTableName` + `parentColumn`) pair must be set; a
+ * parent-scoped entry must appear after its parent in the plan so the parent ids are known
+ * by the time the child is loaded.
+ * @typedef {object} TenantTablePlanEntry
+ * @property {string} tableName Name of the table whose rows are partitioned by tenant.
+ * @property {string} [keyColumn] Column matched directly against the tenant key value.
+ * @property {string} [parentTableName] Earlier-in-plan table whose selected rows scope this one.
+ * @property {string} [parentColumn] Column on this table referencing the parent table's primary key.
+ */
+
+export {}