Back to Details

airtable-migration-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Airtable Migration Audit by straktur.com

由straktur.com提供的Airtable迁移审计工具

Analyzing: $ARGUMENTS
分析对象：$ARGUMENTS

What you deliver

输出内容

After running the audit, your response MUST contain these sections in order:
运行审计后，你的回复必须按以下顺序包含这些部分：

1. Verdict (1-2 sentences)

1. 结论（1-2句话）

Is this base ready to migrate? What's the overall complexity? Example: "This base is ready for migration with medium complexity. 4 core tables, clean relationships, but 3 data quality issues to fix first."
该数据库是否已准备好迁移？整体复杂度如何？ 示例：“该数据库已具备迁移条件，复杂度中等。包含4个核心表，关系清晰，但存在3个需先修复的数据质量问题。”

2. What you're working with (summary table)

2. 分析对象概况（汇总表格）

Tables, records, fields, relationships — from the report's Summary section.
表格、记录、字段、关联关系——来自报告的「汇总」部分。

3. Blockers (if any)

3. 阻碍因素（如有）

Issues that MUST be resolved before migration:
  • Circular dependencies
  • Cross-base links
  • Data quality warnings from the "Data cleanup needed" group
  • Constant fields / composite values that need restructuring
迁移前必须解决的问题：
  • 循环依赖
  • 跨数据库链接
  • 「需清理数据」分组中的数据质量警告
  • 常量字段/复合值需要重构

4. Schema recommendation

4. 架构建议

From the report's "Recommended Target Schema" section:
  • How many PostgreSQL tables (core + junction + lookup)
  • Import order
  • Key relationship decisions (which M2M needs junction tables, which linked records are just FKs)
来自报告的「推荐目标架构」部分：
  • 需要多少个PostgreSQL表（核心表 + 关联表 + 查找表）
  • 导入顺序
  • 关键关联决策（哪些多对多关系需要关联表，哪些关联记录仅需外键）

5. Next steps (numbered, actionable)

5. 后续步骤（编号、可执行）

What the user should do now, in order. Be specific — reference table and field names.
用户当前应按顺序执行的操作。需具体——引用表格和字段名称。

6. Blind spots

6. 局限性

What this audit does NOT cover:
  • Automations / scripts in Airtable (not exported)
  • Interface/view configurations
  • Attachment storage strategy (S3/R2 setup, URL preservation, access permissions — file counts and sizes ARE included in the audit)
  • Business logic in formulas (flagged but not translated)
  • Permission / access control mapping
本审计未覆盖的内容：
  • Airtable中的自动化/脚本（未导出）
  • 界面/视图配置
  • 附件存储策略（S3/R2设置、URL保留、访问权限——文件数量和大小已包含在审计中）
  • 公式中的业务逻辑（仅标记但未转换）
  • 权限/访问控制映射

How to run the audit

审计运行方法

Defaults — don't ask, just do:

默认规则——无需询问，直接执行：

  • If a full analysis report already exists in 
    data/
    , use the latest one (sort by folder name)
  • If only a schema-only report exists and user needs full analysis — run a new full analysis
  • Default to full analysis (not schema-only) unless the user explicitly asks for schema-only
  • If 
    AIRTABLE_BASE_IDS
    is not set and the script prompts for selection — tell the user it needs interactive input and run it
  • 如果
    data/
    目录中已存在完整分析报告，使用最新版本（按文件夹名称排序）
  • 如果仅存在架构报告而用户需要完整分析——运行新的完整分析
  • 默认使用完整分析（而非仅架构分析），除非用户明确要求仅架构分析
  • 如果未设置
    AIRTABLE_BASE_IDS
    且脚本提示选择——告知用户需要交互式输入并运行脚本

Prerequisites

前置条件

  • .env
    must have 
    AIRTABLE_API_KEY
    (Personal Access Token starting with 
    pat...
    )
  • AIRTABLE_BASE_IDS
    is optional — script auto-discovers bases if not set
  • .env
    文件中必须包含
    AIRTABLE_API_KEY
    （以
    pat...
    开头的个人访问令牌）
  • AIRTABLE_BASE_IDS
    为可选——若未设置，脚本会自动发现数据库

Run

运行命令

bash
undefined
bash
undefined

Full analysis (default)

完整分析（默认）

npx tsx src/discover.ts
npx tsx src/discover.ts

Schema only (if user asks for quick overview)

仅架构分析（若用户需要快速概览）

npx tsx src/discover.ts --schema-only
undefined
npx tsx src/discover.ts --schema-only
undefined

If it fails

故障排查

  • AIRTABLE_API_KEY not set → ask user for PAT from https://airtable.com/create/tokens (scopes: 
    schema.bases:read
    , 
    data.records:read
    )
  • API error 401 → token invalid or expired
  • API error 403 → token missing scopes or base access
  • API error 404 → wrong base ID, or token doesn't have access to that base
  • Rate limited (429) → script retries automatically, just wait

Read the report

查看报告

The report is at 
data/<date>_<HHMM>_<baseIds>/AIRTABLE_REPORT.md
. Read it, then deliver the structured output above.
报告位于
data/<date>_<HHMM>_<baseIds>/AIRTABLE_REPORT.md
。读取报告后，按上述结构化格式输出结果。

Key files

关键文件

FilePurpose
src/discover.ts
Main script — fetches and analyzes
data/<run>/AIRTABLE_REPORT.md
Generated report (gitignored)
data/<run>/raw-schema.json
Raw Airtable schema (gitignored)
文件用途
src/discover.ts
主脚本——负责获取数据并执行分析
data/<run>/AIRTABLE_REPORT.md
生成的报告（已加入git忽略）
data/<run>/raw-schema.json
原始Airtable架构（已加入git忽略）

Privacy / security

隐私与安全

  • The audit runs locally — data is fetched to the user's machine and reports are stored in 
    data/
  • No data is sent to Straktur or any third-party service
  • The Airtable token is used read-only (scopes: 
    schema.bases:read
    , 
    data.records:read
    )
  • If the user asks about privacy or data safety, explain the above
  • 审计本地运行——数据会抓取到用户设备，报告存储在
    data/
    目录中
  • 不会将数据发送至Straktur或任何第三方服务
  • Airtable令牌仅用于只读操作（权限范围：
    schema.bases:read
    , 
    data.records:read
    ）
  • 若用户询问隐私或数据安全问题，请解释上述内容

Do NOT

禁止操作

  • Do NOT dump the entire report — synthesize it into the structured output above
  • Do NOT ask which mode to use — default to full, mention schema-only as option only if relevant
  • Do NOT ask about previous reports — just use the latest one or generate a new one
  • 禁止直接输出完整报告——需将其整合为上述结构化输出内容
  • 禁止询问使用模式——默认使用完整分析，仅在相关时提及仅架构分析选项
  • 禁止询问过往报告——直接使用最新报告或生成新报告