I build my own script.so function for the first time recently. I ran into tons of issues due to incomplete documentation. As a result, I propose that we rewrite the documentation that we have. There is important information in there, but it's nowhere near complete enough for use.
If there's anything you'd like included in the script.so documentation, be sure to mention it in this issue.
Here's my recommendation of format:
How to get script.so
How to install script.so
(should explain compilation and install location)
Overview of script.so file and function relationship
(should show that a file and accompanying postgres function are needed)
(should explain that the name should have the same name as the Postgres function)
How to write a script.so script
(should include bare-bones examples of both types of parameter access)
(should include explanations of any security issues the reader should watch out for)
How to write a script.soPostgres function
(should include explanation of naming)
(should show difference between perl and bash)
How to call a script.soPostgres function
(should include what the equivalent command line calls would look like)
Here are the problems in the current documentation I'm trying to address:
Naming conventions are not explained
I thought that action_script_perl and action_script_bash were example names
I didn't know that the Postgres function name determined what file was run
Missing explanations
I didn't know action_script_bash existed.
I didn't know that action_script_perl and action_script_bash determined what file extension you used
I didn't have a reference for what file extensions were valid
Unclear documentation structure
The sections are not laid out in a consistent format
Lots of things look like first-level sections that should be sub-sections
"Parameters" section wasn't really helpful
The page is not laid out in a clear story arc (starting from no script.so and ending with working file/function relationship)
Example Perl and Bash functions are off-topic, uncommented and overly complex
I would've had an easier time if there was an example for echoing/printing all given parameters
There is no link to get the latest version of script.so
There is no explanation of where the script.soC program belongs
The only reason I was able to tell script.so was installed was because someone else used it in the database I was in. Not because I knew where to look in the file system.
"We use the secure coding specification from: [LINK]" doesn't belong in the documentation, it belongs with the source code for script.so
Unless that was meant to explain to the reader that they should follow that coding specification as well. In which case, that sentence needs to address that.
I build my own
script.sofunction for the first time recently. I ran into tons of issues due to incomplete documentation. As a result, I propose that we rewrite the documentation that we have. There is important information in there, but it's nowhere near complete enough for use.If there's anything you'd like included in the script.so documentation, be sure to mention it in this issue.
Here's my recommendation of format:
script.soscript.soscript.sofile and function relationshippostgresfunction are needed)Postgresfunction)script.soscriptscript.soPostgresfunctionperlandbash)script.soPostgresfunctionHere are the problems in the current documentation I'm trying to address:
action_script_perlandaction_script_bashwere example namesPostgresfunction name determined what file was runaction_script_bashexisted.action_script_perlandaction_script_bashdetermined what file extension you usedscript.soand ending with working file/function relationship)PerlandBashfunctions are off-topic, uncommented and overly complexechoing/printing all given parametersscript.soscript.soCprogram belongsscript.sowas installed was because someone else used it in the database I was in. Not because I knew where to look in the file system.