dzql 0.5.13 → 0.5.15

package/README.md

@@ -2,24 +2,29 @@
 
 PostgreSQL-powered framework with automatic CRUD operations, live query subscriptions, and real-time WebSocket synchronization.
 
-## Documentation
-
-- **[Documentation Hub](docs/)** - Complete documentation index
-- **[Getting Started Tutorial](docs/getting-started/tutorial.md)** - Complete tutorial with working todo app
-- **[API Reference](docs/reference/api.md)** - Complete API documentation
-- **[Live Query Subscriptions](docs/getting-started/subscriptions-quick-start.md)** - Real-time denormalized documents
-- **[Compiler Documentation](docs/compiler/)** - Entity compilation guide and coding standards
-- **[Claude Guide](docs/for-ai/claude-guide.md)** - Development guide for AI assistants
-- **[Venues Example](../venues/)** - Full working application
-
-## Quick Install
+## Quick Start
 
 ```bash
 bun add dzql
-# or
-npm install dzql
+
+export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
+bunx dzql db:init
+
+bunx dzql compile entities.sql -o init_db/
+psql $DATABASE_URL -f init_db/*.sql
 ```
 
+See **[Quick Start Guide](docs/getting-started/quickstart.md)** for the full 5-minute setup.
+
+## Documentation
+
+- **[Quick Start](docs/getting-started/quickstart.md)** - 5-minute setup
+- **[Full Tutorial](docs/getting-started/tutorial.md)** - Complete tutorial with working app
+- **[API Reference](docs/reference/api.md)** - Complete API documentation
+- **[Subscriptions](docs/getting-started/subscriptions-quick-start.md)** - Real-time denormalized documents
+- **[Compiler Guide](docs/compiler/)** - Entity compilation and coding standards
+- **[Claude Guide](docs/for-ai/claude-guide.md)** - Development guide for AI assistants
+
 ## Quick Example
 
 ```javascript

package/bin/cli.js

@@ -16,8 +16,8 @@ switch (command) {
   case 'dev':
     console.log('🚧 Dev command coming soon');
     break;
-  case 'db:up':
-    console.log('🚧 Database commands coming soon');
+  case 'db:init':
+    await runDbInit(args);
     break;
   case 'compile':
     await runCompile(args);
@@ -44,25 +44,24 @@ switch (command) {
     console.log(`
 DZQL CLI
 
-Usage:
-  dzql create <app-name>        Create a new DZQL application
-  dzql dev                      Start development server
-  dzql db:up                    Start PostgreSQL database
-  dzql db:down                  Stop PostgreSQL database
-  dzql compile <input>          Compile entity definitions to SQL
+Quick Start:
+  1. dzql db:init              Initialize database with DZQL core (~70 lines SQL)
+  2. dzql compile app.sql      Compile your entities to PostgreSQL functions
+  3. psql < compiled/*.sql     Apply the compiled SQL to your database
+
+Commands:
+  dzql db:init                  Initialize database with DZQL core schema
+  dzql compile <input>          Compile entity definitions to SQL functions
 
   dzql migrate:new <name>       Create a new migration file
   dzql migrate:up               Apply pending migrations
-  dzql migrate:down             Rollback last migration
   dzql migrate:status           Show migration status
 
   dzql --version                Show version
 
 Examples:
-  dzql create my-venue-app
+  dzql db:init
   dzql compile entities/blog.sql -o init_db/
-  dzql migrate:new add_user_avatars
-  dzql migrate:up
 `);
 }
 
@@ -666,3 +665,63 @@ async function runMigrateStatus(args) {
     await sql.end();
   }
 }
+
+// ============================================================================
+// Database Initialization
+// ============================================================================
+
+async function runDbInit(args) {
+  const databaseUrl = process.env.DATABASE_URL;
+
+  if (!databaseUrl) {
+    console.error('Error: DATABASE_URL environment variable not set');
+    console.log('Set it to your PostgreSQL connection string:');
+    console.log('  export DATABASE_URL="postgresql://user:pass@localhost:5432/dbname"');
+    process.exit(1);
+  }
+
+  console.log('\n🚀 DZQL Database Initialization\n');
+
+  const sql = postgres(databaseUrl);
+
+  try {
+    console.log('🔌 Connected to database');
+
+    // Read the core SQL file
+    const coreSQL = readFileSync(
+      new URL('../src/database/dzql-core.sql', import.meta.url),
+      'utf-8'
+    );
+
+    console.log('📦 Applying DZQL core schema...');
+    await sql.unsafe(coreSQL);
+
+    // Check version
+    const version = await sql`SELECT version FROM dzql.meta ORDER BY installed_at DESC LIMIT 1`;
+    console.log(`✅ DZQL core initialized (v${version[0]?.version || 'unknown'})`);
+
+    console.log(`
+Next steps:
+  1. Create your entity definitions (schema + DZQL registrations)
+  2. Compile: dzql compile entities.sql -o compiled/
+  3. Apply:  psql $DATABASE_URL -f compiled/*.sql
+
+Example entity file (entities.sql):
+  -- Schema
+  CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    email TEXT UNIQUE NOT NULL,
+    name TEXT
+  );
+
+  -- DZQL Registration
+  SELECT dzql.register_entity('users', 'name', ARRAY['name', 'email']);
+`);
+
+  } catch (err) {
+    console.error('❌ Initialization failed:', err.message);
+    process.exit(1);
+  } finally {
+    await sql.end();
+  }
+}

package/docs/getting-started/quickstart.md

@@ -0,0 +1,125 @@
+# DZQL Quick Start
+
+Get a real-time API with automatic CRUD in 5 minutes.
+
+## Prerequisites
+
+- PostgreSQL (local or Docker)
+- Bun or Node.js 18+
+
+## 1. Install
+
+```bash
+mkdir my-app && cd my-app
+bun init -y
+bun add dzql
+```
+
+## 2. Start PostgreSQL
+
+```bash
+docker run -d --name dzql-db \
+  -e POSTGRES_USER=dzql \
+  -e POSTGRES_PASSWORD=dzql \
+  -e POSTGRES_DB=dzql \
+  -p 5432:5432 \
+  postgres:latest
+
+export DATABASE_URL="postgresql://dzql:dzql@localhost:5432/dzql"
+```
+
+## 3. Initialize Database
+
+```bash
+bunx dzql db:init
+```
+
+## 4. Define Entities
+
+Create `entities.sql`:
+
+```sql
+-- Schema
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  email TEXT UNIQUE NOT NULL,
+  name TEXT,
+  created_at TIMESTAMPTZ DEFAULT now()
+);
+
+CREATE TABLE todos (
+  id SERIAL PRIMARY KEY,
+  title TEXT NOT NULL,
+  completed BOOLEAN DEFAULT false,
+  user_id INT REFERENCES users(id),
+  created_at TIMESTAMPTZ DEFAULT now()
+);
+
+-- Register with DZQL
+SELECT dzql.register_entity('users', 'name', ARRAY['name', 'email']);
+SELECT dzql.register_entity('todos', 'title', ARRAY['title']);
+```
+
+## 5. Compile
+
+```bash
+bunx dzql compile entities.sql -o init_db/
+```
+
+## 6. Apply
+
+```bash
+psql $DATABASE_URL -f init_db/001_schema.sql
+psql $DATABASE_URL -f init_db/users.sql
+psql $DATABASE_URL -f init_db/todos.sql
+```
+
+## 7. Create Server
+
+Create `index.js`:
+
+```javascript
+import { createServer } from 'dzql/server';
+
+createServer({ port: 3000 });
+console.log('Server running at http://localhost:3000');
+```
+
+## 8. Use
+
+```javascript
+import { WebSocketManager } from 'dzql/client';
+
+const ws = new WebSocketManager();
+await ws.connect();
+
+// Auto-generated CRUD
+const todo = await ws.api.save.todos({ title: 'Buy milk' });
+const todos = await ws.api.search.todos({});
+await ws.api.save.todos({ id: todo.id, completed: true });
+await ws.api.delete.todos({ id: todo.id });
+
+// Real-time updates
+ws.onBroadcast((method, params) => {
+  console.log('Change:', method, params);
+});
+```
+
+## What You Get
+
+For each entity:
+- `get_<entity>(user_id, id)` - Get by ID
+- `save_<entity>(user_id, data)` - Create or update
+- `delete_<entity>(user_id, id)` - Delete
+- `search_<entity>(user_id, filters, search, sort, page, limit)` - Search
+
+Plus:
+- Real-time updates via WebSocket
+- Permission checks in SQL
+- Audit trail in `dzql.events`
+
+## Next Steps
+
+- [Full Tutorial](./tutorial.md) - Complete walkthrough
+- [Subscriptions](./subscriptions-quick-start.md) - Real-time denormalized documents
+- [API Reference](../reference/api.md) - All operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",

package/src/server/index.js

@@ -12,11 +12,11 @@ export { createMCPRoute } from "./mcp.js";
 /**
  * Process subscription updates when a database event occurs
  * Forwards atomic events to affected subscriptions for client-side patching
- * @param {Object} event - Database event {table, op, pk, before, after}
+ * @param {Object} event - Database event {table, op, pk, data}
  * @param {Function} broadcast - Broadcast function from WebSocket handlers
  */
 async function processSubscriptionUpdates(event, broadcast) {
-  const { table, op, pk, before, after } = event;
+  const { table, op, pk, data } = event;
 
   // Get all active subscriptions grouped by subscribable
   const subscriptionsByName = getSubscriptionsBySubscribable();
@@ -39,9 +39,10 @@ async function processSubscriptionUpdates(event, broadcast) {
       }
 
       // Ask PostgreSQL which subscription instances are affected
+      // Pass data for both old/new - COALESCE in the function handles it
       const result = await sql.unsafe(
         `SELECT ${subscribableName}_affected_documents($1, $2, $3, $4) as affected`,
-        [table, op, before, after]
+        [table, op, data, data]
       );
 
       const affectedParamSets = result[0]?.affected;
@@ -70,8 +71,7 @@ async function processSubscriptionUpdates(event, broadcast) {
                     table,
                     op,
                     pk,
-                    data: after,
-                    before
+                    data
                   }
                 }
               });