fix(sqlite): emit inline foreign keys, bare-name default schema, direct exec

SQLite can't ALTER TABLE ADD CONSTRAINT, so foreign keys are now written
as inline FOREIGN KEY clauses in CREATE TABLE instead of commented-out
ALTER statements. The default schema (public/main) now produces bare
table names instead of a "public_" prefix; other schemas are still
prefixed to avoid collisions. Also adds direct-to-file execution: the
sqlite writer can now apply generated DDL straight to a .db file via
Metadata["connection_string"], wired into `relspec merge --output-conn`.

pkg/writers/sqlite/README.md

@@ -4,13 +4,14 @@ SQLite DDL (Data Definition Language) writer for RelSpec. Converts database sche
 
 ## Features
 
-- **Automatic Schema Flattening** - SQLite doesn't support PostgreSQL-style schemas, so table names are automatically flattened (e.g., `public.users` → `public_users`)
+- **Schema Flattening** - SQLite doesn't support PostgreSQL-style schemas. Non-default schema names are flattened into table name prefixes (e.g., `auth.sessions` → `auth_sessions`); the default schema (`public`/`main`) is left as bare table names (e.g., `public.users` → `users`)
 - **Type Mapping** - Converts PostgreSQL data types to SQLite type affinities (TEXT, INTEGER, REAL, NUMERIC, BLOB)
 - **Auto-Increment Detection** - Automatically converts SERIAL types and auto-increment columns to `INTEGER PRIMARY KEY AUTOINCREMENT`
 - **Function Translation** - Converts PostgreSQL functions to SQLite equivalents (e.g., `now()` → `CURRENT_TIMESTAMP`)
 - **Boolean Handling** - Maps boolean values to INTEGER (true=1, false=0)
-- **Constraint Generation** - Creates indexes, unique constraints, and documents foreign keys
+- **Constraint Generation** - Creates indexes, unique constraints, and inline `FOREIGN KEY` clauses in `CREATE TABLE`
 - **Identifier Quoting** - Properly quotes identifiers using double quotes
+- **Direct Execution** - Can execute the generated DDL directly against a `.db` file instead of writing a `.sql` script (see below)
 
 ## Usage
 
@@ -30,15 +31,26 @@ relspec convert --from dbml --from-path schema.dbml \
 
 ### Multi-Schema Databases
 
-SQLite doesn't support schemas, so multi-schema databases are automatically flattened:
+SQLite doesn't support schemas, so multi-schema databases are automatically flattened. The default schema (`public`/`main`) keeps bare table names; other schemas are prefixed to avoid collisions:
 
 ```bash
 # Input has auth.users and public.posts
-# Output will have auth_users and public_posts
+# Output will have auth_users and posts
 relspec convert --from json --from-path multi_schema.json \
                 --to sqlite --to-path flattened.sql
 ```
 
+### Direct Execution Against a Database File
+
+`relspec merge` can execute the generated DDL directly against a SQLite file instead of writing a `.sql` script, by passing the file path as `--output-conn`:
+
+```bash
+relspec merge --source dbml --source-path schema.dbml \
+              --output sqlite --output-conn ./app.db
+```
+
+Passing `--output-conn` opens `./app.db` and applies the schema directly; passing `--output-path` instead (or omitting `--output-conn`) writes a `.sql` script as before.
+
 ## Type Mapping
 
 | PostgreSQL Type | SQLite Affinity | Examples |
@@ -87,17 +99,17 @@ CREATE TABLE "users" (
 
 ## Foreign Keys
 
-Foreign keys are generated as commented-out ALTER TABLE statements for reference:
+SQLite has no `ALTER TABLE ADD CONSTRAINT`, so foreign keys are generated as inline `FOREIGN KEY` clauses inside `CREATE TABLE`, exactly as SQLite requires:
 
 ```sql
--- Foreign key: fk_posts_user_id
--- ALTER TABLE "posts" ADD CONSTRAINT "posts_fk_posts_user_id"
---   FOREIGN KEY ("user_id")
---   REFERENCES "users" ("id");
--- Note: Foreign keys should be defined in CREATE TABLE for better SQLite compatibility
+CREATE TABLE "posts" (
+    "id" INTEGER PRIMARY KEY AUTOINCREMENT,
+    "user_id" INTEGER NOT NULL,
+    FOREIGN KEY ("user_id") REFERENCES "users" ("id") ON DELETE CASCADE
+);
 ```
 
-For production use, define foreign keys directly in the CREATE TABLE statement or execute the ALTER TABLE commands after creating all tables.
+`PRAGMA foreign_keys = ON;` is emitted at the top of the output (and executed first in direct-execution mode) so these constraints are actually enforced.
 
 ## Constraints
 
@@ -112,11 +124,10 @@ Generated SQL follows this order:
 
 1. Header comments
 2. `PRAGMA foreign_keys = ON;`
-3. CREATE TABLE statements (sorted by schema, then table)
+3. CREATE TABLE statements (sorted by schema, then table), with primary keys and foreign keys defined inline
 4. CREATE INDEX statements
 5. CREATE UNIQUE INDEX statements (for unique constraints)
 6. Check constraint comments
-7. Foreign key comments
 
 ## Example
 
@@ -145,7 +156,7 @@ CREATE TABLE public.posts (
 -- SQLite Database Schema
 -- Database: mydb
 -- Generated by RelSpec
--- Note: Schema names have been flattened (e.g., public.users -> public_users)
+-- Note: SQLite has no schema concept; non-default schema names are flattened into table name prefixes (e.g., auth.sessions -> auth_sessions)
 
 -- Enable foreign key constraints
 PRAGMA foreign_keys = ON;
@@ -160,22 +171,17 @@ CREATE TABLE "auth_users" (
 
 CREATE UNIQUE INDEX "auth_users_users_username_key" ON "auth_users" ("username");
 
--- Schema: public (flattened into table names)
-
-CREATE TABLE "public_posts" (
+CREATE TABLE "posts" (
     "id" INTEGER PRIMARY KEY AUTOINCREMENT,
     "user_id" INTEGER NOT NULL,
     "title" TEXT NOT NULL,
-    "published" INTEGER DEFAULT 0
+    "published" INTEGER DEFAULT 0,
+    FOREIGN KEY ("user_id") REFERENCES "auth_users" ("id")
 );
-
--- Foreign key: posts_user_id_fkey
--- ALTER TABLE "public_posts" ADD CONSTRAINT "public_posts_posts_user_id_fkey"
---   FOREIGN KEY ("user_id")
---   REFERENCES "auth_users" ("id");
--- Note: Foreign keys should be defined in CREATE TABLE for better SQLite compatibility
 ```
 
+Note that `public.posts` becomes bare `posts` (the default schema isn't prefixed), while `auth.users` becomes `auth_users` (a non-default schema is), and the foreign key to `auth_users` is defined inline rather than as a separate statement.
+
 ## Programmatic Usage
 
 ```go
@@ -208,8 +214,9 @@ func main() {
 
 ## Notes
 
-- Schema flattening is **always enabled** for SQLite output (cannot be disabled)
+- Schema flattening is **always enabled** for SQLite output (cannot be disabled); the default schema (`public`/`main`) produces bare table names, other schemas are prefixed
 - Constraint and index names are prefixed with the flattened table name to avoid collisions
 - Generated SQL is compatible with SQLite 3.x
-- Foreign key constraints require `PRAGMA foreign_keys = ON;` to be enforced
+- Foreign key constraints require `PRAGMA foreign_keys = ON;` to be enforced, which is emitted (and, in direct-execution mode, run) before any `CREATE TABLE`
+- Setting `Metadata["connection_string"]` to a `.db` file path (or passing `--output-conn` to `relspec merge`) executes the DDL directly against that file instead of writing a `.sql` script
 - For complex schemas, review and test the generated SQL before use in production