document run_sql

Author: lovasoa

examples/official-site/sqlpage/migrations/38_run_sql.sql

@@ -0,0 +1,47 @@
+INSERT INTO sqlpage_functions (
+        "name",
+        "introduced_in_version",
+        "icon",
+        "description_md"
+    )
+VALUES (
+        'run_sql',
+        '0.20.0',
+        'login',
+        'Executes another SQL file and returns its result as a JSON array.
+
+### Example
+    
+#### Include a common header in all your pages
+
+It is common to want to run the same SQL queries at the beginning of all your pages,
+to check if an user is logged in, render a header, etc.
+You can create a file called `common_header.sql`, and use the `dynamic` component with the `run_sql` function to include it in all your pages.
+
+```sql
+select ''dynamic'' as component, sqlpage.run_sql(''common_header.sql'') as contents;
+```
+
+#### Notes
+
+ - **recursion**: you can use `run_sql` to include a file that itself includes another file, and so on. However, be careful to avoid infinite loops. SQLPage will throw an error if it detects a loop.
+ - **security**: be careful when using `run_sql` to include files. Never use `run_sql` with a user-provided parameter. Never run a file uploaded by a user, or a file that is not under your control.
+ - **variables**: the included file will have access to the same variables (URL parameters, POST variables, etc.)
+   as the calling file. It will not have access to uploaded files.
+   If the included file changes the value of a variable or creates a new variable, the change will not be visible in the calling file.
+'
+    );
+INSERT INTO sqlpage_function_parameters (
+        "function",
+        "index",
+        "name",
+        "description_md",
+        "type"
+    )
+VALUES (
+        'run_sql',
+        1,
+        'file',
+        'Path to the SQL file to execute, relative to the WEB ROOT (the root folder of your website).',
+        'TEXT'
+    );