From c6733b4c2ac2d35edffd065520aa9321675c7f67 Mon Sep 17 00:00:00 2001 From: lovasoa Date: Fri, 19 Jul 2024 16:12:38 +0200 Subject: [PATCH] rephrase turorial --- .../your-first-sql-website/tutorial.md | 67 +++++++++---------- 1 file changed, 30 insertions(+), 37 deletions(-) diff --git a/examples/official-site/your-first-sql-website/tutorial.md b/examples/official-site/your-first-sql-website/tutorial.md index bf46b8b0..f5b2e45f 100644 --- a/examples/official-site/your-first-sql-website/tutorial.md +++ b/examples/official-site/your-first-sql-website/tutorial.md @@ -1,12 +1,10 @@ - -Download SQLPage: the SQL website framework -=========================================== +# Download SQLPage: the SQL website framework SQLPage is a small executable file that will take requests to your website, execute the SQL files you write, and render the database responses as nice web pages. [Download the latest SQLPage](https://github.com/lovasoa/SQLpage/releases) for your operating system. -In the *release assets* section, you will find files named `sqlpage-windows.zip`, `sqlpage-linux.tgz`, and `sqlpage-macos.tgz`. +In the _release assets_ section, you will find files named `sqlpage-windows.zip`, `sqlpage-linux.tgz`, and `sqlpage-macos.tgz`. Download the one that corresponds to your operating system, and extract the executable file from the archive. > **Note**: Advanced users can alternatively install SQLPage using @@ -16,8 +14,7 @@ Download the one that corresponds to your operating system, and extract the exec > [scoop](https://scoop.sh/#/apps?q=sqlpage&id=305b3437817cd197058954a2f76ac1cf0e444116), > or [cargo](https://crates.io/crates/sqlpage). -Building your website locally -============================= +# Building your website locally Create a folder on your computer where you will store all contents related to your sql website. In the rest of this tutorial, we will call this folder the **root folder** of your website. @@ -29,12 +26,11 @@ Then launch the `sqlpage.bin` executable file you just downloaded in a terminal ![screenshot for the sql website setup](first-sql-website-launch.png) -You should see a message in your terminal that includes the sentence `SQLPage is now running on http://127.0.0.1:8080/` +You should see a message in your terminal that includes the sentence `accessible from the network, and locally on http://localhost:8080` -You can open your website locally by visiting [`http://127.0.0.1:8080`](http://127.0.0.1:8080/) +You can open your website locally by visiting [`http://localhost:8080`](http://localhost:8080) -Your website’s first SQL file -============================= +# Your website’s first SQL file In the root folder of your SQLPage website, create a new SQL file called `index.sql`. Open it in a text editor that supports SQL syntax highlighting (I recommend [VSCode](https://code.visualstudio.com/)). @@ -55,10 +51,9 @@ In this case, we use the [`list` component](/documentation.sql?component=list#co The second line defines the data that will populate the component. All the components you can use and their properties are documented in [SQLPage's online documentation](https://sql.ophir.dev/documentation.sql). -Your database schema -==================== +# Your database schema -> If you already have a database populated with data, +> If you already have a database populated with data, > or if you intend to use other tools to manage your database structure, > you can skip this section. @@ -75,14 +70,13 @@ CREATE TABLE users ( ); ``` -Please read our [**introduction to database migrations**](./migrations.sql) to +Please read our [**introduction to database migrations**](./migrations.sql) to learn how to maintain your database schema in the long term. > **Note**: The migration system is not supported on Microsoft SQL Server databases. -> If you are using a SQL Server database, you should create your tables using a different tool, such as *SQL Server Management Studio*. +> If you are using a SQL Server database, you should create your tables using a different tool, such as _SQL Server Management Studio_. -Connect to a custom database -============================ +# Connect to a custom database By default, SQLPage uses a [SQLite](https://www.sqlite.org/about.html) database stored in a file named `sqlpage.db` in the `sqlpage` configuration folder. @@ -98,22 +92,20 @@ Here is an example `sqlpage.json` file: This will tell SQLPage to use an in-memory SQLite database instead of the default file-based database. All your data will be lost when you stop the SQLPage server, but it is useful for quickly testing and iterating on your database schema. -Later, when you want to deploy your website online, you can switch back to a persisted database like - - a SQLite file with `sqlite://your-database-file.db` ([see options](https://docs.rs/sqlx/0.6.3/sqlx/sqlite/struct.SqliteConnectOptions.html#main-content)), - - a PostgreSQL-compatible server with `postgres://user:password@host/database` ([see options](https://www.postgresql.org/docs/15/libpq-connect.html#id-1.7.3.8.3.6)), - - a MySQL-compatible server with `mysql://user:password@host/database` ([see options](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html)), - - a Microsoft SQL Server with `mssql://user:password@host/database` ([see options](https://docs.rs/sqlx-oldapi/latest/sqlx_oldapi/mssql/struct.MssqlConnectOptions.html), [note about named instances](https://github.com/lovasoa/SQLpage/issues/92)), +Later, when you want to deploy your website online, you can switch back to a persisted database like + +- a SQLite file with `sqlite://your-database-file.db` ([see options](https://docs.rs/sqlx/0.6.3/sqlx/sqlite/struct.SqliteConnectOptions.html#main-content)), +- a PostgreSQL-compatible server with `postgres://user:password@host/database` ([see options](https://www.postgresql.org/docs/15/libpq-connect.html#id-1.7.3.8.3.6)), +- a MySQL-compatible server with `mysql://user:password@host/database` ([see options](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html)), +- a Microsoft SQL Server with `mssql://user:password@host/database` ([see options](https://docs.rs/sqlx-oldapi/latest/sqlx_oldapi/mssql/struct.MssqlConnectOptions.html), [note about named instances](https://github.com/lovasoa/SQLpage/issues/92)), If `user` or `password` contains special characters, you should [percent-encode](https://en.wikipedia.org/wiki/Percent-encoding) them. For instance, a SQL Server database named `db` running on `localhost` port `1433` with the username `funny:user` and the password `p@ssw0rd` would be represented as `mssql://funny%3Auser:p%40ssw0rd@localhost:1433/db`. For more information about the properties that can be set in sqlpage.json, see [SQLPage's configuration documentation](https://github.com/lovasoa/SQLpage/blob/main/configuration.md#configuring-sqlpage) - ![screenshot for the full sql website folder organisation](full-website.png) - -Use parameterized SQL queries to let users interact with your database -====================================================================== +# Use parameterized SQL queries to let users interact with your database ### Displaying a form @@ -127,6 +119,7 @@ SELECT 'Username' as name, TRUE as required; The snippet above uses the [`form` component](https://sql.ophir.dev/documentation.sql?component=form#component) to display a form on your website. ### Handling form submission + Nothing happens when you submit the form at the moment. Let’s fix that. Add the following below the previous code: @@ -136,17 +129,18 @@ SELECT :Username WHERE :Username IS NOT NULL; ``` -The snippet above uses an [`INSERT INTO SELECT` SQL statement](https://www.sqlite.org/lang_insert.html) to +The snippet above uses an [`INSERT INTO SELECT` SQL statement](https://www.sqlite.org/lang_insert.html) to [safely](../safety.sql) insert a new row into the `users` table when the form is submitted. It uses a `WHERE` clause to make sure that the `INSERT` statement is only executed when the `:Username` parameter is present. -The `:Username` parameter is set to `NULL` when you initially load the page, and then SQLPage automatically sets it to the value +The `:Username` parameter is set to `NULL` when you initially load the page, and then SQLPage automatically sets it to the value from the text field when the user submits the form. There are two types of parameters you can use in your SQL queries: - - `:ParameterName` is a [POST](https://en.wikipedia.org/wiki/POST_(HTTP)) parameter. It is set to the value of the field with the corresponding `name` in a form. If no form was submitted, it is set to `NULL`. - - `$ParameterName` works the same as `:ParameterName`, but it can also be set through a [query parameter](https://en.wikipedia.org/wiki/Query_string) in the URL. - If you add `?x=1&y=2` to the end of the URL of your page, `$x` will be set to the string `'1'` and `$y` will be set to the string `'2'`. - If a query parameter was not provided, it is set to `NULL`. + +- `:ParameterName` is a [POST]() parameter. It is set to the value of the field with the corresponding `name` in a form. If no form was submitted, it is set to `NULL`. +- `$ParameterName` works the same as `:ParameterName`, but it can also be set through a [query parameter](https://en.wikipedia.org/wiki/Query_string) in the URL. + If you add `?x=1&y=2` to the end of the URL of your page, `$x` will be set to the string `'1'` and `$y` will be set to the string `'2'`. + If a query parameter was not provided, it is set to `NULL`. ### Displaying contents from the database @@ -165,11 +159,9 @@ Here is a screenshot of the final result: ![final result](final-result.png) - To go further, have a look at [the examples section of our Github repository](https://github.com/lovasoa/SQLpage/tree/main/examples). -Deploy your SQLPage website online -================================== +# Deploy your SQLPage website online If you want to make your SQLPage website accessible online for everyone to browse, you can deploy it to a VPS (Virtual Private Server). To get started, sign up for a VPS provider of your choice. Some popular options include: AWS EC2, DigitalOcean, Linode, Hetzner. @@ -201,5 +193,6 @@ Then, run the following command on your server: To access your website, enter the address of your VPS in your address bar, followed by the port on which SQLPage runs. For instance: http://123.123.123.123:8080. For production use, you should: - - run SQLPage as a service, using a tool like [docker](https://docs.docker.com/engine/reference/run/) or [systemd](https://linuxhandbook.com/create-systemd-services/). - - [use a reverse proxy like *nginx*](./nginx.sql) to improve security and performance, or to configure multiple websites on the same server. + +- run SQLPage as a service, using a tool like [docker](https://docs.docker.com/engine/reference/run/) or [systemd](https://linuxhandbook.com/create-systemd-services/). +- [use a reverse proxy like _nginx_](./nginx.sql) to improve security and performance, or to configure multiple websites on the same server.