Skip to content

docs: add a PL/iSQL overview#1444

Open
Z95-cmyk wants to merge 2 commits into
IvorySQL:masterfrom
Z95-cmyk:docs-plisql-overview
Open

docs: add a PL/iSQL overview#1444
Z95-cmyk wants to merge 2 commits into
IvorySQL:masterfrom
Z95-cmyk:docs-plisql-overview

Conversation

@Z95-cmyk

@Z95-cmyk Z95-cmyk commented Jul 20, 2026

Copy link
Copy Markdown

Summary

  • add PL/iSQL to the server-programming part of the main manual
  • explain Oracle-mode installation, implicit language selection, program-unit structure, and the psql slash terminator
  • summarize supported declarations, control flow, SQL execution, cursors, exceptions, nested routines, and packages
  • document package session state, connection-pool resets, definer rights, transaction-control restrictions, autonomous units, and migration guidance

Fixes #1434

Verification

  • make -C doc/src/sgml check
  • make -C doc/src/sgml html
  • git diff --check

The SGML and HTML checks were run in an out-of-tree cumulative documentation build containing this change and the other independently proposed documentation additions.

AI assistance disclosure

This contribution was prepared with OpenAI Codex using GPT-5. The agent assisted with source and test inspection, issue scoping, drafting code, documentation and tests where applicable, running verification, and preparing the PR description. I directed the scope, reviewed the resulting changes against the source and test results, and remain responsible for the submission.

Summary by CodeRabbit

  • Documentation
    • Added a new PL/iSQL documentation chapter covering syntax, compatibility setup, supported features, packages, security, transactions, and migration guidance.
    • Added PL/iSQL to the server programming documentation index.

Assisted-by: OpenAI:gpt-5
@coderabbitai

coderabbitai Bot commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 63278e1d-15a2-465a-a1c7-0906af947382

📥 Commits

Reviewing files that changed from the base of the PR and between 15d3b5b and a7d2e9c.

📒 Files selected for processing (3)
  • doc/src/sgml/filelist.sgml
  • doc/src/sgml/plisql.sgml
  • doc/src/sgml/postgres.sgml

📝 Walkthrough

Walkthrough

Adds a PL/iSQL documentation chapter covering setup, syntax, features, packages, security, transactions, and migration guidance, then registers and includes the chapter in the SGML manual.

Changes

PL/iSQL documentation

Layer / File(s) Summary
PL/iSQL foundations
doc/src/sgml/plisql.sgml
Documents Oracle-compatible setup, program units, block syntax, submission behavior, examples, and supported PL/iSQL facilities.
Packages, security, and migration
doc/src/sgml/plisql.sgml
Describes package state, security rights, transaction restrictions, autonomous transactions, and migration validation guidance.
Manual integration
doc/src/sgml/filelist.sgml, doc/src/sgml/postgres.sgml
Registers plisql.sgml as an SGML entity and includes it in the Server Programming section.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly states the main change: adding a PL/iSQL overview to the docs.
Linked Issues check ✅ Passed The new chapter covers Oracle-mode availability, program units, package state, rights, transaction rules, client terminators, and migration guidance.
Out of Scope Changes check ✅ Passed The changes stay within PL/iSQL documentation and manual wiring, with no unrelated code or content added.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@Z95-cmyk
Z95-cmyk marked this pull request as ready for review July 20, 2026 04:47
@hanjianqiao

Copy link
Copy Markdown
Collaborator

Thanks for your work! Before we merge, though, I noticed a few errors in the documentation. It reads like it was largely AI-generated, so I'd strongly encourage you to write it yourself — that usually makes the docs more accurate and easier to maintain.

@Z95-cmyk

Copy link
Copy Markdown
Author

Thank you for flagging this. AI assistance is now explicitly disclosed in the PR description, and I reworked the chapter in commit a7d2e9c56802decbac7f5382499bdc4406ea2585 based on a source-and-regression-test audit rather than relying on generated prose.

The corrections include:

  • describing PL/iSQL as derived from PL/pgSQL, rather than calling PL/pgSQL its execution environment
  • documenting that ivorysql.database_mode is fixed at cluster initialization and that Oracle mode is required
  • adding the ivorysql_ora extension and shared_preload_libraries prerequisites for Oracle compatibility objects such as NUMBER and dual
  • correcting array compatibility wording
  • removing the unsupported claim about compiling invalid objects
  • tightening package invalidation wording
  • correcting autonomous-routine behavior: the current implementation uses a separate dblink connection, successful completion commits independently, and explicit COMMIT/ROLLBACK inside the autonomous body is unsupported

I checked these points against the relevant initialization, GUC, extension, PL/iSQL autonomous-routine source, and regression tests. The full SGML check html build passes. If you had other specific errors in mind, please point them out and I will address them directly.

@hanjianqiao

Copy link
Copy Markdown
Collaborator

Thank you again for your contribution. We noticed you've submitted multiple documentation PRs. Since IvorySQL's documentation is managed in the ivorysql_docs repository, we're currently discussing how best to handle the documentation you've submitted. We'll reach out to you once we've reached a decision.

@hs-liuxh

Copy link
Copy Markdown
Collaborator

Thanks for you work. Please refer to the previous comments.

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.

Documentation: add a PL/iSQL overview

3 participants