Skip to content

docs(best_practices): add a production readiness checklist - #390

Open
qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/production-checklist
Open

qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/production-checklist

Conversation

@qwer381

@qwer381 qwer381 commented Nov 11, 2026 •

Copy link
Copy Markdown

Closes #386

What this changes

New page CN|EN/modules/ROOT/pages/master/best_practices/production_checklist.adoc (237 lines each) plus one nav.adoc line per language, inserted after the operation guide entry:

  • CN nav.adoc: after ** xref:master/operation_guide.adoc[运维管理指南]
  • EN nav.adoc: after ** xref:master/operation_guide.adoc[Operation Management]

1. == 上线检查清单 / == Production readiness checklist

One |=== table with 18 data rows, each carrying check item / command / expected result / impact when it fails: version and build options, ivorysql.compatible_mode on both listeners, ivorysql.database_mode, ivorysql.port and listen_addresses, identifier_case_switch, enable_emptystring_to_NULL, pg_hba.conf trust rules, extension availability on both listeners, template1 inheritance, wal_level/archive_mode, and the two-port reachability check.

2. == 兼容性最佳实践案例 / == Compatibility cases

Three worked cases, each with the scenario, the SQL to reproduce it, the measured output, and the recommendation:

  • Dual listeners, two modes. 1521 → oracle, 5432 → pg, while ivorysql.port, ivorysql.database_mode and listen_addresses are identical on both; compatible_mode is the only thing that tells you which semantics a session is getting.
  • identifier_case_switch. ABC|abc|mixed / abc|ABC|mixed / abc|abc|mixed for the same query under the three values, with the plan and row count unchanged — a column-name comparison is what breaks, not the data.
  • Empty string → NULL. The UNIQUE index is bypassed (INSERT 0 1 twice, total_rows = 3 null_rows = 3), NOT NULL rejects '', statistics show null_frac = 1 n_distinct = 0; with the parameter off the second insert fails with duplicate key.

How it was verified

Every command and output in both pages comes from a real run on IvorySQL 5.6 over both listeners; the raw psql transcripts were kept as evidence, and the page states which values came from the sample cluster (for example the six trust rules in pg_hba_file_rules) rather than presenting them as universal.

Deliberately not written, because this batch did not measure them: the purpose of 5866/tcp, the container's default initdb mode, a full promotion replay, NULLS NOT DISTINCT DDL, and the clean-install success path for uuid-ossp. Reviewers asking for those should get a measured answer, not an invented one.

Rendering: both languages convert with asciidoctor.js 4.2.1, zero warnings, CN and EN are line-for-line symmetric (237 lines each), no empty table cells.

Checklist

  • CLA signed and on file (individual CLA emailed to cla@ivorysql.org on 2026-11-10)
  • nav.adoc change is a single inserted line per language
  • Facts are reproducible from the commands shown; nothing is pasted from a different version

There is no pre-flight material anywhere in the docs: the word for
checklist does not appear on any page, and backup/PITR are covered by the
operation guide while the pre-deployment checks are not covered at all.

Add master/best_practices/production_checklist.adoc in CN and EN, plus one
navigation entry per language:

- an 18-row checklist: item, command, expected result, and the impact of
  failing it, covering version and build options, both listeners, hba
  rules, extension availability on both listeners, template1 inheritance,
  wal_level and archiving;
- three worked compatibility cases: one database answering with
  compatible_mode=pg on 5432 and oracle on 1521 while every other
  ivorysql.* parameter is identical; identifier_case_switch changing only
  the quoted column names, not the plan or the row count; and
  enable_emptystring_to_NULL turning '' into NULL so that a UNIQUE index
  stops rejecting duplicates while NOT NULL starts rejecting ''.

Every command and output on the page comes from a real 5.6 run. The
material that would have required another kind of instance (promotion
replay, NULLS NOT DISTINCT, container specifics) is left out rather than
invented.
@github-actions
github-actions Bot temporarily deployed to pull request November 11, 2026 16:46 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@qwer381

qwer381 commented Nov 12, 2026 •

Copy link
Copy Markdown
Author

CI is green and the rendered result has been verified on the deploy preview.

  • build-and-deploy: success (job completed), mergeStateStatus=clean, base master @ 7d4ad9d.
  • Preview check (both languages, HTTP 200): /cn/ivorysql-doc/master/best_practices/production_checklist.html and /en/ivorysql-doc/master/best_practices/production_checklist.html.
  • Rendered content matches the patch: the new page (go-live checklist + three compatibility cases); no {asterisk} leftovers and no nested-markup artifacts.
  • nav position was verified against the live sidebar order, not just the diff.

Nothing else is pending on my side -- happy to adjust wording or split anything if you prefer a different shape for this section.

@qwer381
qwer381 force-pushed the docs/production-checklist branch from 9304baa to 5f00aae Compare November 13, 2026 05:53
@github-actions
github-actions Bot temporarily deployed to pull request November 13, 2026 05:56 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

This branch was previously deployed

1 inactive deployment
pull request — 5f00aae5 Deployed Nov 13, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants