include more default files and folders in release assets

.github/workflows/release.yml

@@ -45,14 +45,17 @@ jobs:
     needs: [build, build-aws]
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/checkout@v3
       - uses: actions/download-artifact@v3
       - run: |
+          rm -rf sqlpage/templates/*.handlebars;
           chmod +x sqlpage*/sqlpage;
           mv 'sqlpage macos-latest/sqlpage' sqlpage.bin;
-          tar --create --file sqlpage-macos.tgz --gzip sqlpage.bin;
+          tar --create --file sqlpage-macos.tgz --gzip sqlpage.bin sqlpage/sqlpage.json sqlpage/migrations sqlpage/templates;
           mv 'sqlpage ubuntu-20.04/sqlpage' sqlpage.bin;
-          tar --create --file sqlpage-linux.tgz --gzip sqlpage.bin
-          cd 'sqlpage windows-latest' && zip -r sqlpage-windows.zip *.exe
+          tar --create --file sqlpage-linux.tgz --gzip sqlpage.bin sqlpage/migrations sqlpage/templates;
+          mv 'sqlpage windows-latest/sqlpage.exe' .
+          zip -r sqlpage-windows.zip sqlpage.exe sqlpage/migrations sqlpage/templates;
       - name: Create Release
         id: create_release
         uses: softprops/action-gh-release@v1

sqlpage/migrations/README.md

@@ -0,0 +1,39 @@
+# SQLPage migrations
+
+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.
+
+## Creating a migration
+
+To create a migration, create a file in the `sqlpage/migrations` directory with the following name:
+
+```
+<version>_<name>.sql
+```
+
+Where `<version>` is a number that represents the version of the migration, and `<name>` is a name for the migration.
+For example, `001_initial.sql` or `002_add_users.sql`.
+
+When you need to update the database schema, always create a **new** migration file with a new version number
+that is greater than the previous one.
+Use commands like `ALTER TABLE` to update the schema declaratively instead of modifying the existing `CREATE TABLE`
+statements.
+
+If you try to edit an existing migration, SQLPage will not run it again, will detect
+
+## Running migrations
+
+Migrations that need to be applied are run automatically when SQLPage starts.
+You need to restart SQLPage each time you create a new migration.
+
+## How does it work?
+
+SQLPage keeps track of the migrations that have been applied in a table called `_sqlx_migrations`.
+This table is created automatically when SQLPage starts for the first time, if you create migration files.
+If you don't create any migration files, SQLPage will never touch the database schema on its own.
+
+When SQLPage starts, it checks the `_sqlx_migrations` table to see which migrations have been applied.
+It checks the `sqlpage/migrations` directory to see which migrations are available.
+If the checksum of a migration file is different from the checksum of the migration that has been applied,
+SQLPage will return an error and refuse to start.
+If you end up in this situation, you can remove the `_sqlx_migrations` table: all your old migrations will be reapplied, and SQLPage will start again.

sqlpage/templates/README.md

@@ -0,0 +1,19 @@
+# SQLPage component templates
+
+SQLPage templates are handlebars[^1] files that are used to render the results of SQL queries.
+
+[^1]: https://handlebarsjs.com/
+
+## Default components
+
+SQLPage comes with a set of default[^2] components that you can use without having to write any code.
+These are documented on https://sql.ophir.dev/components.sql
+
+## Custom components
+
+You can write your own component templates and place them in the `sqlpage/templates` directory.
+To override a default component, create a file with the same name as the default component.
+If you want to start from an existing component, you can copy it from the `sqlpage/templates` directory
+in the SQLPage source code[^2].
+
+[^2]: A simple component to start from: https://github.com/lovasoa/SQLpage/blob/main/sqlpage/templates/code.handlebars