document 404.sql

thanks again to  @wucke13  who implemented the feature

Author: lovasoa

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.28.0 (unreleased)
 - Chart component: fix the labels of pie charts displaying too many decimal places.
+- You can now create a `404.sql` file anywhere in your SQLPage project to handle requests to non-existing pages. This allows you to create custom 404 pages, or create [nice URLs](https://sql.datapage.app/your-first-sql-website/nginx.sql) that don't end with `.sql`.
 
 ## 0.27.0 (2024-08-17)
 

configuration.md

@@ -128,3 +128,14 @@ CREATE TEMPORARY TABLE my_temporary_table(
     my_temp_column TEXT
 );
 ```
+
+## Migrations
+
+SQLPage allows you to run SQL scripts when the database schema changes, by creating a `sqlpage/migrations` directory.
+We have a guide on [how to create migrations](https://sql.datapage.app/your-first-sql-website/migrations.sql).
+
+## Custom URL routes
+
+By default, SQLPage encourages a simple mapping between the URL and the SQL file that is executed.
+You can also create custom URL routes by creating [`404.sql` files](http://localhost:8080/your-first-sql-website/custom_urls.sql).
+If you need advanced routing, you can also [add a reverse proxy in front of SQLPage](https://sql.datapage.app/reverse_proxy.sql).

examples/official-site/404.sql

@@ -0,0 +1,10 @@
+select 'redirect' as component, '/404.sql' as link where sqlpage.path() <> '/404.sql';
+
+select 'status_code' as component, 404 as status;
+select 'http_header' as component, 'no-store, max-age=0' as "Cache-Control";
+select 'dynamic' as component, properties FROM example WHERE component = 'shell' LIMIT 1;
+
+select 'hero' as component,
+    'Not Found' as title,
+    'Sorry, we couldn''t find the page you were looking for.' as description_md,
+    '/your-first-sql-website/not_found.jpg' as image;

examples/official-site/sqlpage/migrations/11_json.sql

@@ -63,5 +63,10 @@ This will return a JSON response that looks like this:
 }
 ```
 
+If you want to handle custom API routes, like `POST /api/users/:id`,
+you can use 
+ - the [`404.sql` file](/your-first-sql-website/custom_urls.sql) to handle the request despite the URL not matching any file,
+ - the [`request_method` function](/functions.sql?function=request_method#function) to differentiate between GET and POST requests,
+ - and the [`path` function](/functions.sql?function=path#function) to extract the `:id` parameter from the URL.
 '
     );

examples/official-site/sqlpage/migrations/48_status_code.sql

@@ -0,0 +1,46 @@
+-- Insert the status_code component into the component table
+INSERT INTO
+    component (name, description, icon)
+VALUES
+    (
+        'status_code',
+        'A simple component to set the HTTP status code for the response. This can be used to indicate the result of the request, such as 200 for success, 404 for not found, or 500 for server error.
+
+        The status code should be set according to the HTTP standard status codes.
+
+        This component should be used when you need to explicitly set the status code of the HTTP response.
+        ',
+        'error-404'
+    );
+
+-- Insert the parameters for the status_code component into the parameter table
+INSERT INTO
+    parameter (
+        component,
+        name,
+        description,
+        type,
+        top_level,
+        optional
+    )
+VALUES
+    (
+        'status_code',
+        'status',
+        'The HTTP status code to be set for the response. This should be an integer value representing a valid HTTP status code.',
+        'INTEGER',
+        TRUE,
+        FALSE
+    );
+
+
+INSERT INTO example (component, description)
+VALUES (
+        'status_code',
+        'Set the HTTP status code to 404, indicating that the requested resource was not found.
+Useful in combination with [`404.sql` files](/your-first-sql-website/custom_urls.sql):
+
+```sql
+select ''status_code'' as component, 404 as status;
+```
+');

examples/official-site/your-first-sql-website/custom_urls.sql

@@ -0,0 +1,56 @@
+select 'http_header' as component,
+    'public, max-age=300, stale-while-revalidate=3600, stale-if-error=86400' as "Cache-Control";
+
+select 'dynamic' as component, properties FROM example WHERE component = 'shell' LIMIT 1;
+
+select 'hero' as component,
+    'Custom URLs' as title,
+    'SQLPage lets you customize responses to URLs that don''t match any file, using `404.sql`.' as description_md,
+    'not_found.jpg' as image;
+
+select 'text' as component, '
+# Handling custom URLs
+
+By default, SQLPage serves the file that matches the URL requested by the client.
+If your users enter `https://example.com/about`, SQLPage will serve the file `about/index.sql` in your project.
+If you create a file named `about.sql`, SQLPage will serve it when the user requests `https://example.com/about.sql`.
+
+But what if you want to handle URLs that don''t match any file in your project ?
+For example, what if you have a blog, and you want nice urls like `example.com/blog/my-trip-to-rome`,
+but you don''t want to create a file for each blog post ?
+By default, SQLPage would return a sad 404 error if you don''t have a file named `blog/my-trip-to-rome/index.sql`
+in your project''s root directory.
+
+But you can customize this behavior by creating a file named `404.sql` in your project.
+
+## The 404.sql file
+
+When SQLPage doesn''t find a file that matches the URL requested by the client, it will serve the file `404.sql` if it exists.
+
+Since v0.28, when SQLPage receives a request for a URL like `https://example.com/a/b/c`, it will look for the file `a/b/c/index.sql` in your project,
+and if it doesn''t find it, it will then search for, in order:
+- `/a/b/404.sql`
+- `/a/404.sql`
+- `/404.sql`
+
+## Basic routing example
+
+So, you have a `blog_posts` table in your database, with columns `name`, and `content`.
+You want to serve the content of the blog post with id `:id` when the user requests `example.com/blog/:id`.
+You can do this by creating a `404.sql` file in the `blog` directory of your project:
+
+```sql
+-- blog/404.sql
+
+-- Get the id from the URL
+set name = substr(sqlpage.path(), 1+length(''/blog/''));
+
+-- Get the blog post from the database
+select ''text'' as component,
+    content as contents_md
+from blog_posts
+where name = $name;
+```
+
+Now, when a user requests `example.com/blog/my-trip-to-rome`, SQLPage will serve the content of the blog post with name `my-trip-to-rome` from the `blog_posts` table.
+' as contents_md;

examples/official-site/your-first-sql-website/nginx.md

@@ -70,6 +70,9 @@ Your SQLPage instance is now hosted behind a reverse proxy using NGINX. You can
 URL rewriting is a powerful feature that allows you to manipulate URLs to make them more readable, search-engine-friendly, and easy to maintain.
 In this section, we will cover how to use URL rewriting with SQLPage.
 
+Note that for basic URL rewriting, you can use a simple [`404.sql`](/your-first-sql-website/custom_urls.sql) file to handle custom URLs.
+However, for more complex rewriting rules, you can use NGINX's `rewrite` directive.
+
 #### Example: Rewriting `/products/$id` to `/products.sql?id=$id`
 
 Let's say you want your users to access product details using URLs like `/products/123` instead of `/products.sql?id=123`. This can be achieved using the `rewrite` directive in NGINX.

examples/official-site/your-first-sql-website/not_found.jpg

@@ -454,6 +454,7 @@ async fn serve_fallback(
     for idx in req_path
         .rmatch_indices('/')
         .map(|(idx, _)| idx + 1)
+        .take(128) // Limit the number of iterations because lookups can be expensive
         .chain(std::iter::once(0))
     {
         // Remove the trailing substring behind the current `/`, and append `404.sql`.