docs(destination-postgres): fix incorrect config and changelog details, document undocumented settings and limits

[devin-ai-integration]

Triggering Context

Run triggered by: Automated autodoc run on a commit merged to master.

Relevant context: Commit a65bba8 — #75902 (fix(destination-postgres): re-throw COPY errors and sanitize null bytes in raw JSON, released as 3.0.16). This branch already carried an earlier autodoc run's changes for 3.0.15; it was reset to master and rebuilt so both runs land in one PR.

Confidence impact: The trigger is a small, merged bug-fix PR with an unambiguous diff, so scope was clear from the start (Triggering Context 5/5).

Documentation Confidence Assessment

Overall Confidence: 3/5

Dimension	Score	Rationale
Code Comprehension of the Documented Surface	3/5	Java/Kotlin baseline of 2, adjusted up: every documented fact came from the spec fixtures or a single, short Kotlin file I read in full.
API Documentation Quality	4/5	PostgreSQL's official docs are excellent and the connector's own limit constants cite the exact pages they come from.
Change Scope & Risk	3/5	~68 lines changed across config fields, sync modes, naming, value limits, and the changelog.
Existing Doc Maturity	4/5	The page is 390+ lines with full setup, schema, and troubleshooting coverage; the gaps were identifiable rather than structural.
Connector Sensitivity	1/5	destination-postgres is a top-tier certified connector.
Triggering Context	5/5	Triggered from a small merged bug-fix PR.
Inference Ratio	4/5	Nearly all claims trace to connector source or the GitHub API; the changelog wording for 3.0.16 is my paraphrase of the diff.

Adjustments based on code comprehension

• Declarative surface area: upward — the optional-settings table and field titles come from src/test-integration/resources/expected-spec-oss.json and spec/PostgresSpecification.kt, not from imperative code.
• Framework leverage: upward — the connector runs on the Bulk Load CDK; the Postgres-specific path I documented is PostgresValueCoercer, PostgresNamingUtils, PostgresTableSchemaMapper, and PostgresWriter, all small and free of custom dispatch.
• Structural complexity of the documented path: downward — Kotlin with runtime bean wiring (Micronaut) means I could not execute the paths I documented, only read them.

What I Verified vs. What I Inferred

• Verified from code:
  • Type mapping, including union and unknown types resolving to JSONB (schema/PostgresTableSchemaMapper.kt).
  • Identifier shortening — first 54 characters, _, then an 8-character hash — and the special-character/leading-digit rules (schema/PostgresNamingUtils.kt).
  • Null-byte stripping for string values and for the raw JSON blob, and the DESTINATION_FIELD_SIZE_LIMITATION nullification with its exact BIGINT, numeric, 1 GB string, and timestamp bounds (write/transform/PostgresValueCoercer.kt, write/load/PostgresRecordFormatter.kt).
  • Dedup requiring a primary key, and dedup falling back to append in raw-tables-only mode (write/PostgresWriter.kt, PostgresDirectLoadSqlGeneratorTest.kt).
  • Field titles, defaults, and required flags for the config table (spec fixtures and spec/PostgresSpecification.kt).
• Verified from API docs: PostgreSQL's documented 63-character identifier limit, BIGINT/NUMERIC ranges, the 1 GB field size limit, and the 4713 BC–294276 AD timestamp range — all cited directly in the coercer.
• Verified from GitHub: merge timestamps for PRs 75902, 83235, and 82273, and that PR 11514 (not 11729) is the mina-sshd bump referenced by the 0.3.18 row.
• Inferred: the plain-English changelog subject for 3.0.16; that the collision case for two names differing only in replaced special characters surfaces as a Postgres duplicate-name error (the code has no collision pass for it, and the troubleshooting page documents the equivalent truncation collision).

Areas of Concern

• The "Unconstrained numeric columns" row says the setting has no effect. unconstrained_number is parsed into PostgresConfiguration but nothing reads it, and the mapper always emits decimal. If that's an implementation gap rather than an intentional deprecation, the connector — not this doc — is what needs fixing.
• The 9.5 minimum server version in Prerequisites is unchanged and unverifiable from the connector: nothing in the source or tests enforces or checks it.
• The legacy raw-tables note now says raw table and schema names are lowercased and raw column names are untouched. That matches PostgresNamingUtils, but it contradicts the previous "unquoted identifiers" wording, so it's worth a second opinion from someone who remembers the pre-3.0.0 behavior.

---

What

Corrects factual errors on the Postgres destination page and fills the gaps a user hits when a sync fails for a reason the page never mentions: a missing primary key, a mangled column name, or a value silently written as NULL.

How

Corrections

• Changelog dates now match merge dates: 3.0.16 was 2026-03-31 (merged 2026-08-10), 3.0.15 was 2026-08-07 (merged 2026-08-10), 3.0.14 was 2026-07-30 (merged 2026-08-05).
• The 0.3.18 row's link text said #11729 while the URL pointed at 11514. 11514 is the mina-sshd bump the row describes, so the text now matches the URL.
• Default Schema was described as a comma-separated search-path that syncs "all of existing" schemas. That's source-connector behavior. It's a single schema, defaulting to public, used when a stream carries no namespace.
• Database Name no longer claims it defaults to the username.
• The legacy raw-tables note claimed unquoted identifiers; raw table and schema names are lowercased and raw column names are passed through unchanged.
• The sync modes heading linked to /cloud/core-concepts, which no longer exists.

Additions

• An "Optional settings" table covering CDC deletion mode, Airbyte Internal Schema Name, Disable Final Tables, Drop tables with CASCADE, and Unconstrained numeric columns — none of which were documented.
• Deduplication requires a primary key, and raw-tables-only mode silently appends instead of deduping.
• Union and unknown types map to JSONB.
• A "Value limitations" section for null-byte stripping (the behavior this run's connector change extended to raw JSON) and for the out-of-range values written as NULL with a _airbyte_meta entry.

Rewrites

• "Naming limitations" said long names are truncated and "Airbyte may modify these column names to avoid the collision," which understates what happens. It now describes the actual 54-characters-plus-hash scheme and names the collision case the connector does not handle.

Review Guide

• The "Optional settings" table (around line 180) is the largest new claim surface. Every default there came from expected-spec-oss.json, but the descriptions are mine.
• The "Unconstrained numeric columns" row calls the setting a no-op — see Areas of Concern.
• The 3.0.16 changelog subject (line 312) is a rewrite of the auto-generated text, not the original wording.

---

User Impact

Users of the Postgres destination get accurate release dates, a documented list of the optional settings the connector exposes, and an explanation of the cases where the connector changes their data on the way in: null bytes removed, out-of-range values nulled, long names hashed. Documentation only; no connector behavior changes.

Can this PR be safely reverted and rolled back?

• YES 💚
• NO ❌

Note: I am an AI assistant (Devin) and have proposed these documentation updates based on a review of the connector source code and PostgreSQL's documentation. Reviewers may merge, modify, or close this PR as they see fit.

---

Devin session

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• 🛠️ Quick Fixes
  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
    • Bump types: patch (default), minor, major, major_rc, rc, promote.
    • The rc type is a smart default: applies minor_rc if stable, or bumps the RC number if already RC.
    • The promote type strips the RC suffix to finalize a release.
    • Example: /bump-version type=rc or /bump-version type=minor
  • /bump-progressive-rollout-version - Alias for /bump-version type=rc. Bumps with an RC suffix and enables progressive rollout.
• ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
  • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
  • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
  • /ai-review - AI-powered PR review for connector safety and quality gates.
• 📝 AI Documentation:
  • /ai-docs-review - AI-powered documentation review for PRs with connector changes.
  • /ai-create-docs-pr - Creates a documentation PR for connector changes, stacked on the current PR.
• 🚀 Connector Releases:
  • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • /enable-autopilot-rollouts - Enables autopilot progressive rollouts for the modified connector(s) in the PR, remediating "autopilot rollouts not enabled for {connector-name}" auto-merge blockers. Sets defaultRolloutMode: autopilot and enableProgressiveRollout: true, preserving any existing autopilotConfig.
    • Optional args: connector=<CONNECTOR_NAME> (defaults to the modified connectors in the PR), strategy=fast|slow|default (defaults to fast).
    • Example: /enable-autopilot-rollouts or /enable-autopilot-rollouts connector=source-faker strategy=slow
• ☕️ JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
• 🐍 Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
• ⚙️ Admin commands:
  • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
    Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

📝 Edit this welcome message.

[github-actions]

Deploy preview for airbyte-docs ready!

Project:	airbyte-docs
Status:	✅  Deploy successful!
Preview URL:	https://airbyte-docs-nwxqupvfa-airbyte-growth.vercel.app
Latest Commit:	b7324ea

Deployed with vercel-action

[Alexandre Girard (girarda)]

aside - Test comment, please ignore.