genesis-stack 1.1.3 → 1.1.4

package/README.md

@@ -49,6 +49,11 @@ Do not add technology-specific knowledge or dependencies to
 `genesis-compiler`, and do not create one catalog package per framework unless
 the single-catalog model becomes genuinely unworkable.
 
+The `sqlite` piece covers persistent filenames, transactions, migrations and
+consistent backups. `laravel-sqlite` adds Laravel's `DB_DATABASE` filename
+binding and `DB_CONNECTION=sqlite` default. Hosts own provisioning; applications
+own schema changes and preservation of existing data during adoption.
+
 ## Resource-estimate proposals
 
 JSKIT proposes Vibe64's optional `Resource estimates` section for its concrete

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-stack",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "The optional curated technology Stack catalog for Genesis projects.",
   "type": "module",
   "repository": {

package/stacks/pieces/laravel-mysql.md

@@ -12,6 +12,7 @@ Laravel MySQL connection, migration, Eloquent, and database environment conventi
 ## Conflicts
 
 - `laravel-postgresql`
+- `laravel-sqlite`
 
 ## Environment defaults
 

package/stacks/pieces/laravel-postgresql.md

@@ -12,6 +12,7 @@ Laravel PostgreSQL connection, migration, Eloquent, and database environment con
 ## Conflicts
 
 - `laravel-mysql`
+- `laravel-sqlite`
 
 ## Environment defaults
 

package/stacks/pieces/laravel-sqlite.md

@@ -0,0 +1,57 @@
+# Stack piece: laravel-sqlite
+
+## Description
+
+Laravel SQLite connection, migration, and database filename conventions.
+
+## Requires
+
+- `laravel`
+- `sqlite`
+
+## Conflicts
+
+- `laravel-mysql`
+- `laravel-postgresql`
+
+## Environment defaults
+
+- Default `DB_CONNECTION`: `sqlite`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "sqlite",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_DATABASE"
+      },
+      "preferred": true
+    }
+  ]
+}
+```
+
+## Guidance
+
+- Confirm `config/database.php` uses `DB_DATABASE` for the SQLite filename and
+  `DB_CONNECTION` for the driver. Keep the project Resource contract aligned
+  with any application-specific names. Laravel expects an absolute filename;
+  preserve a host-supplied value. For standalone setup, create the selected file
+  only if absent and configure its absolute path before migration.
+- Verify the selected PHP runtime includes `pdo_sqlite`. Use the application's
+  migrations and seeders, and declare their exact commands in the project setup
+  and deployment contracts. Repeated setup must preserve records, the migration
+  ledger, and the existing application key; do not use `migrate:fresh` or
+  regenerate keys as routine preparation.
+- Consult the installed Laravel version's SQLite configuration documentation at
+  `https://laravel.com/docs/database#sqlite-configuration`.
+
+## Adoption
+
+- Read the database configuration and existing environment before declaring
+  readiness. Preserve any existing SQLite data when adopting managed storage.
+  Verify migrations on the configured file and keep test connections separate.

package/stacks/pieces/laravel.md

@@ -55,7 +55,7 @@ conventions. Authoritative framework documentation: https://laravel.com/docs/
 - Record actual Composer and frontend installation, test, build, development,
   queue, scheduler, migration, and production operations. Do not assume the
   catalog proposal matches an older application.
-- When the app uses MySQL or PostgreSQL, select the matching Laravel database
+- When the app uses MySQL, PostgreSQL or SQLite, select the matching Laravel database
   integration so its conventional environment names become explicit.
 
 ## Environment files

package/stacks/pieces/sqlite.md

@@ -0,0 +1,37 @@
+# Stack piece: sqlite
+
+## Description
+
+SQLite file-backed persistence, migrations, and backup conventions.
+
+## Requires
+
+- Nothing.
+
+## Guidance
+
+- Use the application's existing SQLite driver and migration owner. Declare a
+  persistent database filename through the `database` resource semantic and
+  the environment name the application actually reads. A driver selector such
+  as `DB_CONNECTION=sqlite` is configuration, not a database filename.
+- Keep durable database files outside disposable build and release directories.
+  A host may supply a persistent filename; do not replace that value with a
+  repository-relative default or recreate an existing database during setup.
+- Use transactions, foreign-key enforcement, and bounded busy handling. Prove
+  concurrent writes using SQLite itself; a different engine does not establish
+  SQLite's locking behavior.
+- Use SQLite's online backup API or `VACUUM INTO` for a consistent backup of a
+  running database, including committed WAL data. Do not copy only the main file
+  while writers are active. Validate backups and prove restoration before
+  removing the original. See `https://www.sqlite.org/backup.html`.
+- Keep test databases separate from development and production. In-memory
+  databases are useful for tests but are not persistent application resources.
+
+## Adoption
+
+- Identify the configured database filename, driver, migration ledger, journal
+  mode, and any existing data before changing configuration. Preserve a verified
+  snapshot before moving data to a host-managed filename. Do not silently switch
+  an existing application to an empty database.
+- Distinguish fresh creation from migrations of retained data. Record app-owned
+  migration and optional seed commands without resetting the database.