Skip to content

docs(faq): answer the twelve IvorySQL-specific questions users hit first - #397

Open
qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/faq-common-pitfalls
Open

qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/faq-common-pitfalls

Conversation

@qwer381

@qwer381 qwer381 commented Nov 12, 2026 •

Copy link
Copy Markdown

Closes #393

What changed

master/contribution/faq.adoc, Chinese and English: twelve === Q&A entries appended to the existing page. +335 lines per language, zero deletions — the current content is untouched, and the section order matches between CN and EN.

The twelve questions were picked from behaviours that are specific to IvorySQL and that are not described anywhere in master/ today:

# Question What the answer pins down
1 Oracle mode vs PG mode initdb -m decides the stored mode; -m pg is the default in the TAP fixtures
2 1521 vs 5432 one postmaster, two listeners, one data directory
3 compatible_mode flips per port the mode follows the listener, not the database or the session
4 replication clusters ivorysql.port must be set on each node
5 sync_state FIRST 1 (…) → sync, ANY 1 (*) → quorum
6 writes hang after pg_promote() commits wait in wait_event = SyncRep; statement_timeout does not break it; clear synchronous_standby_names and reload
7 initdb fails: extension "uuid-ossp" is not available the extension must be installed where the server runs
8 make fails: #error "please use configure's --with-uuid switch …" --with-uuid=e2fs/bsd/ossp is required for contrib/uuid-ossp
9 TAP fixtures they always initdb -m pg, so Oracle-only objects are not exercised
10 container exits at start IVORYSQL_PASSWORD is mandatory unless POSTGRES_HOST_AUTH_METHOD=trust
11 port 5866 in the image initialisation-time temporary port, not a service
12 ivorysql.conf.sample documents 4 of the 15 ivorysql.* parameters

How it was verified

Every command, error message and value quoted in the answers was reproduced on PostgreSQL 18.6 (IvorySQL 5.6) in this environment — two-node synchronous replication for #5/#6, initdb and make runs for #7/#8, the ivorysql/ivorysql:5.6-ubi8 container for #10/#11, and the installed initdb/postgres binaries for #1–#4. The transcripts were kept as evidence; nothing is quoted from another project or from memory.

Rendering: both pages convert with asciidoctor.js 4.2.1 with zero warnings (CN: 1 h1 / 7 h2 / 12 h3 / 5 tables / 29 literal blocks; EN has the same skeleton).

Checklist

  • CLA signed and on file (individual CLA emailed to cla@ivorysql.org on 2026-11-10)
  • Only contribution/faq.adoc (CN + EN) touched, no nav.adoc change
  • Bilingual: all twelve answers exist in both languages, in the same order
  • No deletions

The FAQ page answers general questions, but none of the behaviours that are
specific to IvorySQL's two serving modes: which port gives which mode, what
synchronous replication does to sync_state, why commits hang after
pg_promote(), why initdb and make fail when uuid-ossp is missing, and what
the container image requires at startup.

Add 12 Q&A entries to both the Chinese and the English page. Every number,
error message and GUC value quoted here was reproduced on PostgreSQL 18.6
(IvorySQL 5.6) in this environment; nothing is copied from other projects.

No existing content is removed.

Closes IvorySQL#393
@github-actions
github-actions Bot temporarily deployed to pull request November 12, 2026 15:13 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@qwer381

qwer381 commented Nov 12, 2026

Copy link
Copy Markdown
Author

Note for reviewers: an identical pull request from the same patch (#398) was opened in the same second by a duplicate automation run. It has been closed, so this is the only thread to review.

@qwer381
qwer381 force-pushed the docs/faq-common-pitfalls branch from a21dcdb to 3ee1b96 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 — 3ee1b96c 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.

1 participant