From ea14c96361e9d11a7e70522828ec5f10542077ac Mon Sep 17 00:00:00 2001 From: lovasoa Date: Thu, 23 May 2024 18:36:14 +0200 Subject: [PATCH] links to migrations --- CHANGELOG.md | 1 + configuration.md | 2 +- .../migrations.md} | 11 ++--------- .../your-first-sql-website/migrations.sql | 7 +++++++ .../official-site/your-first-sql-website/tutorial.md | 12 +++--------- .../todo application/sqlpage/migrations/README.md | 2 ++ sqlpage/migrations/README.md | 2 ++ 7 files changed, 18 insertions(+), 19 deletions(-) rename examples/official-site/{migrations.sql => your-first-sql-website/migrations.md} (93%) create mode 100644 examples/official-site/your-first-sql-website/migrations.sql diff --git a/CHANGELOG.md b/CHANGELOG.md index 48993d05..7faf3dce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ - when providing an ISO datetime string for the x value (time), without an explicit timezone, it is now interpreted and displayed in the local timezone of the user. It used to be interpreted as a local time, but displayed in UTC, which [was confusing](https://github.com/lovasoa/SQLpage/issues/324). If you were using the `TRUE as time` syntax with naive datetime strings (without timezone information), you will need to convert your datetime strings to UTC on the database side if you want to keep the same behavior as before. As a side note, it is always recommended to store and query datetime strings with timezone information in the database, to avoid ambiguity. - This change is particularly useful in SQLite, which generates naive datetime strings by default. You should still store and query datetimes as unix timestamps when possible, to avoid ambiguity and reduce storage size. - When calling a file with [`sqlpage.run_sql`](https://sql.ophir.dev/functions.sql?function=run_sql#function), the target file now has access to uploaded files. + - New article by [Matthew Larkin](https://github.com/matthewlarkin) about [migrations](https://sql.ophir.dev/your-first-sql-website/migrations.sql). ## 0.21.0 (2024-05-19) diff --git a/configuration.md b/configuration.md index e3d66e7c..333163dc 100644 --- a/configuration.md +++ b/configuration.md @@ -19,7 +19,7 @@ Here are the available configuration options and their default values: | `sqlite_extensions` | | An array of SQLite extensions to load, such as `mod_spatialite` | | `web_root` | `.` | The root directory of the web server, where the `index.sql` file is located. | | `site_prefix` | `/` | Base path of the site. If you want to host SQLPage at `https://example.com/sqlpage/`, set this to `/sqlpage/`. When using a reverse proxy, this allows hosting SQLPage together with other applications on the same subdomain. | -| `configuration_directory` | `./sqlpage/` | The directory where the `sqlpage.json` file is located. This is used to find the path to `templates/`, `migrations/`, and `on_connect.sql`. Obviously, this configuration parameter can be set only through environment variables, not through the `sqlpage.json` file itself in order to find the `sqlpage.json` file. Be careful not to use a path that is accessible from the public WEB_ROOT | +| `configuration_directory` | `./sqlpage/` | The directory where the `sqlpage.json` file is located. This is used to find the path to [`templates/`](https://sql.ophir.dev/custom_components.sql), [`migrations/`](https://sql.ophir.dev/your-first-sql-website/migrations.sql), and `on_connect.sql`. Obviously, this configuration parameter can be set only through environment variables, not through the `sqlpage.json` file itself in order to find the `sqlpage.json` file. Be careful not to use a path that is accessible from the public WEB_ROOT | | `allow_exec` | false | Allow usage of the `sqlpage.exec` function. Do this only if all users with write access to sqlpage query files and to the optional `sqlpage_files` table on the database are trusted. | | `max_uploaded_file_size` | 5242880 | Maximum size of uploaded files in bytes. Defaults to 5 MiB. | | `https_domain` | | Domain name to request a certificate for. Setting this parameter will automatically make SQLPage listen on port 443 and request an SSL certificate. The server will take a little bit longer to start the first time it has to request a certificate. | diff --git a/examples/official-site/migrations.sql b/examples/official-site/your-first-sql-website/migrations.md similarity index 93% rename from examples/official-site/migrations.sql rename to examples/official-site/your-first-sql-website/migrations.md index 2e24afcb..68698af9 100644 --- a/examples/official-site/migrations.sql +++ b/examples/official-site/your-first-sql-website/migrations.md @@ -1,11 +1,4 @@ -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; - --- Article by Matthew Larkin -select 'text' as component, -"# Understanding SQL Migrations: Your Database, Layer by Layer +# Understanding SQL Migrations: Your Database, Layer by Layer Maintaining a structured and evolving database is crucial for web app development. Rarely do we get a schema 100% correct on day one. New insights about the shape of the application are discovered over time, or business needs themselves evolve. In the world of databases, we can evolve schemas using migration files. These files are just more SQL that append or amend layers of development. Think of this process like sedimentary rock layers. Each migration adds a layer, and together, these layers create a complete, functional structure along with a visible trail of historical changes. @@ -150,4 +143,4 @@ Best migrations on your evolving database journey! 👋 --- -Article written by [Matthew Larkin](https://github.com/matthewlarkin) for [SQLPage](https://sql.ophir.dev/)." as contents_md; +Article written by [Matthew Larkin](https://github.com/matthewlarkin) for [SQLPage](https://sql.ophir.dev/). \ No newline at end of file diff --git a/examples/official-site/your-first-sql-website/migrations.sql b/examples/official-site/your-first-sql-website/migrations.sql new file mode 100644 index 00000000..5521da91 --- /dev/null +++ b/examples/official-site/your-first-sql-website/migrations.sql @@ -0,0 +1,7 @@ +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; + +-- Article by Matthew Larkin +select 'text' as component, sqlpage.read_file_as_text('your-first-sql-website/migrations.md') as contents_md; diff --git a/examples/official-site/your-first-sql-website/tutorial.md b/examples/official-site/your-first-sql-website/tutorial.md index 9049a740..9cf6492c 100644 --- a/examples/official-site/your-first-sql-website/tutorial.md +++ b/examples/official-site/your-first-sql-website/tutorial.md @@ -65,15 +65,6 @@ Your database schema The [database schema](https://en.wikipedia.org/wiki/Database_schema) for your SQLPage website can be defined using SQL scripts located in the **`sqlpage/migrations`** subdirectory of your website's root folder. -Each script represents a [migration](https://en.wikipedia.org/wiki/Schema_migration) -that sets up or modifies the database structure. - -The scripts are executed in order. You must prefix them with a number to control the order in which they are executed. -For instance, `my_website/sqlpage/migrations/0001_create_users_table.sql` -will be executed before `my_website/sqlpage/migrations/0002_add_email_to_users_table.sql`. -SQLPage keeps track of which migrations have already run -(by storing the executed migrations in a table named `_sqlx_migrations`), -and will only execute new migrations. For our first website, let's create a file located in `sqlpage/migrations/0001_create_users_table.sql` with the following contents: @@ -84,6 +75,9 @@ CREATE TABLE users ( ); ``` +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*. diff --git a/examples/todo application/sqlpage/migrations/README.md b/examples/todo application/sqlpage/migrations/README.md index 38731b04..9ce6c0b1 100644 --- a/examples/todo application/sqlpage/migrations/README.md +++ b/examples/todo application/sqlpage/migrations/README.md @@ -3,6 +3,8 @@ SQLPage migrations are SQL scripts that you can use to create or update the database schema. They are entirely optional: you can use SQLPage without them, and manage the database schema yourself with other tools. +If you are new to SQL migrations, please read our [**introduction to database migrations**](https://sql.ophir.dev/your-first-sql-website/migrations.sql). + ## Creating a migration To create a migration, create a file in the `sqlpage/migrations` directory with the following name: diff --git a/sqlpage/migrations/README.md b/sqlpage/migrations/README.md index 38731b04..9ce6c0b1 100644 --- a/sqlpage/migrations/README.md +++ b/sqlpage/migrations/README.md @@ -3,6 +3,8 @@ SQLPage migrations are SQL scripts that you can use to create or update the database schema. They are entirely optional: you can use SQLPage without them, and manage the database schema yourself with other tools. +If you are new to SQL migrations, please read our [**introduction to database migrations**](https://sql.ophir.dev/your-first-sql-website/migrations.sql). + ## Creating a migration To create a migration, create a file in the `sqlpage/migrations` directory with the following name: