[DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation
Hi
I have made some documentation enhancements for PL/pgSQL and PL/Python
sections. The changes include the addition of a Quick Start Guide to
facilitate a smoother onboarding experience for users.
Patch File Name:
0001-plpyhton-plpgsql-docu-changes.patch
Patch Description:
This patch introduces a Quick Start Guide to the documentation for PL/pgSQL
and PL/Python. The Quick Start Guide provides users with a step-by-step
walkthrough of setting up and using these procedural languages. The goal is
to improve user accessibility and streamline the learning process.
Changes Made:
1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and
PL/Python documentation.
2. Included step-by-step instructions for users to get started with these
procedural languages.
3. Provided explanations, code snippets, and examples to illustrate key
concepts.
Discussion Points:
I am seeking your feedback on the following aspects:
- Clarity and completeness of the Quick Start Guide
- Any additional information or examples that could enhance the guide
- Suggestions for improving the overall documentation structure
Your insights and suggestions are highly valuable, and I appreciate your
time in reviewing this documentation enhancement.
--
Best regards,
Ishaan Adarsh
Attachments:
0001-plpyhton-plpgsql-docu-changes.patchapplication/octet-stream; name=0001-plpyhton-plpgsql-docu-changes.patchDownload
From f896904feb254ca0866b58ed7261d5bf4498815a Mon Sep 17 00:00:00 2001
From: Ishaan Adarsh <ishaanad9@gmail.com>
Date: Sat, 16 Dec 2023 15:45:20 +0530
Subject: [PATCH] plpyhton-plpgsql-docu-changes
---
doc/src/sgml/plpgsql.sgml | 191 +
doc/src/sgml/plpython.sgml | 181 +
2 files changed, 372 insertions(+)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 5977534a62..8522415c44 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -6105,4 +6105,195 @@ $$ LANGUAGE plpgsql STRICT IMMUTABLE;
</sect1>
+ <sect1 id="plpgsql-quickstart">
+ <title>Quick Start: Creating a PostgreSQL Extension using PL/pgSQL</title>
+
+ <para>
+ In this quick start guide, we will create a simple PostgreSQL extension using PL/pgSQL.
+ </para>
+
+ <sect2 id="plpgsql-prerequisites">
+ <title>Prerequisites</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="https://www.postgresql.org/download/">PostgreSQL</ulink> installed and running on your system.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Basic knowledge of SQL and <literal>PL/pgSQL</literal> programming.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>make</literal> utility for building and compiling software.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Knowledge about the Postgres Development Libraries.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="plpgsql-step1">
+ <title>Create the Extension Directory</title>
+
+ <para>
+ Create a new directory for your extension project.
+ </para>
+
+ <screen>
+ $ mkdir ~/pg_plpgsql_ext
+ $ cd ~/pg_plpgsql_ext
+ </screen>
+ </sect2>
+
+ <sect2 id="plpgsql-step2">
+ <title>Create the SQL Script File</title>
+
+ <para>
+ Create a file named <filename>pg_plpgsql_ext--1.0.0.sql</filename> in the <filename>pg_plpgsql_ext</filename> directory with the following content:
+ </para>
+
+ <screen>
+ -- pg_plpgsql_ext--1.0.0.sql
+ -- Create the function that uses PL/pgSQL
+ CREATE OR REPLACE FUNCTION subtract_numbers(a integer, b integer)
+ RETURNS integer
+ LANGUAGE plpgsql
+ AS $$
+ BEGIN
+ RETURN a - b;
+ END;
+ $$;
+ </screen>
+
+ <para>
+ Explanation of the SQL Script:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>CREATE OR REPLACE FUNCTION subtract_numbers(a integer, b integer) RETURNS integer LANGUAGE plpgsql AS $$</literal>:
+ This statement creates the function <literal>subtract_numbers</literal> with two integer arguments (<literal>a</literal> and <literal>b</literal>). The function will return an integer. The <literal>LANGUAGE plpgsql</literal> specifies that the function is written in PL/pgSQL.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>BEGIN</literal>:
+ This is the beginning of the PL/pgSQL code block.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>RETURN a - b;</literal>:
+ This line calculates the subtraction of <literal>b</literal> from <literal>a</literal> and returns the result.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2 id="plpgsql-step3">
+ <title>Create the Control File</title>
+
+ <para>
+ Create a file named <filename>pg_plpgsql_ext.control</filename> in the <filename>pg_plpgsql_ext</filename> directory with the following content:
+ </para>
+
+ <screen>
+ # pg_plpgsql_ext.control
+
+ # Extension name
+ comment = 'A simple PostgreSQL extension using PL/pgSQL.'
+
+ # Default version of the extension
+ default_version = '1.0.0'
+
+ # Extension is relocatable
+ relocatable = true
+ </screen>
+ </sect2>
+
+ <sect2 id="plpgsql-step4">
+ <title>Create the Makefile</title>
+
+ <para>
+ Create a Makefile in the <filename>pg_plpgsql_ext</filename> directory with the following content:
+ </para>
+
+ <screen>
+ # Makefile for pg_plpgsql_ext
+ EXTENSION = pg_plpgsql_ext
+ DATA = pg_plpgsql_ext--1.0.0.sql
+
+ PG_CONFIG = pg_config
+ PGXS := $(shell $(PG_CONFIG) --pgxs)
+ include $(PGXS)
+ </screen>
+ </sect2>
+
+ <sect2 id="plpgsql-step5">
+ <title>Build and Install the Extension</title>
+
+ <para>
+ Let's build and install the <filename>pg_plpgsql_ext</filename> extension:
+ </para>
+
+ <screen>
+ # Build the extension
+ $ make
+
+ # Install the extension
+ $ make install
+ </screen>
+
+ <para>
+ For more information on the installation procedures, you can refer to the <xref linkend="install-make"/>
+ </para>
+ </sect2>
+
+ <sect2 id="plpgsql-step6">
+ <title>Enable the Extension in PostgreSQL</title>
+
+ <para>
+ Connect to your PostgreSQL database using <literal>psql</literal>:
+ </para>
+
+ <screen>
+ $ psql -U your_username -d your_database
+ </screen>
+
+ <para>
+ Inside the PostgreSQL interactive terminal, enable the extension:
+ </para>
+
+ <screen>
+ CREATE EXTENSION pg_plpgsql_ext;
+ </screen>
+
+ <para>
+ For more information on the <literal>CREATE EXTENSION</literal> command, you can refer to the PostgreSQL documentation on <xref linkend="sql-createextension"/>.
+ </para>
+ </sect2>
+
+ <sect2 id="plpgsql-step7">
+ <title>Test the Extension</title>
+
+ <screen>
+ -- Example usage of the function
+ SELECT subtract_numbers(10, 5);
+
+ -- Output:
+ subtract_numbers
+ -----------------
+ 5
+ (1 row)
+ </screen>
+ </sect2>
+</sect1>
+
</chapter>
diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index e05e607aba..2590fff14c 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1394,4 +1394,185 @@ plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % (
command-line interpreter and not an embedded Python interpreter.)
</para>
</sect1>
+
+
+ <sect1 id="plpython-quickstart">
+ <title>Quick Start: Creating a PostgreSQL Extension using PL/Python</title>
+
+ <para>
+ In this quick start guide, we will create a simple PostgreSQL extension using PL/Python.
+ </para>
+
+ <sect2 id="plpython-prerequisites">
+ <title>Prerequisites</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="https://www.postgresql.org/download/">PostgreSQL</ulink> installed and running on your system.</para>
+ </listitem>
+ <listitem>
+ <para> <literal>plpython3u </literal> procedural language available in your PostgreSQL installation.</para>
+ </listitem>
+ <listitem>
+ <para>Basic knowledge of <ulink url="https://www.python.org">Python</ulink> programming.</para>
+ </listitem>
+ <listitem>
+ <para><literal>make</literal> utility for building and compiling software.</para>
+ </listitem>
+ <listitem>
+ <para>Knowledge about the Postgres Development Libraries.</para>
+ </listitem>
+ </itemizedlist>
+
+ </sect2>
+
+ <sect2 id="plpython-step1">
+ <title>Create the Extension Directory</title>
+
+ <para>
+ Create a new directory for your extension project.
+ </para>
+
+ <screen>
+ $ mkdir ~/pg_py_ext
+ $ cd ~/pg_py_ext
+ </screen>
+ </sect2>
+
+ <sect2 id="plpython-step2">
+ <title>Create the SQL Script File</title>
+
+ <para>
+ Create a file named <filename>pg_py_ext--1.0.0.sql</filename> in the <filename>pg_py_ext</filename> directory with the following content:
+ </para>
+
+ <screen>
+ -- pg_py_ext--1.0.0.sql
+ -- Create the function that uses the Python script
+ CREATE OR REPLACE FUNCTION add_numbers(a integer, b integer)
+ RETURNS integer
+ LANGUAGE plpython3u
+ AS $$
+ def add_numbers(a, b):
+ return a + b
+ return add_numbers(int(a), int(b))
+ $$;
+ </screen>
+<para>
+ Explanation of the SQL Script:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>CREATE OR REPLACE FUNCTION add_numbers(a integer, b integer) RETURNS integer LANGUAGE plpython3u AS $$</literal>:
+ This statement creates the function <literal>add_numbers</literal> with two integer arguments (<literal>a</literal> and <literal>b</literal>). The function will return an integer. The <literal>LANGUAGE plpython3u</literal> specifies that the function is written in PL/Python3U.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>def add_numbers(a, b):</literal>:
+ This is the Python code block that defines the <literal>add_numbers</literal> function. The function takes two arguments (<literal>a</literal> and <literal>b</literal>) and returns their sum.
+ </para>
+ </listitem>
+ </itemizedlist>
+</para>
+ </sect2>
+
+ <sect2 id="plpython-step3">
+ <title>Create the Control File</title>
+
+ <para>
+ Create a file named <filename>pg_py_ext.control</filename> with the following content:
+ </para>
+
+ <screen>
+ # pg_py_ext.control
+
+ # Extension name
+ comment = 'A simple PostgreSQL extension using PL/Python3U.'
+
+ # Default version of the extension
+ default_version = '1.0.0'
+
+ # Extension is relocatable
+ relocatable = true
+ </screen>
+ </sect2>
+
+ <sect2 id="plpython-step4">
+ <title>Create the Makefile</title>
+
+ <para>
+ Create a file named <filename>Makefile</filename> in the <filename>pg_py_ext</filename> directory with the following content:
+ </para>
+
+ <screen>
+ # Makefile for pg_py_ext
+ EXTENSION = pg_py_ext
+ DATA = pg_py_ext--1.0.0.sql
+
+ PG_CONFIG = pg_config
+ PGXS := $(shell $(PG_CONFIG) --pgxs)
+ include $(PGXS)
+ </screen>
+ </sect2>
+
+ <sect2 id="plpython-step5">
+ <title>Build and Install the Extension</title>
+
+ <para>
+ Let's build and install the <filename>pg_py_ext</filename> extension:
+ </para>
+
+ <screen>
+ # Build the extension
+ $ make
+
+ # Install the extension
+ $ make install
+ </screen>
+
+ <para>
+ For more information on the installation procedures, you can refer to the <xref linkend="install-make"/>
+ </para>
+ </sect2>
+
+ <sect2 id="plpython-step6">
+ <title>Enable the Extension in PostgreSQL</title>
+
+ <para>
+ Connect to your PostgreSQL database using <literal>psql</literal>:
+ </para>
+
+ <screen>
+ $ psql -U your_username -d your_database
+ </screen>
+
+ <para>
+ Inside the PostgreSQL interactive terminal, enable the extension:
+ </para>
+
+ <screen>
+ CREATE EXTENSION pg_py_ext;
+ </screen>
+
+ <para>
+ For more information on the <literal>CREATE EXTENSION</literal> command, you can refer to the PostgreSQL documentation on <xref linkend="sql-createextension"/>.
+ </para>
+ </sect2>
+
+ <sect2 id="plpython-step7">
+ <title>Test the Extension</title>
+
+ <screen>
+ -- Example usage of the function
+ SELECT add_numbers(3, 5);
+
+ -- Output:
+ add_numbers
+ -------------
+ 8
+ (1 row)
+ </screen>
+ </sect2>
+ </sect1>
</chapter>
On Sat, Dec 16, 2023, at 7:49 AM, Ishaan Adarsh wrote:
I have made some documentation enhancements for PL/pgSQL and PL/Python sections. The changes include the addition of a Quick Start Guide to facilitate a smoother onboarding experience for users.
Great! Add your patch to the next CF [1]https://commitfest.postgresql.org/46/ so we don't miss it.
[1]: https://commitfest.postgresql.org/46/
--
Euler Taveira
EDB https://www.enterprisedb.com/
On Sat, 16 Dec 2023 at 18:49, Ishaan Adarsh <ishaanad9@gmail.com> wrote:
Hi
I have made some documentation enhancements for PL/pgSQL and PL/Python
sections. The changes include the addition of a Quick Start Guide to
facilitate a smoother onboarding experience for users.Patch File Name:
0001-plpyhton-plpgsql-docu-changes.patchPatch Description:
This patch introduces a Quick Start Guide to the documentation for PL/pgSQL
and PL/Python. The Quick Start Guide provides users with a step-by-step
walkthrough of setting up and using these procedural languages. The goal is
to improve user accessibility and streamline the learning process.Changes Made:
1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and
PL/Python documentation.
2. Included step-by-step instructions for users to get started with these
procedural languages.
3. Provided explanations, code snippets, and examples to illustrate key
concepts.Discussion Points:
I am seeking your feedback on the following aspects:
- Clarity and completeness of the Quick Start Guide
- Any additional information or examples that could enhance the guide
- Suggestions for improving the overall documentation structureYour insights and suggestions are highly valuable, and I appreciate your
time in reviewing this documentation enhancement.
1.
It seems you miss <filename> tag in plpgsql "Create the Makefile":
+ <sect2 id="plpgsql-step4">
+ <title>Create the Makefile</title>
+
+ <para>
+ Create a Makefile in the <filename>pg_plpgsql_ext</filename> directory with the following content:
+ </para>2.
We expected use CREATE EXTENSION to load the extension, should we add the
following in extension--version.sql?
-- complain if script is sourced in psql, rather than via CREATE EXTENSION
\echo Use "CREATE EXTENSION pair" to load this file. \quit
--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.
I've addressed the points you raised:
1. *Missing `<filename>` Tag:*
I reviewed the "Create the Makefile" section, and it seems that <filename>
tags are appropriately used for filenames. If there's a specific instance
where you observed a missing tag, please provide more details, and I'll
ensure it's addressed.
2. *Use `CREATE EXTENSION` in "extension--version.sql":*
Considering that there's already a CREATE EXTENSION step in the quick
start guide, I can include a note in the general documentation to explain
the rationale without repeating it in the individual script. What do you
think?
--
Best regards,
Ishaan Adarsh
On Tue, Dec 19, 2023 at 12:28 PM Japin Li <japinli@hotmail.com> wrote:
Show quoted text
1.
It seems you miss <filename> tag in plpgsql "Create the Makefile":+ <sect2 id="plpgsql-step4"> + <title>Create the Makefile</title> + + <para> + Create a Makefile in the <filename>pg_plpgsql_ext</filename> directory with the following content: + </para>2.
We expected use CREATE EXTENSION to load the extension, should we add the
following in extension--version.sql?-- complain if script is sourced in psql, rather than via CREATE EXTENSION
\echo Use "CREATE EXTENSION pair" to load this file. \quit--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.
On Tue, 19 Dec 2023 at 17:57, Ishaan Adarsh <ishaanad9@gmail.com> wrote:
I've addressed the points you raised:
1. *Missing `<filename>` Tag:*
I reviewed the "Create the Makefile" section, and it seems that <filename>
tags are appropriately used for filenames. If there's a specific instance
where you observed a missing tag, please provide more details, and I'll
ensure it's addressed.
Thanks.
2. *Use `CREATE EXTENSION` in "extension--version.sql":*
Considering that there's already a CREATE EXTENSION step in the quick
start guide, I can include a note in the general documentation to explain
the rationale without repeating it in the individual script. What do you
think?
Agreed.
--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.
On 16.12.23 11:49, Ishaan Adarsh wrote:
1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and
PL/Python documentation.
2. Included step-by-step instructions for users to get started with
these procedural languages.
3. Provided explanations, code snippets, and examples to illustrate key
concepts.
The way I read it, that's not really what your patch does. Your patch
explains how to write an extension in PL/pgSQL and PL/Python,
respectively. Which is okay, I guess, but a bit unusual. But I
wouldn't call that an unqualified "quick start" in the respective
languages. Also, it seems to repeat the very basics of setting up an
extension file structure etc. repeatedly in each chapter.
The existing documentation has "explanations, code snippets, and
examples". Are they not good? Do you have more? Better ones? Why are
yours separate from the existing ones?
I think it would be useful to take a step back here and define the
purpose of a bit clearer.
Subject: Clarification on the Purpose of the Patch
Hi Peter,
The intention was to address the challenge faced by newcomers in
understanding how to write an extension for PostgreSQL. The existing
documentation, while comprehensive, lacks a consolidated and easy-to-follow
tutorial that serves as a quick start guide. The goal was to create a
beginner-friendly resource that assumes only knowledge of Postgres and the
target language, making it accessible for new contributors because the
barrier for entry is prohibitive for new contributors. There are various
third-party blog posts focusing on different areas, and sometimes
contradictory.
Specifically:
1. The new section titled "Quick Start Guide" aims to provide step-by-step
instructions for users to get started with writing extensions in PL/pgSQL
and PL/Python.
2. Explanations, code snippets, and examples were included to illustrate
key concepts, making it easier for users to follow along.
I understand your point about the basics of setting up an extension file
structure being repeated. The intention was to provide a self-contained
guide within each language's documentation, ensuring that users who
directly access a specific language's documentation get a complete guide
without having to navigate between sections.
If there are areas where the existing documentation is already sufficient
or if there are ways to improve the approach, I am open to suggestions. The
primary aim is to enhance the accessibility of extension development
information for newcomers.
--
Best regards,
Ishaan Adarsh
On Tue, Dec 19, 2023 at 9:18 PM Peter Eisentraut <peter@eisentraut.org>
wrote:
Show quoted text
On 16.12.23 11:49, Ishaan Adarsh wrote:
1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and
PL/Python documentation.
2. Included step-by-step instructions for users to get started with
these procedural languages.
3. Provided explanations, code snippets, and examples to illustrate key
concepts.The way I read it, that's not really what your patch does. Your patch
explains how to write an extension in PL/pgSQL and PL/Python,
respectively. Which is okay, I guess, but a bit unusual. But I
wouldn't call that an unqualified "quick start" in the respective
languages. Also, it seems to repeat the very basics of setting up an
extension file structure etc. repeatedly in each chapter.The existing documentation has "explanations, code snippets, and
examples". Are they not good? Do you have more? Better ones? Why are
yours separate from the existing ones?I think it would be useful to take a step back here and define the
purpose of a bit clearer.
On 19.12.23 17:26, Ishaan Adarsh wrote:
Subject: Clarification on the Purpose of the Patch
Hi Peter,
The intention was to address the challenge faced by newcomers in
understanding how to write an extension for PostgreSQL. The existing
documentation, while comprehensive, lacks a consolidated and
easy-to-follow tutorial that serves as a quick start guide. The goal was
to create a beginner-friendly resource that assumes only knowledge of
Postgres and the target language, making it accessible for new
contributors because the barrier for entry is prohibitive for new
contributors. There are various third-party blog posts focusing on
different areas, and sometimes contradictory.
Have you seen this:
https://www.postgresql.org/docs/devel/extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE
Maybe that could be extended/modified/simplified?
Specifically:
1. The new section titled "Quick Start Guide" aims to provide
step-by-step instructions for users to get started with writing
extensions in PL/pgSQL and PL/Python.
What's confusing here is writing an extension in a PL language is not a
normal use case I'd say. The normal use case involves some C code.
Hi
čt 21. 12. 2023 v 11:18 odesílatel Peter Eisentraut <peter@eisentraut.org>
napsal:
On 19.12.23 17:26, Ishaan Adarsh wrote:
Subject: Clarification on the Purpose of the Patch
Hi Peter,
The intention was to address the challenge faced by newcomers in
understanding how to write an extension for PostgreSQL. The existing
documentation, while comprehensive, lacks a consolidated and
easy-to-follow tutorial that serves as a quick start guide. The goal was
to create a beginner-friendly resource that assumes only knowledge of
Postgres and the target language, making it accessible for new
contributors because the barrier for entry is prohibitive for new
contributors. There are various third-party blog posts focusing on
different areas, and sometimes contradictory.Have you seen this:
https://www.postgresql.org/docs/devel/extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE
Maybe that could be extended/modified/simplified?
Specifically:
1. The new section titled "Quick Start Guide" aims to provide
step-by-step instructions for users to get started with writing
extensions in PL/pgSQL and PL/Python.What's confusing here is writing an extension in a PL language is not a
normal use case I'd say. The normal use case involves some C code.
Extensions were designed for C, but they are working with PL well too.
Some of my customers use extensions for PLpgSQL and they are almost happy.
1) there is nothing else, 2) it is really works
I agree with Peter - this topic is not what I imagine under "Quick start
guide"
Regards
Pavel
The recent documentation patches are part of my GSoC 2023 project
<https://wiki.postgresql.org/wiki/GSoC_2023#Postgres_extension_tutorial_.2F_quick_start>
to develop a comprehensive PostgreSQL extension development tutorial, it
assumes only a basic knowledge of Postgres and the target programming
language.
The entire project is available on GitHub: Postgres-extension-tutorial
<https://github.com/IshaanAdarsh/Postgres-extension-tutorial/blob/main/SGML/intro_and_toc.md>.
It covers many topics, including prerequisites, writing extensions,
creating Makefiles, using procedural languages, incorporating external
languages, writing regression tests, and managing extension releases.
*The patch submitted
for procedural languages, specifically PL/pgSQL and PL/Python, is part of
the procedural language section within the broader tutorial. *
Based on the feedback I think there is a real need
<https://twitter.com/jer_s/status/1699071450915938609> for this as this is
a very important and growing part of the Postgres ecosystem. Currently, all
the extension material is scattered and very limited. There are various
third-party blog posts focusing on different areas, and sometimes
contradictory. The main motivation behind making this is to make the barrier
for entry less prohibitive for new contributors.
I would greatly appreciate your input on how to add it to the existing
documentation (this is where I have major doubts) and any suggestions on
how to proceed. If there are areas where the existing documentation is
already sufficient or if there are ways to improve the overall structure, I
am open to making adjustments.
Best,
Ishaan Adarsh
On Thu, Dec 21, 2023 at 4:17 PM Pavel Stehule <pavel.stehule@gmail.com>
wrote:
Show quoted text
Hi
čt 21. 12. 2023 v 11:18 odesílatel Peter Eisentraut <peter@eisentraut.org>
napsal:On 19.12.23 17:26, Ishaan Adarsh wrote:
Subject: Clarification on the Purpose of the Patch
Hi Peter,
The intention was to address the challenge faced by newcomers in
understanding how to write an extension for PostgreSQL. The existing
documentation, while comprehensive, lacks a consolidated and
easy-to-follow tutorial that serves as a quick start guide. The goalwas
to create a beginner-friendly resource that assumes only knowledge of
Postgres and the target language, making it accessible for new
contributors because the barrier for entry is prohibitive for new
contributors. There are various third-party blog posts focusing on
different areas, and sometimes contradictory.Have you seen this:
https://www.postgresql.org/docs/devel/extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE
Maybe that could be extended/modified/simplified?
Specifically:
1. The new section titled "Quick Start Guide" aims to provide
step-by-step instructions for users to get started with writing
extensions in PL/pgSQL and PL/Python.What's confusing here is writing an extension in a PL language is not a
normal use case I'd say. The normal use case involves some C code.Extensions were designed for C, but they are working with PL well too.
Some of my customers use extensions for PLpgSQL and they are almost happy.
1) there is nothing else, 2) it is really worksI agree with Peter - this topic is not what I imagine under "Quick start
guide"Regards
Pavel
Hi
čt 21. 12. 2023 v 13:37 odesílatel Ishaan Adarsh <ishaanad9@gmail.com>
napsal:
The recent documentation patches are part of my GSoC 2023 project
<https://wiki.postgresql.org/wiki/GSoC_2023#Postgres_extension_tutorial_.2F_quick_start>
to develop a comprehensive PostgreSQL extension development tutorial, it
assumes only a basic knowledge of Postgres and the target programming
language.The entire project is available on GitHub: Postgres-extension-tutorial
<https://github.com/IshaanAdarsh/Postgres-extension-tutorial/blob/main/SGML/intro_and_toc.md>.
It covers many topics, including prerequisites, writing extensions,
creating Makefiles, using procedural languages, incorporating external
languages, writing regression tests, and managing extension releases. *The patch submitted
for procedural languages, specifically PL/pgSQL and PL/Python, is part of
the procedural language section within the broader tutorial. *Based on the feedback I think there is a real need
<https://twitter.com/jer_s/status/1699071450915938609> for this as this
is a very important and growing part of the Postgres ecosystem. Currently,
all the extension material is scattered and very limited. There are
various third-party blog posts focusing on different areas, and sometimes
contradictory. The main motivation behind making this is to make the barrier
for entry less prohibitive for new contributors.I would greatly appreciate your input on how to add it to the existing
documentation (this is where I have major doubts) and any suggestions on
how to proceed. If there are areas where the existing documentation is
already sufficient or if there are ways to improve the overall structure, I
am open to making adjustments.
https://www.postgresql.org/docs/current/plpgsql-development-tips.html and
new section - deployment or packaging to extensions
I agree so https://www.postgresql.org/docs/current/plpgsql-overview.html is
under dimensioned, but packaging should not be there
Regards
Pavel
Show quoted text
Best,
Ishaan AdarshOn Thu, Dec 21, 2023 at 4:17 PM Pavel Stehule <pavel.stehule@gmail.com>
wrote:Hi
čt 21. 12. 2023 v 11:18 odesílatel Peter Eisentraut <peter@eisentraut.org>
napsal:On 19.12.23 17:26, Ishaan Adarsh wrote:
Subject: Clarification on the Purpose of the Patch
Hi Peter,
The intention was to address the challenge faced by newcomers in
understanding how to write an extension for PostgreSQL. The existing
documentation, while comprehensive, lacks a consolidated and
easy-to-follow tutorial that serves as a quick start guide. The goalwas
to create a beginner-friendly resource that assumes only knowledge of
Postgres and the target language, making it accessible for new
contributors because the barrier for entry is prohibitive for new
contributors. There are various third-party blog posts focusing on
different areas, and sometimes contradictory.Have you seen this:
https://www.postgresql.org/docs/devel/extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE
Maybe that could be extended/modified/simplified?
Specifically:
1. The new section titled "Quick Start Guide" aims to provide
step-by-step instructions for users to get started with writing
extensions in PL/pgSQL and PL/Python.What's confusing here is writing an extension in a PL language is not a
normal use case I'd say. The normal use case involves some C code.Extensions were designed for C, but they are working with PL well too.
Some of my customers use extensions for PLpgSQL and they are almost happy.
1) there is nothing else, 2) it is really worksI agree with Peter - this topic is not what I imagine under "Quick start
guide"Regards
Pavel
On Thu, 21 Dec 2023 at 21:03, Pavel Stehule <pavel.stehule@gmail.com> wrote:
Hi
čt 21. 12. 2023 v 13:37 odesílatel Ishaan Adarsh <ishaanad9@gmail.com>
napsal:The recent documentation patches are part of my GSoC 2023 project
<https://wiki.postgresql.org/wiki/GSoC_2023#Postgres_extension_tutorial_.2F_quick_start>
to develop a comprehensive PostgreSQL extension development tutorial, it
assumes only a basic knowledge of Postgres and the target programming
language.The entire project is available on GitHub: Postgres-extension-tutorial
<https://github.com/IshaanAdarsh/Postgres-extension-tutorial/blob/main/SGML/intro_and_toc.md>.
It covers many topics, including prerequisites, writing extensions,
creating Makefiles, using procedural languages, incorporating external
languages, writing regression tests, and managing extension releases. *The patch submitted
for procedural languages, specifically PL/pgSQL and PL/Python, is part of
the procedural language section within the broader tutorial. *Based on the feedback I think there is a real need
<https://twitter.com/jer_s/status/1699071450915938609> for this as this
is a very important and growing part of the Postgres ecosystem. Currently,
all the extension material is scattered and very limited. There are
various third-party blog posts focusing on different areas, and sometimes
contradictory. The main motivation behind making this is to make the barrier
for entry less prohibitive for new contributors.I would greatly appreciate your input on how to add it to the existing
documentation (this is where I have major doubts) and any suggestions on
how to proceed. If there are areas where the existing documentation is
already sufficient or if there are ways to improve the overall structure, I
am open to making adjustments.https://www.postgresql.org/docs/current/plpgsql-development-tips.html and
new section - deployment or packaging to extensionsI agree so https://www.postgresql.org/docs/current/plpgsql-overview.html is
under dimensioned, but packaging should not be there
It seems redundant if we add this for each PL, maybe a separate section to
describe how to package PL into extensions is better.
--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.
pá 22. 12. 2023 v 15:50 odesílatel Japin Li <japinli@hotmail.com> napsal:
On Thu, 21 Dec 2023 at 21:03, Pavel Stehule <pavel.stehule@gmail.com>
wrote:Hi
čt 21. 12. 2023 v 13:37 odesílatel Ishaan Adarsh <ishaanad9@gmail.com>
napsal:The recent documentation patches are part of my GSoC 2023 project
<https://wiki.postgresql.org/wiki/GSoC_2023#Postgres_extension_tutorial_.2F_quick_start
to develop a comprehensive PostgreSQL extension development tutorial, it
assumes only a basic knowledge of Postgres and the target programming
language.The entire project is available on GitHub: Postgres-extension-tutorial
<https://github.com/IshaanAdarsh/Postgres-extension-tutorial/blob/main/SGML/intro_and_toc.md
.
It covers many topics, including prerequisites, writing extensions,
creating Makefiles, using procedural languages, incorporating external
languages, writing regression tests, and managing extension releases.*The patch submitted
for procedural languages, specifically PL/pgSQL and PL/Python, is part
of
the procedural language section within the broader tutorial. *
Based on the feedback I think there is a real need
<https://twitter.com/jer_s/status/1699071450915938609> for this as this
is a very important and growing part of the Postgres ecosystem.Currently,
all the extension material is scattered and very limited. There are
various third-party blog posts focusing on different areas, andsometimes
contradictory. The main motivation behind making this is to make the
barrier
for entry less prohibitive for new contributors.
I would greatly appreciate your input on how to add it to the existing
documentation (this is where I have major doubts) and any suggestions on
how to proceed. If there are areas where the existing documentation is
already sufficient or if there are ways to improve the overallstructure, I
am open to making adjustments.
https://www.postgresql.org/docs/current/plpgsql-development-tips.html
and
new section - deployment or packaging to extensions
I agree so https://www.postgresql.org/docs/current/plpgsql-overview.html
is
under dimensioned, but packaging should not be there
It seems redundant if we add this for each PL, maybe a separate section to
describe how to package PL into extensions is better.
I have not a strong opinion about it. My personal experience is so 99% PL
code is PLpgSQL, so it can be there, and other PL can be referenced there.
I am not sure if there is some common part for all PL.
Regards
Pavel
Show quoted text
--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.
On Fri, Dec 22, 2023 at 12:04 PM Pavel Stehule <pavel.stehule@gmail.com> wrote:
I have not a strong opinion about it. My personal experience is so 99% PL code is PLpgSQL, so it can be there, and other PL can be referenced there. I am not sure if there is some common part for all PL.
After reading over this thread, it seems clear to me that there is no
consensus to proceed with this patch in its current form, and the
discussion seems to have stalled. Accordingly, I've marked this
"Returned with Feedback" in the CommitFest.
Ishaan, if you plan to rework this into a form which might be
acceptable given the review comments made up until now, please feel
free to change this back to "Waiting on Author", and/or move it to a
future CommitFest.
--
Robert Haas
EDB: http://www.enterprisedb.com