dzql 0.5.14 → 0.5.16

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.14",
+  "version": "0.5.16",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -17,7 +17,7 @@
   "files": [
     "bin/**/*.js",
     "src/**/*.js",
-    "src/database/migrations/**/*.sql",
+    "src/database/**/*.sql",
     "docs/**/*.md",
     "docs/examples/*.sql",
     "README.md",

package/src/database/dzql-core.sql

@@ -0,0 +1,161 @@
+-- ============================================================================
+-- DZQL Core - Minimal Foundation
+-- ============================================================================
+-- This is the minimal SQL needed for DZQL compiled mode.
+-- Run: dzql db:init
+-- Or:  psql $DATABASE_URL -f dzql-core.sql
+-- ============================================================================
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE SCHEMA IF NOT EXISTS dzql;
+
+-- Version tracking
+CREATE TABLE IF NOT EXISTS dzql.meta (
+  installed_at TIMESTAMPTZ DEFAULT now(),
+  version TEXT NOT NULL
+);
+
+INSERT INTO dzql.meta (version)
+SELECT '0.5.14'
+WHERE NOT EXISTS (SELECT 1 FROM dzql.meta);
+
+-- Entity registry
+CREATE TABLE IF NOT EXISTS dzql.entities (
+  table_name TEXT PRIMARY KEY,
+  label_field TEXT NOT NULL,
+  searchable_fields TEXT[] NOT NULL,
+  fk_includes JSONB DEFAULT '{}',
+  soft_delete BOOLEAN DEFAULT false,
+  temporal_fields JSONB DEFAULT '{}',
+  notification_paths JSONB DEFAULT '{}',
+  permission_paths JSONB DEFAULT '{}',
+  graph_rules JSONB DEFAULT '{}',
+  field_defaults JSONB DEFAULT '{}',
+  many_to_many JSONB DEFAULT '{}'
+);
+
+-- Function allowlist
+CREATE TABLE IF NOT EXISTS dzql.registry (
+  fn_regproc REGPROC PRIMARY KEY,
+  description TEXT
+);
+
+-- Event audit table
+CREATE TABLE IF NOT EXISTS dzql.events (
+  event_id BIGSERIAL PRIMARY KEY,
+  table_name TEXT NOT NULL,
+  op TEXT NOT NULL,
+  pk JSONB NOT NULL,
+  data JSONB,
+  user_id INT,
+  notify_users INT[],
+  at TIMESTAMPTZ DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS dzql_events_at_idx ON dzql.events (at);
+CREATE INDEX IF NOT EXISTS dzql_events_table_pk_idx ON dzql.events (table_name, pk, at);
+
+-- NOTIFY trigger for real-time updates
+CREATE OR REPLACE FUNCTION dzql.notify_event()
+RETURNS TRIGGER LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM pg_notify('dzql', jsonb_build_object(
+    'event_id', NEW.event_id,
+    'table', NEW.table_name,
+    'op', NEW.op,
+    'pk', NEW.pk,
+    'data', NEW.data,
+    'user_id', NEW.user_id,
+    'at', NEW.at,
+    'notify_users', NEW.notify_users
+  )::text);
+  RETURN NULL;
+END $$;
+
+DROP TRIGGER IF EXISTS dzql_events_notify ON dzql.events;
+CREATE TRIGGER dzql_events_notify
+  AFTER INSERT ON dzql.events
+  FOR EACH ROW EXECUTE FUNCTION dzql.notify_event();
+
+-- Subscribables registry (for compiled subscribables)
+CREATE TABLE IF NOT EXISTS dzql.subscribables (
+  name TEXT PRIMARY KEY,
+  permission_paths JSONB DEFAULT '{}',
+  param_schema JSONB DEFAULT '{}',
+  root_entity TEXT NOT NULL,
+  relations JSONB DEFAULT '{}',
+  scope_tables TEXT[] DEFAULT '{}',
+  created_at TIMESTAMPTZ DEFAULT now()
+);
+
+-- Helper to register entities
+CREATE OR REPLACE FUNCTION dzql.register_entity(
+  p_table_name TEXT,
+  p_label_field TEXT,
+  p_searchable_fields TEXT[],
+  p_fk_includes JSONB DEFAULT '{}',
+  p_soft_delete BOOLEAN DEFAULT false,
+  p_temporal_fields JSONB DEFAULT '{}',
+  p_notification_paths JSONB DEFAULT '{}',
+  p_permission_paths JSONB DEFAULT '{}',
+  p_graph_rules JSONB DEFAULT '{}',
+  p_field_defaults JSONB DEFAULT '{}',
+  p_many_to_many JSONB DEFAULT '{}'
+) RETURNS VOID AS $$
+BEGIN
+  INSERT INTO dzql.entities (
+    table_name, label_field, searchable_fields, fk_includes,
+    soft_delete, temporal_fields, notification_paths, permission_paths,
+    graph_rules, field_defaults, many_to_many
+  ) VALUES (
+    p_table_name, p_label_field, p_searchable_fields, p_fk_includes,
+    p_soft_delete, p_temporal_fields, p_notification_paths, p_permission_paths,
+    p_graph_rules, p_field_defaults, p_many_to_many
+  )
+  ON CONFLICT (table_name) DO UPDATE SET
+    label_field = EXCLUDED.label_field,
+    searchable_fields = EXCLUDED.searchable_fields,
+    fk_includes = EXCLUDED.fk_includes,
+    soft_delete = EXCLUDED.soft_delete,
+    temporal_fields = EXCLUDED.temporal_fields,
+    notification_paths = EXCLUDED.notification_paths,
+    permission_paths = EXCLUDED.permission_paths,
+    graph_rules = EXCLUDED.graph_rules,
+    field_defaults = EXCLUDED.field_defaults,
+    many_to_many = EXCLUDED.many_to_many;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Helper to register subscribables
+CREATE OR REPLACE FUNCTION dzql.register_subscribable(
+  p_name TEXT,
+  p_permission_paths JSONB,
+  p_param_schema JSONB,
+  p_root_entity TEXT,
+  p_relations JSONB DEFAULT '{}'
+) RETURNS VOID AS $$
+DECLARE
+  v_scope_tables TEXT[];
+BEGIN
+  -- Extract scope tables from relations
+  SELECT array_agg(DISTINCT tbl) INTO v_scope_tables
+  FROM (
+    SELECT p_root_entity AS tbl
+    UNION ALL
+    SELECT value->>'entity' AS tbl
+    FROM jsonb_each(p_relations)
+    WHERE value->>'entity' IS NOT NULL
+  ) t
+  WHERE tbl IS NOT NULL;
+
+  INSERT INTO dzql.subscribables (name, permission_paths, param_schema, root_entity, relations, scope_tables)
+  VALUES (p_name, p_permission_paths, p_param_schema, p_root_entity, p_relations, v_scope_tables)
+  ON CONFLICT (name) DO UPDATE SET
+    permission_paths = EXCLUDED.permission_paths,
+    param_schema = EXCLUDED.param_schema,
+    root_entity = EXCLUDED.root_entity,
+    relations = EXCLUDED.relations,
+    scope_tables = EXCLUDED.scope_tables;
+END;
+$$ LANGUAGE plpgsql;