wip: perf guide

Author: lovasoa

examples/official-site/performance.sql

@@ -22,20 +22,21 @@ as opposed to writing imperative code in a backend programming language like Jav
 This declarative approach allows SQLPage to offer **optimizations** out of the box that are difficult or time-consuming
 to achieve in traditional web development stacks.
 
-## Server-side rendering
+## Progressive server-side rendering
 
 SQLPage applications are [server-side rendered](https://web.dev/articles/rendering-on-the-web),
-which means that the SQL queries are executed on the server, and the results are sent to the user''s browser
-as HTML, which allows it to start rendering the page as soon as the first byte is received.
+which means that the SQL queries are executed on the server, and the results are sent to the user''s browser as HTML.
 In contrast, many other web frameworks render the page on the client side, which means that the browser has to download
 some HTML, then download some JavaScript, then execute the JavaScript, then make more requests,
+wait for the database to produce a full result set,
 then process the responses before it can start rendering the actual data the user is interested in.
 This can lead to loading times that are several times longer than a SQLPage application.
 
 ### Streaming
 
 SQLPage applications will often feel faster than even equivalent applications written even in alternative server-side rendering
 frameworks, because SQLPage streams the results of the SQL queries to the browser as soon as they are available.
+The user sees the start of the page even before the database has finished producing the last query results.
 
 Most server-side rendering frameworks will first wait for all the SQL queries to finish, then render the page in memory
 on the server, and only then send the HTML webpage to the browser. If a page contains a long list of items, the user
@@ -51,7 +52,7 @@ an execution plan every time an user requests a page.
 
 When an user loads a page, all SQLPage has to do is tell the database: "Hey, do you remember that query we talked about
 earlier? Can you give me the results for these specific parameters?". This is much faster than sending the whole SQL query
-string to the database every time.
+string to the database every time, especially for large complex queries that require heavy planning on the database side.
 
 ## Compiled templates
 
@@ -87,16 +88,15 @@ interaction.
 
 ## Key Takeaways
 
-SQLPage offers a radically different approach to web development,
-resolving the classical tension between performance and ease of use.
-
-By leveraging a declarative approach, server-side rendering, and advanced optimization techniques, SQLPage enables:
-
-* **Faster page loads**: Long loading times make your website feel sluggish and unresponsive, causing users to leave.
-* **Easier development**: Focus on writing SQL queries; all the heavy lifting is done for you.
-* **Cost effective**: SQLPage''s low CPU and memory usage means you can host your website extremely cheaply, even if it gets significant traffic.
+Performance is a key feature of SQLPage.
+Its architecture allows you to build fast websites without having to implement advanced optimizations yourself.
 
 ## Ready to get started?
 
 [Build your fast, secure, and beautiful website](/your-first-sql-website) with SQLPage today!
+
+## Already a SQLPage developer ?
+
+Have a look at our [performance guide](/blog?post=Performance+Guide) to learn the best practices to leverage
+all the features that will make your site faster.
 ' as contents_md;

examples/official-site/sqlpage/migrations/69_blog_performance_guide.sql

@@ -0,0 +1,92 @@
+
+INSERT INTO blog_posts (title, description, icon, created_at, content)
+VALUES
+    (
+        'Performance Guide',
+        'Concrete advice on how to make your SQLPage webapp fast',
+        'bolt',
+        '2025-10-31',
+        '
+# Performance Guide
+
+SQLPage is [optimized](/performance)
+to allow you to create web pages that feel snappy.
+This guide contains advice on how to ensure your users never wait
+behind a blank screen waiting for your pages to load.
+
+A lot of the advice here is not specific to SQLPage, but applies
+to making SQL queries fast in general.
+If you are already comfortable with SQL performance optimization, feel free to jump right to
+the second part of the quide: *SQLPage-specific advice*.
+
+## Make your queries fast
+
+The best way to ensure your SQLPage webapp is fast is to ensure your
+database is well managed and your SQL queries are well written.
+We''ll go over the most common database performance pitfalls so that you know how to avoid them.
+
+### Choose the right database schema
+
+#### Normalize (but not too much)
+
+Your database schema should be made so that one piece of information
+is stored in only one place in the database.
+For instance, if you are modelling sales that happen in stores, the sales table should 
+contain a foreign key to another table named stores.
+This way, when you need to display the list of stores in your application, you don''t have to 
+run a slow `select distinct store from sales`, that would have to go through your millions of sales
+(*even if you have an index on the store column*),
+
+### Use database indices
+
+### Use (materialized) views
+
+### Query performance debugging
+
+## SQLPage-specific advice
+
+The best way to make your SQLPage webapp fast is to make your queries fast.
+Sometimes, you just don''t have control over the database, and have to run slow queries.
+This section will help you minimize the impact to your users.
+
+### Order matters
+
+SQLPage executes the queries in your `.sql` files in order.
+It does not start executing a query before the previous one has returned all its results.
+So, if you have to execute a slow query, put it as far down in the page as possible.
+
+#### No heavy computation before the shell
+
+Every user-facing page in a SQLPage site has a [shell](/components?component=shell).
+
+The first queries in any sql file (all the ones that come before the [])
+
+#### Set variables just above their first usage
+
+### Avoid recomputing the same data multiple times
+
+### Reduce the number of queries
+
+### Lazy loading
+
+Use the card and modal components to load data lazily.
+
+### Database connections
+
+SQLPage uses connection pooling: it keeps multiple database connections opened,
+and reuses them for consecutive requests. When it does not receive requests for a long time,
+it closes idle connection. When it receives many requests, it opens new connection,
+but never more than the value specified by `max_database_pool_connections` in its
+[configuration](https://github.com/sqlpage/SQLPage/blob/main/configuration.md).
+You can increase the value of that parameter if your website has many concurrent users and your
+database is configured to allow opening many simultaneous connections.
+
+### SQLPage performance debugging
+
+When `environment` is set to `development` in its [configuration](https://github.com/sqlpage/SQLPage/blob/main/configuration.md),
+SQLPage will include precise measurement of the time it spends in each of the steps it has to go through before starting to send data
+back to the user''s browser. You can visualize that performance data in your browser''s network inspector.
+
+You can set the `RUST_LOG` environment variable to `sqlpage=debug` to make SQLPage
+print detailed messages associated with precise timing for everything it does.
+');