Skip to content

Document subordinate backends in the administration guide - #1302

Merged
vharseko merged 2 commits into
OpenIdentityPlatform:masterfrom
vharseko:docs/subordinate-backends
Nov 18, 2026
Merged

vharseko merged 2 commits into
OpenIdentityPlatform:masterfrom
vharseko:docs/subordinate-backends

Conversation

@vharseko

@vharseko vharseko commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Document how subordinate backends divide a directory tree, when to use them, and how to create a backend or plan an existing branch migration. Cover search, replication, backup, indexing, and availability considerations.

Use a local example with an LDIF parent, two persistent PDB child backends, and a disposable Memory child backend. Update the existing LDIF and Memory chapters to describe supported local backends instead of presenting a proxy backend as available. Preserve the former LDIF section anchor for existing links.

Validation:

  • The documentation xref checker verified 12 file references in the subordinate-backends chapter.
  • Asciidoctor rendered both the old and new LDIF section anchors.
  • git diff --check passed.
  • A full xref check of all three chapters was not completed: the ungenerated source tree lacks the generated dsconfig reference partial.

@vharseko
vharseko requested a review from maximthomas November 17, 2026 12:23
@vharseko vharseko added docs backend Storage backends (JE, PDB, memory) and their database behaviour labels Nov 17, 2026

@maximthomas maximthomas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

praise: The chapter clearly distinguishes creating an empty subordinate backend from migrating an existing branch.

  • subordinate-backends-create explains that registering a base DN does not populate the backend.
  • subordinate-backends-migrate warns that registration does not move existing data and requires separate parent and child datasets.

issue (blocking): The chapter presents subordinate proxy backends as an available use case, but this revision ships no configurable directory-server proxy backend.

opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-subordinate-backends.adoc:41, :83, :88, :90

Normal backend startup and creation reach BackendConfigManager.registerBackend(), which accepts only LocalBackend implementations and otherwise throws RuntimeException("registerBackend() is not yet supported for proxy backend."). The configuration test explicitly records that the proxy backend is absent from this codebase; the standalone SDK proxy example is not a directory-server backend. Although custom LocalBackend implementations are possible, the documented topology cannot be configured using the shipped backends. Please remove the proxy-specific recommendation and operational references, including the concluding link, or identify the separate implementation required and state that it is not included in this server.

@vharseko

Copy link
Copy Markdown
Member Author

Addressed in 4ec5924. The subordinate-backends chapter now uses an LDIF parent with two PDB children and one disposable Memory child, and its operational guidance no longer presents proxy backends as available.

I also replaced the proxy example in the existing LDIF chapter and removed the corresponding proxy references from the Memory chapter. The former LDIF section anchor remains available for existing links.

Validation: the xref checker verified 12 file references in the subordinate-backends chapter, Asciidoctor rendered both LDIF section anchors, and git diff --check passed. The full three-chapter xref check could not run against the ungenerated source tree because the generated dsconfig reference partial is missing.

@vharseko
vharseko requested a review from maximthomas November 17, 2026 13:43

@maximthomas maximthomas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

praise: The LDIF/PDB/Memory example separates persistent and disposable data, explains migration hazards, and preserves the former LDIF section anchor.

@vharseko
vharseko merged commit 795e8ce into OpenIdentityPlatform:master Nov 18, 2026
43 of 45 checks passed
@vharseko
vharseko deleted the docs/subordinate-backends branch November 18, 2026 06:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend Storage backends (JE, PDB, memory) and their database behaviour docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants