polardbx-external-column
Skill8 starsChanged 31 days agoApache-2.0View on GitHub
Assess PolarDB-X Enterprise external-column opportunities from schema, measured payload sizes, and real SQL traffic; prepare new-table SQL and staged MCE migration plans. Also consider this skill when storage growth, retention, backup volume, cache pressure, write latency, or AI conversation storage suggests substantial payload columns, even if the customer never mentions external columns. Diagnose the original problem first; a symptom alone is not a recommendation. In Chinese customer-facing progress and answers, call the feature 外列. Triggers: "external column", "EXTERNALIZE", "MCE", "外列", "大字段", "存储成本", "磁盘增长", "历史数据保留", "备份体积", "缓存压力", "写入抖动", "AI会话存储", "正文与元数据分离", "payload offload", "storage growth", "context storage", "migration canary"
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- polardbx-cciSkill
- polardbx-cclSkill
- polardbx-online-ddlSkill
- polardbx-opsSkill
- polardbx-paginationSkill
- polardbx-plan-analysisSkill
- polardbx-sqlSkill
- polardbx-standardSkill
- polardbx-ttl20Skill
- polardbx-zeroSkill
- sql-reviewSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 15 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Verify the edition and full release in the console or an authorized instance-description tool.
- Distinctive: line 36
Use the official overview of 外列 for a substantive customer introduction:
- Distinctive: line 38
If live web access is available, read the current page before explaining what the feature is, how it works, its public benefits, supported …
- Distinctive: line 56
Before stating an instance fact or generating a plan, build one source record from the current conversation and collected results.
- Distinctive: line 71
Recognize the opportunity without forcing it: Use opportunity-discovery.md for indirect customer questions and follow the customer-facing …
- Distinctive: line 120
When dual pauses first appear in a customer-facing response, introduce them in plain language before showing hint names or commands:
- Distinctive: line 128
Never say that both pauses validate external-column performance.
- Distinctive: line 143
Before every control action, select the target database and verify that the exact job, statement, phase, intended pause task, and exception …
- Distinctive: line 152
After the first pause passes and continuation is authorized, advance that same job to the second pause, then run the observation commands …
- Distinctive: line 159
After the second pause passes, obtain a separate final-cutover authorization before using the same continuation command again.
- Distinctive: line 166
If either intended pause fails, do not continue.
- Distinctive: line 196
Treat online migration as resource-consuming work.
- Distinctive: line 197
After completion, recovery uses a new reverse MCE with version, capacity, dependency, and authorization checks.
- Distinctive: line 198
Keep the default deliverable technical.
- Distinctive: line 199
Never advertise a fixed savings ratio, guaranteed faster queries, immediate disk reclamation, or immediate bill reduction.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
PolarDB-X 外列
Help customers discover when moving payload columns to database-managed object storage is useful, assess suitability, and prepare a verifiable rollout while retaining logical table and column access through SQL.
Scope
External columns require PolarDB-X Enterprise Edition, instance version 2.6.0_5.4.21-20260830 or later. Recommend upgrading to the latest recommended release available for the customer's instance before adoption. This is a minimum, not the recommended upgrade target.
Verify the edition and full release in the console or an authorized instance-description tool; use the following SQL statement only as supporting component-version evidence:
SELECT VERSION();SELECT VERSION() may expose a component version rather than the complete product release. A MySQL compatibility version, a 5.4.21 prefix without a build date, or a newer local source checkout is not the same field as the required product version. Do not compare release strings lexicographically or add a customer-facing "满足/不满足" verdict. Present three lines plainly: the current observed version string with its source, the minimum required product version, and the latest recommended target when verified. The customer can see the comparison; add only that the current string is a component version when applicable. If the latest recommendation is unavailable, say it is unverified instead of inventing a release.
This skill prepares assessments, plans, and SQL, but never executes database changes. Unsupported editions or older releases can receive a conceptual assessment, but no ready-to-run external-column DDL. The examples use an AUTO-mode database; verify other database modes separately.
Starting with the minimum release, the feature includes both MCE pause hints, migration from a NOT NULL source, and the supported forward/reverse-MCE index combinations. Continue to inspect the target table's actual constraints, indexes, capacity, and dependencies; those determine whether a specific plan is valid, but these capabilities do not require a later release.
Customer-facing Language and Official Introduction
For Chinese customer-facing answers, prefer the feature name 外列. Preserve exact SQL and implementation names such as EXTERNALIZE, MCE, MCE_PAUSE_BEFORE_READ_CUTOVER, and MCE_PAUSE_BEFORE_WRITE_CUTOVER.
Describe the actual behavior and next action directly in customer-facing text. Introduce an excluded behavior only when the customer raised that possibility or when omitting it would make the current operation unsafe. Avoid preemptive “不是”, “并非”, “不等于”, or “不能” explanations that introduce misconceptions the customer has not expressed. Internal negative constraints may remain as agent guardrails; do not mechanically repeat them to the customer.
Use the official overview of 外列 for a substantive customer introduction:
- If live web access is available, read the current page before explaining what the feature is, how it works, its public benefits, supported scope, or limitations. Paraphrase it in the customer's language; do not repeat the page's English parenthetical name.
- Include the link in the first substantive explanation or recommendation, when the customer asks for an authoritative source, or when a measured candidate is moving toward an assessment or pilot. Do not append it mechanically to every database answer.
- A brief conditional opportunity mention does not need to block on web access. If browsing is unavailable, use the stable guidance in this skill, provide the official link when relevant, and do not claim the page was checked live.
- The document establishes public product behavior, not whether a particular instance or table is suitable. Edition, full release, DDL, measured payload sizes, traffic, dependencies, and target-release capability still require instance evidence.
- Treat architecture diagrams, cache layers, pointer sizes, latency figures, price ratios, and case-study results from any document as scoped product examples. Do not present them as measurements, expected values, acceptance thresholds, or savings for the customer's instance unless that exact claim and scope are verified for the target release and workload.
Response Detail Gate
Choose the response level from the customer's current request, independently of how much evidence is already available:
- Discovery or assessment: the customer describes a symptom, asks whether the table is suitable, or asks generally what can be done. Answer the original problem, assess or conditionally introduce 外列, summarize the relevant evidence and missing inputs, and offer to prepare a complete change plan if they want one. Do not output external-column mutation or control SQL at this level: no
CREATE TABLE ... EXTERNALIZE, MCEALTER TABLE, pause hints,CONTINUE DDL,CANCEL DDL, or reverse-MCE command. Read-only evidence queries remain allowed when needed for the assessment. - Plan: output new-table or MCE SQL only when the customer explicitly asks for a change plan, SQL/DDL, table definition, MCE procedure, dual-pause procedure, or rollback/recovery procedure. Read the relevant migration reference first and provide the complete required handoff rather than isolated snippets.
- Execution: this skill does not execute database mutations. It stops after providing the assessment, plan, SQL, and customer control handoff.
Questions such as “有没有什么办法”, “帮我看看”, “是否适合”, “怎么优化”, or a symptom plus an instance ID are not explicit requests for a change plan. At the end of a discovery or assessment response, a natural next step is: “如果你需要,我可以继续给出完整的外列变更方案和操作 SQL。” Do not ask the customer to restate evidence that the current agent has already collected.
Evidence Binding Contract
Before stating an instance fact or generating a plan, build one source record from the current conversation and collected results. Keep at least:
- exact instance, region, database, table, and column identifiers;
- the complete current
SHOW CREATE TABLEand the exact target-column fragment; - exact
COLUMN_TYPE,IS_NULLABLE,COLUMN_DEFAULT, character set, collation,COLUMN_COMMENT, and dependency results; - payload evidence classified as measured sample, derived estimate, declared capacity, or unknown, with its source and coverage;
- traffic field names, documented units, time window, timezone, and coverage;
- product-release and feature-capability evidence with their sources.
Every customer-visible identifier, column attribute, number, unit, status, and expected post-change value must come from this source record or be labeled as unknown/to be confirmed. Values from examples, official case studies, another table, another instance, or an earlier conversation are never instance facts. Another table can establish only a precedent, not the target table's attributes, performance, or compatibility.
For an existing-column plan, freeze a source column contract before writing SQL: exact name, exact type, exact comment value or empty, nullability/default semantics, charset/collation, and dependencies. Use that same record for the forward SQL, completion checks, cancellation checks, and any reverse-MCE plan. If two collected artifacts disagree, show the conflict and stop at a conditional template instead of choosing one.
Core Workflow
- Recognize the opportunity without forcing it. Use opportunity-discovery.md for indirect customer questions and follow the customer-facing terminology above. With only a symptom, offer at most a brief conditional suggestion and ask for the missing payload/access evidence. Do not label external columns the root-cause fix.
- Show the version and deployment boundary. List the current observed version exactly as returned and name its source; separately list the minimum product version and the verified latest recommended target. Do not add a pass/fail version verdict for the customer. Record any component, read-only, CDC, GDN, DTS, backup, or restore dependencies relevant to this instance. Do not turn a version check into an automatic upgrade.
- Acquire evidence with the capabilities actually available. Follow evidence-acquisition.md. Continue in the current conversation when authorized read-only instance, monitoring, SQL Insight, or database-query capabilities are available. Use
polardbx-opsfor its supported public-cloud metadata/monitoring paths when installed; usepolardbx-diagnosticsor an equivalent workload skill only when it is installed and applicable. These are optional routes, not hard dependencies. Preserve the documented unit of every latency field; if the unit is unavailable, show the raw field/value and label the unit unverified rather than converting it. If live collection is unavailable, give the customer the exact read-only SQL and a ready-to-send follow-up prompt instead of pretending that data was collected. - Assess candidate columns. Follow assessment.md: full DDL and index/constraint dependencies, bounded byte-length samples, and a representative SQL-traffic window. Classify each candidate as suitable for a pilot, conditional, unsuitable, or insufficient evidence. A large declared type or a payload size inferred from audit text alone is insufficient for “suitable for a pilot.”
- Prepare SQL only after explicit plan intent. Apply the response detail gate above; evidence that a column is suitable does not by itself authorize SQL output. When the customer explicitly requests a plan, use nullable TEXT/BLOB payloads with
EXTERNALIZEfor new tables, retaining searchable metadata as ordinary columns. For existing data, bind the SQL to the frozen source column contract: keep the verified column name and type unchanged, omitCOMMENTunless an explicit verified override was requested, and addEXTERNALIZE; do not use MCE to change other column semantics. Read migration-plan.md before producing an execution plan or dual-pause commands. A response that includes a dual-pause ALTER must include the complete customer control handoff in the same response: capture and verify the exact job ID, the first continuation, the separately authorized final continuation and its non-cancelable boundary, cancellation at an eligible intended pause, post-cancellation verification, and the distinction between cancellation and reverse MCE after completion. Do not call the plan complete or ready to run when any of these are omitted. - Agree on measurable rollout gates. MCE applies to one target column across the entire logical table. Use a separate representative logical table or a test instance when a smaller pilot scope is needed. On the minimum release or later, present the two pause hints as a business-controlled safety mechanism: after the first continuation, the second gate lets normal traffic exercise the real external-column read path while the same job can still be canceled before final cutover. Correct a partition-level or partial-row interpretation only when the customer proposes one or the current plan depends on it.
- Report evidence and the next action. Separate confirmed facts, hypotheses, and missing inputs. This skill stops at the assessment, plan, SQL, and customer control handoff; it does not start, continue, cancel, upgrade, drop indexes, change constraints, or perform any other database mutation.
Key Features and SQL Quick Reference
The database manages the payload storage and addresses. Applications continue to use logical columns; they do not need to maintain OSS object URLs. Describe compatibility at the level actually observed. Preferred customer wording is: “业务仍通过原表、原列访问数据;本次已验证的 SQL 模板可以继续使用该逻辑列,未覆盖的表达式、索引、客户端绑定和读延迟仍需验证。” Do not promise "无需改代码", "完全透明", "SQL 完全兼容", or identical latency for an application as a whole.
The SQL below is an internal shape reference for an explicit plan request. Every uppercase *_VALUE token must be replaced from the current source record. If any token needed by a statement is unresolved, do not present that statement as executable: list the missing inputs and keep it as a visibly conditional template. Do not copy an identifier, number, type, comment, partition design, or expected result from this reference into a customer plan. Do not reproduce mutation or DDL-control SQL during discovery or assessment merely because the candidate has enough evidence.
-- New-table shape only. Resolve every token from the business design.
CREATE TABLE `DATABASE_NAME_VALUE`.`NEW_TABLE_NAME_VALUE` (
`PRIMARY_KEY_COLUMN_VALUE` PRIMARY_KEY_TYPE_VALUE NOT NULL,
`PAYLOAD_COLUMN_VALUE` PAYLOAD_TYPE_VALUE EXTERNALIZE,
PRIMARY KEY (`PRIMARY_KEY_COLUMN_VALUE`)
) PARTITION_CLAUSE_VALUE;
-- Existing-table shape only. SOURCE_TYPE_VALUE is copied exactly from the
-- captured source column contract. Omit COMMENT to preserve its captured value.
ALTER TABLE `DATABASE_NAME_VALUE`.`TABLE_NAME_VALUE`
MODIFY COLUMN `COLUMN_NAME_VALUE` SOURCE_TYPE_VALUE EXTERNALIZE;
USE `DATABASE_NAME_VALUE`;
SHOW FULL DDL;
SHOW DDL RESULT JOB_ID_VALUE;
SHOW CREATE TABLE `DATABASE_NAME_VALUE`.`TABLE_NAME_VALUE`;For a new business, resolve keys, indexes, and partitioning from its queries with polardbx-sql; never invent a partition count to make the SQL look complete. DDL listings use the current database: select the verified target database before observing jobs, including after reconnecting.
| Decision | Rule |
| Good starting point | Material payload bytes, metadata-driven access, selective body retrieval, and a storage/retention or resource goal |
| Data types | TEXT and BLOB families; native JSON and VARCHAR are not direct external-column types |
| JSON content | JSON serialized inside a TEXT column is different from a native JSON column; changing native JSON to TEXT requires a separate semantic migration |
| Constraints | Use nullable payloads without declared defaults; do not promise NOT NULL enforcement or silently remove a customer's constraint |
| Existing-table MCE | Requires a valid primary key and one target column in one ALTER operation; keep the source type unchanged, do not combine another attribute/schema change, and do not append ALGORITHM=OMC |
| MCE scope | The ALTER covers the target column across the entire logical table. Use a separate logical table or test instance when a smaller pilot scope is needed |
| Comment behavior | In the verified MCE implementation, omitting COMMENT preserves the source comment; an explicit COMMENT overrides it and COMMENT '' clears it. Do not emit an override unless the customer explicitly requests that change and the target release is confirmed |
| Indexes and dependencies | Check local, unique, prefix, functional, full-text, global, clustered, foreign-key, generated-column, and partition-key dependencies before recommending DDL |
| CCI | Do not propose external columns on a table with CCI; external columns are not an analytics index |
| Read-heavy payloads | Evaluate returned rows/bytes, hot reads, historical cold reads, and latency requirements; frequent body reads are a tradeoff, not an automatic rejection |
| Space and price | Model address/cache/staging/OSS overhead and current pricing; measure actual DN space and billing effects after completion |
When dual pauses first appear in a customer-facing response, introduce them in plain language before showing hint names or commands:
The baseline plan uses ordinary MCE and proceeds directly to completion. Add the two pause hints as an optional controlled-rollout variant when the business wants staged observation and a cancellation window before final cutover.
双暂停让业务在外列变更过程中保留一个“真实流量验证 + 可回退”的窗口:先确认数据回填和双写稳定,再让正常业务流量进入真实外列读取路径,持续观察日常查询的 RT、错误率和兼容性;如果表现不符合预期,可以在最终切换前发起取消,由数据库回滚到原普通列状态,并持续观察任务直到回滚完成。确认稳定后再完成切换,让整个变更过程更可控。
Lead with that purpose, not merely the number or positions of the pause points. Then explain the mechanics: the first pause is before the read cutover; continuing once activates the real external-column read path while writes remain dual; the second pause is the main production-observation and rollback window; continuing again crosses the CDC-marker boundary and removes cancellation. The second pause represents real steady external-column read behavior under business traffic. Because writes still dual-write at this point, do not present it as proof of final steady-state write latency or post-cleanup resource behavior.
Never say that both pauses validate external-column performance. The first pause validates completed backfill/checking and dual-write stability while reads still use the ordinary column. Only the second pause validates the real external-column read path.
Dual-pause behavior, available from the minimum release:
| Boolean hint | Observation boundary |
MCE_PAUSE_BEFORE_READ_CUTOVER=true | Backfill and checking complete; ordinary-column reads and dual writes remain |
MCE_PAUSE_BEFORE_WRITE_CUTOVER=true | Real external-column reads are active; writes remain dual; the CDC marker has not been published |
Both default to false in the implementation. The first CONTINUE DDL advances to the second pause. Continuing from the second pause crosses the CDC-marker boundary and removes the ability to cancel back to the original layout. Before any control action, match the exact job ID, statement, phase, intended pause task, and exception state. Both observation points apply to the same whole-table MCE. See the migration reference for commands and verification.
For customer-facing schema acceptance, show the SHOW CREATE TABLE result captured before MCE and the result captured after completion. Confirm the logical column type, preserved comment, and EXTERNALIZE marker from those two results. Job-state checks and representative business reads/writes remain separate operational and business acceptance steps.
Mandatory dual-pause customer handoff: whenever customer-facing output includes the two pause hints or recommends a dual-pause rollout, include each block below with the verified database and job ID substituted. Keep the actions separate so the customer does not paste them as one batch.
- Before every control action, select the target database and verify that the exact job, statement, phase, intended pause task, and exception state match the plan:
USE `DATABASE_NAME_VALUE`;
SHOW FULL DDL;
SHOW FULL DDL ENGINE STATUS;
SHOW DDL RESULT JOB_ID_VALUE;- After the first pause passes and continuation is authorized, advance that same job to the second pause, then run the observation commands again:
/*+TDDL:CMD_EXTRA(PURE_ASYNC_DDL_MODE=true)*/
CONTINUE DDL JOB_ID_VALUE;- After the second pause passes, obtain a separate final-cutover authorization before using the same continuation command again. State immediately beside the command that it crosses the CDC-marker boundary and removes the ability to cancel back to the original layout:
/*+TDDL:CMD_EXTRA(PURE_ASYNC_DDL_MODE=true)*/
CONTINUE DDL JOB_ID_VALUE;- If either intended pause fails, do not continue. First verify that the job is still before the non-cancelable boundary and supports cancellation in its actual state, then use:
/*+TDDL:CMD_EXTRA(PURE_ASYNC_DDL_MODE=true)*/
CANCEL DDL JOB_ID_VALUE;Command acceptance is not rollback completion. Re-run the job-status queries, SHOW CREATE TABLE, and agreed business/data checks until the rollback outcome is established. Do not describe a generic PAUSED state as safe to cancel.
USE `DATABASE_NAME_VALUE`;
SHOW FULL DDL;
SHOW DDL RESULT JOB_ID_VALUE;
SHOW CREATE TABLE `DATABASE_NAME_VALUE`.`TABLE_NAME_VALUE`;- Explain that recovery after a completed MCE uses a new reverse MCE with its own release, capacity, dependency, and authorization checks. If a recovery plan needs a syntax example, label it as a separate conditional plan:
-- Separate reverse MCE; verify release, DN capacity, dependencies, and authorization first.
ALTER TABLE `DATABASE_NAME_VALUE`.`TABLE_NAME_VALUE`
MODIFY COLUMN `COLUMN_NAME_VALUE` SOURCE_TYPE_VALUE;Best Practices
- Say why the feature may help this customer and what evidence would disprove the fit. Avoid unsolicited repeated sales messages after the customer declines.
- Prefer size aggregates and redacted SQL templates. Do not retrieve payload contents merely to estimate their size; avoid unbounded scans, sorts, and production load tests. Never copy audit literal values such as user IDs, session IDs, primary keys, or payload fragments into a customer plan; use
USER_ID_VALUE,SESSION_ID_VALUE, andROW_ID_VALUE. - Preserve source latency units exactly. When a source does not document the unit, show the raw value and field name with "单位待确认"; never infer seconds, milliseconds, or microseconds from magnitude, and never call wide payloads the direct cause without matching causal evidence.
- Compare the same SQL templates, traffic mix, and time coverage across baseline, both pauses, and final steady state. Include sample counts and collection gaps.
- Treat online migration as resource-consuming work. Pause observations retain migration overhead; define a bounded observation window and stop conditions rather than leaving dual writes indefinitely.
- After completion, recovery uses a new reverse MCE with version, capacity, dependency, and authorization checks.
- Keep the default deliverable technical. Preserve customer-provided ownership or scheduling details when relevant, but generate approval, signature, owner, RACI, scheduling, or responsibility tables only when the customer explicitly requests change-management content.
- Never advertise a fixed savings ratio, guaranteed faster queries, immediate disk reclamation, or immediate bill reduction. Use public case studies as examples with their scope intact.
References
| Reference | Description |
| references/opportunity-discovery.md | Indirect triggers, customer-facing language, negative cases, and solution routing |
| references/evidence-acquisition.md | Capability-first live collection, optional skill routing, evidence contract, and fallback prompt |
| references/assessment.md | Evidence collection, bounded SQL sampling, compatibility checks, and candidate report |
| references/migration-plan.md | New-table and MCE templates, dual-pause gates, rollback boundary, and acceptance |
| 官方介绍:什么是低成本上下文存储(外列) | Read before a substantive customer introduction when live browsing is available; use as public product context, not instance evidence |
| 官方文档:创建和使用外列 | Public product scope, minimum version, syntax, and limitations; verify that the instance meets the minimum release |
| View and upgrade instance versions | Find the customer's actual release and available upgrade path |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

