links to migrations

sqlpage · May 23, 2024 · ea14c96 · ea14c96
1 parent 0ea7beb
commit ea14c96
Show file tree

Hide file tree

Showing 7 changed files with 18 additions and 19 deletions.
diff --git 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
@@ -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 → ...site/your-first-sql-website/migrations.md b/examples/official-site/migrations.sql → ...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/).
diff --git a/examples/official-site/your-first-sql-website/migrations.sql 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
@@ -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
@@ -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
@@ -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: