SED Documentation

v1.0.5
Back to HomepageGitHub

Quick Navigation

Getting StartedCore ConceptsCLI CommandsAI IntegrationAPI ReferenceBusiness RulesDatabase SupportAdvanced UsageExamples & Use Cases

Getting Started with SED

SED (Semantic Entity Designs) is a production-grade platform that transforms your database into an AI-ready semantic layer with enterprise security, automatic business context resolution, and sophisticated guardrails. This guide shows you how to deploy a secure AI-database integration in minutes.

Installation

# Install SED globally
npm install -g sed-cli
# Or use npx (recommended)
npx sed-cli --version

Production Setup Guide

Step 1: Initialize with Auto-Detection

npx sedql init --force

Interactive setup with automatic domain detection (ecommerce, SaaS, finance, healthcare), connection pooling, business context resolution, and security configuration.

Step 2: Deploy Secure API Endpoints

# Environment Configuration
SED_REQUIRE_API_KEY=true
SED_API_KEY=your_secure_api_key
SED_RATE_LIMIT_ENABLED=true
SED_ENCRYPTION_ENABLED=true
# Endpoints automatically available:
✓ /api/schema - Get business context
✓ /api/plan - AI creates execution plan
✓ /api/approve - Human approval workflow
✓ /api/execute - Secure execution with guardrails

Step 3: AI Agent Integration

# 1. Agent creates plan (with risk assessment)
curl -H "x-sed-api-key: key" -H "Content-Type: application/json" \
-d '{"question":"Show top customers by revenue"}' \
http://localhost:3000/api/plan
# 2. Human approves (shows business context)
curl -H "x-sed-api-key: key" -H "Content-Type: application/json" \
-d '{"plan_id":"uuid-here"}' \
http://localhost:3000/api/approve
# 3. System executes safely (PII detection, access control)
curl -H "x-sed-api-key: key" -H "Content-Type: application/json" \
-d '{"plan_id":"uuid-here"}' \
http://localhost:3000/api/execute

Plan → Approve → Execute workflow with encrypted plan storage, risk assessment, and automatic business context resolution (user_id becomes "Customer Identifier").

Configuration

SED uses a simple JSON configuration file to manage your database connections and settings.

// sed.config.json
{
"database": {
"type": "postgres",
"host": "localhost",
"port": 5432,
"database": "myapp",
"username": "postgres"
}
"rules": {
"auto_generate": true,
"enabled_by_default": true
}
}

Production Features Activated

After running sedql init, SED deploys a production-grade platform with enterprise security, intelligent business context, and sophisticated monitoring.

Enterprise Features Enabled

Security & Monitoring

• Rate limiting & account lockout
• Encrypted plan storage
• Connection pooling & health checks
• Structured error handling (9 types)
• Schema change detection

Business Intelligence

• Domain detection (ecommerce, SaaS, finance)
• Technical-to-business mapping
• Risk assessment (low/medium/high)
• PII detection & protection
• Business rule auto-generation

Production Setup Complete

✓ Connected to PostgreSQL with pooling
✓ Domain detected: ecommerce
✓ Business context: 15 tables → 8 entities
✓ Security: Rate limiting, encryption enabled
✓ API endpoints: /plan, /approve, /execute
✓ Monitoring: Health checks, error tracking
✓ Business mapping: user_id → Customer ID
🚀 Production-ready AI-database platform deployed!

Core Concepts

SED is a community-first platform that provides AI with the infrastructure and business understanding it needs to work intelligently with your data. It's not a wrapper that uses AI - it's a tool that helps AI understand your business context while keeping you in control.

AI Infrastructure & Control

SED provides AI with the infrastructure it needs while keeping you in control. This includes rate limiting, PII detection, access control, and secure workflows that empower AI without compromising your data.

What SED Provides to AI:

  • • Business Context: Understanding of your domain and business terminology
  • • Data Access Control: Safe, controlled access to your database
  • • Security Infrastructure: PII protection, rate limiting, and audit trails
  • • Business Rules: Context about your data relationships and constraints

Business Intelligence for AI

SED automatically detects your business domain and maps technical database terms to business language. This helps AI understand the context and meaning behind your data.

Example: Technical to Business Mapping

Technical Names:

  • • user_id
  • • order_date
  • • product_sku
  • • revenue_amount

Business Names:

  • • Customer ID
  • • Purchase Date
  • • Product Code
  • • Sales Revenue

Community-First Architecture

SED runs entirely on your infrastructure with no cloud dependencies. Your data never leaves your machines, ensuring community ownership and data sovereignty.

Community Benefits:

  • • Data Sovereignty: Your data stays on your infrastructure
  • • No Vendor Lock-in: Run SED anywhere, anytime
  • • Community Ownership: Open source with community-driven development
  • • Local Control: All processing happens on your machines

CLI Commands

Essential CLI commands for production deployment, monitoring, and management of your AI-database platform.

sedql init

Production setup with automatic domain detection, connection pooling, security configuration, and business context resolution.

Usage

npx sedql init --force

Production Features

  • • Auto-Detection - Domain (ecommerce, SaaS, finance, healthcare)
  • • Connection Pooling - Managed connections with health monitoring
  • • Security Setup - Rate limiting, encryption, API key generation
  • • Business Context - Technical-to-business name mapping
  • • API Endpoints - /api/plan, /api/approve, /api/execute
  • • Monitoring - Error tracking, schema change detection

Production Output

✓ Connected to PostgreSQL with pooling
✓ Domain detected: ecommerce
✓ Business context: 15 tables → 8 entities
✓ Security: Rate limiting, encryption enabled
✓ API endpoints: /plan, /approve, /execute
✓ Monitoring: Health checks, error tracking
🚀 Production-ready AI-database platform deployed!

sedql build

Build or rebuild your semantic layer. Use this when your database schema changes or you want to regenerate everything.

Usage

npx sedql build

What it does

  • • Discovers all tables, views, and schemas
  • • Analyzes foreign key relationships
  • • Detects business logic patterns
  • • Generates semantic mapping
  • • Auto-generates business rules
  • • Creates semantic-layer.json

sedql query

Query your database using natural language. SED validates your request against business rules and executes the query.

Usage

npx sedql query "show me customer orders from last month"

What it does

  • • Validates query against business rules
  • • Applies security and compliance checks
  • • Executes the query safely
  • • Returns results with validation status

Output

✓ Query validated successfully
ℹ Applied business rules
Results: [customer data...]

Note: Natural language to SQL translation is currently in development. The query command validates and executes queries but uses basic pattern matching for now.

sedql validate

Validate your semantic layer and check for potential issues or improvements.

Usage

npx sedql validate

What it checks

  • • Semantic layer file exists and is valid JSON
  • • All referenced entities are present
  • • Relationship mappings are consistent
  • • Business logic patterns are properly applied
  • • Business rules are valid
  • • Database connection is still valid

sedql rules

Manage business rules for your semantic layer. List, enable, disable, add custom rules, and configure rules.

Usage

npx sedql rules --list
npx sedql rules --add custom-rules.json
npx sedql rules --remove rule-id
npx sedql rules --disable pii-protection
npx sedql rules --enable pii-protection

Filtering Options

npx sedql rules --list --type access_policy
npx sedql rules --list --severity critical
npx sedql rules --list --format json

Additional Commands

sedql sync

Sync semantic layer with database changes.

npx sedql sync --force

sedql context

Get semantic context for AI applications.

npx sedql context

sedql export

Export your semantic layer and configuration in various formats.

npx sedql export --format json

sedql import

Import semantic layer configuration from a file.

npx sedql import config.json

sedql status

Show current SED status and configuration details.

npx sedql status

sedql detect-changes

Detect and analyze schema changes in your database.

npx sedql detect-changes --verbose

sedql diagnose

Diagnose database access and permission issues.

npx sedql diagnose

AI Integration Guide

SED provides a production-grade Plan → Approve → Execute workflow for AI agents. This guide shows you how to integrate the secure AI agent workflow with any AI platform, featuring encrypted plan storage, risk assessment, and automatic business context resolution.

Integration Overview

AI Agent Workflow Architecture

SED provides a secure, three-step workflow that separates AI planning from execution:

  • • Plan - AI creates execution plan with business context and risk assessment
  • • Approve - Human or system approval with full visibility into what will be executed
  • • Execute - Secure execution with PII detection, access control, and audit logging
  • • Monitor - Real-time health checks, error tracking, and schema change detection

Production Workflow

AI Agent → POST /api/plan → Encrypted Storage
Human/System → POST /api/approve → Risk Assessment
SED Engine → POST /api/execute → Safe Database Access
Features: Rate limiting, connection pooling, business context mapping

ChatGPT Agent Integration

Production Agent Implementation

Integrate ChatGPT with SED's secure plan-approve-execute workflow for production AI-database interactions.

# Get your semantic layer context
npx sedql export-context > semantic-context.json
# Use in agent system prompt (no end-user NL UI)
const systemPrompt = `You have access to a database with the following structure: ${semanticContext}`;

Example ChatGPT Integration

import { openai } from 'openai';
import { readFileSync } from 'fs';
import { execSync } from 'child_process';
// Get semantic context from SED
const semanticContext = execSync('npx sedql export-context').toString();
// Create ChatGPT client
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
// Agent proposes a plan (no human NL box)
const response = await openai.chat.completions.create({
model: 'gpt-4',
messages: [
{
role: 'system',
content: `You can use SED endpoints to plan → approve → execute under rules. Schema: ${semanticContext}.`
},
{
role: 'user',
content: 'Show me total revenue by customer for Q1 2024'
}
]
});

Method 2: Function Calling Integration

For more advanced integration, use ChatGPT's function calling to validate queries through SED before execution.

// Define function for query validation
const functions = [
{
name: 'validate_query',
description: 'Validate a SQL query against business rules',
parameters: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'SQL query to validate'
}
},
required: ['query']
}
}
];

LangChain Integration

Custom Tool Integration

Create a custom LangChain tool that uses SED for semantic search and query validation.

import { Tool } from 'langchain/tools';
import { execSync } from 'child_process';
class SEDTool extends Tool {
name = 'sed_semantic_search';
description = 'Search the semantic layer for entities, attributes, and relationships';
async _call(input: string) {
try {
const result = execSync(`npx sedql search "${input}"`).toString();
return result;
} catch (error) {
return `Error searching semantic layer: ${error.message}`;
}
}
}

Using SED Tool in LangChain

import { ChatOpenAI } from 'langchain/chat_models';
import { initializeAgentExecutorWithOptions } from 'langchain/agents';
const model = new ChatOpenAI({ temperature: 0 });
const sedTool = new SEDTool();
const executor = await initializeAgentExecutorWithOptions([
sedTool
], model, {
agentType: 'chat-zero-shot-react-description',
verbose: true
});
const result = await executor.invoke({
input: 'Find all customer-related entities and their revenue metrics'
});

Custom AI Integration

REST API Integration

For custom AI applications, you can create a REST API wrapper around SED commands.

import express from 'express';
import { execSync } from 'child_process';
const app = express();
// Search semantic layer
app.get('/api/semantic/search', async (req, res) => {
try {
const { query } = req.query;
const result = execSync(`npx sedql search "${query}"`).toString();
res.json({ success: true, data: result });
} catch (error) {
res.status(500).json({ error: error.message });
}
});
// Validate query
app.post('/api/validate-query', async (req, res) => {
try {
const { query } = req.body;
const result = execSync(`npx sedql validate-query "${query}"`).toString();
res.json({ success: true, data: result });
} catch (error) {
res.status(500).json({ error: error.message });
}
});

Best Practices

Performance Optimization

  • • Cache semantic layer context to reduce CLI calls
  • • Use batch operations for multiple queries
  • • Implement connection pooling for database access
  • • Monitor query execution times and optimize slow queries

Security Considerations

  • • Always validate queries before execution
  • • Use business rules to enforce access controls
  • • Implement rate limiting for API endpoints
  • • Log all AI-generated queries for audit trails

Error Handling

  • • Implement graceful fallbacks for SED failures
  • • Provide meaningful error messages to users
  • • Retry failed operations with exponential backoff
  • • Monitor and alert on integration failures

Maintenance

  • • Regularly update semantic layer when schema changes
  • • Review and update business rules periodically
  • • Monitor AI query patterns and optimize rules
  • • Keep SED and dependencies up to date

API Reference

Enterprise Authentication & Security

Production-grade security with rate limiting, account lockout, and timing-safe authentication.

Security Features

  • • Rate Limiting - Configurable requests per minute per client
  • • Account Lockout - Automatic lockout after failed attempts
  • • Timing-Safe Comparison - Prevents timing attacks on API keys
  • • Client Tracking - IP + User-Agent based identification
# Production Environment
SED_REQUIRE_API_KEY=true
SED_API_KEY=your_secure_256_bit_key
SED_RATE_LIMIT_ENABLED=true
SED_RATE_LIMIT_REQUESTS=100 # per minute
SED_ACCOUNT_LOCKOUT_ENABLED=true
# Request headers
x-sed-api-key: your_secure_256_bit_key
Content-Type: application/json

GET /api/schema

Returns the semantic mapping (entities, attributes, relationships).

curl -H "x-sed-api-key: $KEY" http://localhost:3000/api/schema

GET /api/rules

Returns active business rules/guardrails.

curl -H "x-sed-api-key: $KEY" http://localhost:3000/api/rules

POST /api/plan

AI creates execution plan with business context resolution and risk assessment. Plans are encrypted and stored with expiration.

Plan Features

  • • Risk Assessment - Automatic classification (low/medium/high)
  • • Business Context - Technical-to-business name mapping
  • • Encrypted Storage - AES-256-CBC encryption with IV
  • • Automatic Expiration - Plans expire after configurable time
  • • Client Tracking - Full audit trail of who created plans
curl -H "x-sed-api-key: $KEY" -H "Content-Type: application/json" \
-d '{"question":"Show top 10 customers by revenue this quarter"}' \
http://localhost:3000/api/plan

Response Example

{
"plan_id": "uuid-here",
"sql": "SELECT customer_name, SUM(order_total) as revenue...",
"business_context": {
"domain": "ecommerce",
"mappings": {"user_id": "Customer ID", "order_total": "Revenue"}
},
"risk_level": "low",
"expires_at": "2024-01-01T12:00:00Z"
}

POST /api/approve

Marks a plan as approved (human or policy gate).

curl -H "x-sed-api-key: $KEY" -H "Content-Type: application/json" \
-d '{"plan_id":"..."}' \
http://localhost:3000/api/approve

POST /api/execute

Securely executes approved plans with PII detection, access control, and comprehensive audit logging.

Execution Guardrails

  • • PII Protection - Automatic detection and masking of sensitive data
  • • Risk Blocking - High-risk queries blocked from execution
  • • Access Control - Row/column/query-level permissions
  • • Connection Pooling - Managed database connections with retry logic
  • • Audit Logging - Complete execution trail for compliance
curl -H "x-sed-api-key: $KEY" -H "Content-Type: application/json" \
-d '{"plan_id":"uuid-here"}' \
http://localhost:3000/api/execute

Response Example

{
"success": true,
"data": [{"Customer ID": "CUST001", "Revenue": "$25,000"}],
"execution_time_ms": 145,
"risk_level": "low",
"pii_detected": false,
"rows_returned": 10
}

Notes

  • Run npx sedql build first to generate .sed/*.mapping.json and rules.
  • Set DATABASE_URL on the server. Keys are not exposed to browsers.
  • Keep SED_REQUIRE_API_KEY=false for local dev if you want zero friction; enable in staging/prod.

Business Rules Engine

SED's Business Rules Engine acts as a governance layer that ensures AI interactions with your database are safe, compliant, and follow your business logic. Rules can be manually created and are automatically enabled for immediate protection.

Business Rules Overview

What are Business Rules?

Business rules are automated policies that govern how AI can interact with your database. They act as a "bouncer" that validates, modifies, or blocks queries based on your business requirements.

Security Rules

  • • PII Protection
  • • Access Control
  • • Data Privacy
  • • Audit Logging

Business Logic

  • • Metric Definitions
  • • Required Joins
  • • Data Validation
  • • Calculation Rules

Rule Execution Flow

1. AI generates query
2. SED validates against business rules
3. Rules can modify, allow, or block query
4. Modified query is returned to AI
5. AI executes validated query

Rule Types

Access Policy Rules

Control who can access what data and when. These rules enforce security and compliance requirements.

{
"id": "pii-protection",
"name": "PII Protection",
"type": "access_policy",
"severity": "block",
"condition": {
"type": "pattern",
"pattern": ".*(ssn|password|email).*"
},
"action": {
"type": "deny",
"message": "Access to PII columns is not allowed"
}
}

Metric Definition Rules

Define how business metrics should be calculated. Ensures consistency across all AI-generated queries.

{
"id": "revenue-calculation",
"name": "Revenue Metric Definition",
"type": "metric_definition",
"condition": {
"type": "pattern",
"pattern": ".*revenue.*"
},
"action": {
"type": "modify",
"code": "SELECT SUM(amount) - SUM(refunds) + SUM(adjustments) as revenue FROM {originalQuery}"
}
}

Join Rules

Ensure proper table relationships are maintained. Automatically adds required joins to queries.

{
"id": "user-joins",
"name": "Required User Joins",
"type": "join_rule",
"condition": {
"type": "function",
"function": "hasTable",
"parameters": { "table": "users" }
},
"action": {
"type": "modify",
"code": "{originalQuery} LEFT JOIN user_profiles ON users.id = user_profiles.user_id"
}
}

Data Validation Rules

Enforce data quality standards and format requirements. Validates data before processing.

{
"id": "email-validation",
"name": "Email Format Validation",
"type": "data_validation",
"condition": {
"type": "pattern",
"pattern": ".*email.*"
},
"action": {
"type": "modify",
"code": "{originalQuery} WHERE email REGEXP '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$'"
}
}

Auto-Generated Rules

Advanced Automatic Rule Generation

SED uses advanced AI-powered analysis to automatically generate comprehensive business rules based on your database schema, data patterns, and business domain. Rules are enabled by default for immediate protection - no manual setup required.

# Advanced rules are auto-generated during init/build
npx sedql init
# Advanced detection and rule generation
✓ Multi-method PII detection (pattern, semantic, ML, profiling)
✓ Business domain detection (e-commerce, SaaS, fintech, etc.)
✓ Advanced relationship analysis and join rules
✓ Business metric and KPI detection
✓ Workflow and business process detection
✓ Compliance requirement mapping (GDPR, HIPAA, PCI DSS)

What Gets Auto-Generated

  • • Advanced PII Protection - Multi-method detection with compliance mapping
  • • Business Domain Rules - Domain-specific business logic and workflows
  • • Advanced Relationship Rules - Foreign key, business logic, and workflow relationships
  • • Business Metrics & KPIs - Automatic metric definition and calculation rules
  • • Data Validation Rules - Constraint-based and business logic validation
  • • Workflow Rules - Business process and workflow enforcement
  • • Compliance Rules - GDPR, HIPAA, PCI DSS compliance enforcement
  • • Access Control Rules - Role-based and context-aware permissions
  • • Performance Rules - Query optimization and performance monitoring

Advanced Auto-Generation Process

  1. 1. Schema Analysis - Comprehensive database structure analysis
  2. 2. Business Domain Detection - Identifies e-commerce, SaaS, fintech, healthcare domains
  3. 3. Multi-Method PII Detection - Pattern matching, semantic analysis, data profiling, ML classification
  4. 4. Advanced Relationship Analysis - Foreign key, business logic, and workflow relationship detection
  5. 5. Business Logic Extraction - Automatic metric, validation, and workflow rule generation
  6. 6. Compliance Mapping - GDPR, HIPAA, PCI DSS requirement detection
  7. 7. Confidence Assessment - Intelligent confidence scoring for all detections
  8. 8. Rule Optimization - Performance and accuracy optimization
  9. 9. Auto-Enable - Production-ready rules enabled by default

Custom Rules

Creating Custom Rules

SED supports creating custom business rules to address your specific requirements. You can create rules from JSON files or use the interactive rule creation feature.

# Add rule from JSON file
npx sedql rules --add custom-rules.json
# List all rules
npx sedql rules --list
# Filter rules by type
npx sedql rules --list --type access_policy

Custom Rule Example

// custom-rules.json
{
"id": "business-hours-only",
"name": "Business Hours Restriction",
"description": "Only allow queries during business hours",
"type": "access_policy",
"severity": "warning",
"scope": "global",
"trigger": "before_query",
"enabled": true,
"priority": 100,
"condition": {
"type": "function",
"function": "isTimeWindow",
"parameters": { "start": "09:00", "end": "17:00" }
},
"action": {
"type": "log",
"message": "Query executed during business hours"
},
"tags": ["custom", "business-hours"],
"version": "1.0.0",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"createdBy": "user"
}

Rule Management Commands

npx sedql rules --list
npx sedql rules --add rule.json
npx sedql rules --remove rule-id
npx sedql rules --enable rule-id
npx sedql rules --disable rule-id

Rule Filtering Options

npx sedql rules --list --type access_policy
npx sedql rules --list --severity critical
npx sedql rules --list --format json

Rule Management

Managing Rules

# List all rules
npx sedql rules --list
# Disable a rule (rules enabled by default)
npx sedql rules --disable pii-protection
# Re-enable a rule
npx sedql rules --enable pii-protection

Rule Priority System

Rules are executed in priority order (highest first):

  • • 1000-900: Critical security rules
  • • 800-700: Business logic rules
  • • 600-500: Data quality rules
  • • 400-300: Performance rules
  • • 200-100: Audit and logging rules

Testing Rules

Test your business rules with sample queries to ensure they work as expected.

# Agent flow (rules applied automatically)
curl -H "x-sed-api-key: $KEY" -H "Content-Type: application/json" -d '{"question":"intent here"}' http://localhost:3000/api/plan

Advanced Features

Advanced PII Detection

  • • Multi-Method Detection: Pattern matching, semantic analysis, data profiling, and ML classification
  • • Compliance Mapping: Automatic GDPR, HIPAA, PCI DSS compliance requirements
  • • Risk Assessment: Intelligent risk level classification (Low, Medium, High, Critical)
  • • Context Analysis: Table and column context-aware detection
  • • Sample Data Analysis: Real data profiling for accurate detection

Advanced Business Logic Detection

  • • Domain Detection: Automatic e-commerce, SaaS, fintech, healthcare domain identification
  • • Relationship Analysis: Advanced foreign key and business relationship detection
  • • Metric Generation: Automatic business metric and KPI detection
  • • Workflow Analysis: Business process and workflow pattern detection
  • • Validation Rules: Automatic constraint and validation rule generation

Production-Ready Features

  • • Confidence Scoring: Intelligent confidence assessment for all detections
  • • Fallback Mechanisms: Graceful degradation to basic patterns
  • • Performance Optimization: Timeout handling and efficient processing
  • • Comprehensive Logging: Detailed audit trails and debugging information
  • • Extensible Architecture: Easy to extend with new detection methods

SED now provides production-ready advanced business rules engine with sophisticated PII detection and comprehensive business logic analysis.

Database Support

SED supports multiple database systems with automatic schema discovery and semantic mapping.

PostgreSQL

Full support for PostgreSQL with advanced schema discovery including multiple schemas, views, and complex relationships.

Features

  • • Multiple schema support (public, private, custom schemas)
  • • View and materialized view discovery
  • • Foreign key relationship analysis
  • • Index and constraint detection
  • • Partitioned table support

Connection Example

// sed.config.json
{
"database": {
"type": "postgres",
"host": "localhost",
"port": 5432,
"database": "myapp",
"username": "postgres"
}
}

MySQL

Comprehensive MySQL support with automatic detection of tables, views, and relationships across different databases.

Features

  • • Multi-database support
  • • View and stored procedure discovery
  • • Foreign key constraint analysis
  • • Index and trigger detection
  • • Character set and collation awareness

Connection Example

// sed.config.json
{
"database": {
"type": "mysql",
"host": "localhost",
"port": 3306,
"database": "myapp",
"username": "root"
}
}

SQLite

Lightweight SQLite support perfect for development, testing, and small applications with file-based databases.

Features

  • • File-based database support
  • • Automatic table discovery
  • • Foreign key relationship analysis
  • • Index and constraint detection
  • • Perfect for development and testing

Connection Example

// sed.config.json
{
"database": {
"type": "sqlite",
"database": "./data/app.db"
}
}

Connection Options

Advanced connection options and configuration settings for different database environments.

Connection Parameters

Basic Options

• host - Database server hostname
• port - Database server port
• database - Database name
• username - Database username
• password - Database password

Advanced Options

• ssl - Enable SSL/TLS encryption
• timeout - Connection timeout (seconds)
• pool - Connection pool settings
• schema - Default schema (PostgreSQL)
• charset - Character encoding

Environment Variables

# Connection string format
DATABASE_URL="postgresql://user:pass@localhost:5432/dbname"
# Or individual variables
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_USER=postgres
DB_PASSWORD=your_password

Connection Security

Best Practices

  • • Use environment variables for sensitive credentials
  • • Enable SSL/TLS for production connections
  • • Use dedicated database users with minimal required permissions
  • • Regularly rotate database passwords
  • • Never commit credentials to version control

Environment Variables

# .env file
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_USER=postgres
DB_PASSWORD=your_password

Advanced Usage

Production-grade features for enterprise deployments. Connection pooling, health monitoring, structured error handling, and advanced security configurations for mission-critical AI-database systems.

Connection Pooling & Performance

Enterprise Connection Management

SED includes production-grade connection pooling with automatic health monitoring, retry logic, and resource cleanup.

Connection Features

• Automatic connection pooling (max 10)
• Idle connection cleanup (30s timeout)
• Connection health monitoring
• Automatic retry with backoff
• Resource leak prevention

Performance Stats

• Real-time connection statistics
• Active/idle connection tracking
• Query execution timing
• Error rate monitoring
• Resource utilization metrics
# Configure caching in sed.config.json
{
"cache": {
"type": "redis",
"host": "localhost",
"port": 6379,
"ttl": 3600
}
}

Cache Implementation Example

import redis from 'redis';
import { execSync } from 'child_process';
class SEDCache {
constructor() {
this.redis = redis.createClient();
}
async getSemanticContext() {
const cached = await this.redis.get('semantic_context');
if (cached) return JSON.parse(cached);
const context = execSync('npx sedql export-context').toString();
await this.redis.setex('semantic_context', 3600, context);
return JSON.parse(context);
}
}

Query Optimization

  • • Batch Operations - Group multiple queries together
  • • Connection Pooling - Reuse database connections
  • • Query Analysis - Monitor slow queries
  • • Index Optimization - Ensure proper database indexing

Token Reduction

  • • Semantic Compression - Use concise entity names
  • • Context Filtering - Only include relevant metadata
  • • Lazy Loading - Load context on demand
  • • Query Templates - Pre-define common query patterns

Custom Business Patterns

Creating Custom Patterns

Extend SED's business logic detection with domain-specific patterns for your industry or organization.

// custom-patterns.json
{
"calculation_patterns": {
"healthcare": {
"patient_satisfaction_score": {
"pattern": ["rating", "feedback_score"],
"formula": "(rating + feedback_score) / 2",
"description": "Patient satisfaction calculation",
"business_purpose": "Quality of care measurement"
}
}
}
}

Loading Custom Patterns

# Load custom patterns during build
npx sedql build --patterns custom-patterns.json
# Or configure in sed.config.json
{
"patterns": "custom-patterns.json"
}

Pattern Types

  • • Calculation Patterns - Business formulas and metrics
  • • Status Patterns - State transitions and flags
  • • Relationship Patterns - Entity connections
  • • Validation Patterns - Data quality rules

Pattern Matching

  • • Exact Matching - Precise column name matches
  • • Fuzzy Matching - Similar name variations
  • • Regex Patterns - Complex pattern matching
  • • Context Matching - Table and column context

Schema Evolution

Managing Database Changes

Keep your semantic layer synchronized with database schema changes. SED provides tools to detect, analyze, and apply schema evolution safely.

# Detect schema changes
npx sed sync
# Force update without prompts
npx sed sync --force
# Show detailed changes
npx sed sync --verbose

Change Types

  • • New Tables - Automatically detected and mapped
  • • New Columns - Added to existing entities
  • • Removed Tables/Columns - Marked as deprecated
  • • Type Changes - Updated data type mappings
  • • Relationship Changes - Updated foreign key mappings

Version Management

  • • Automatic Backups - Previous versions saved
  • • Rollback Support - Revert to previous versions
  • • Change Logging - Track all schema changes
  • • Breaking Change Detection - Identify risky changes

CI/CD Integration

Integrate schema evolution into your deployment pipeline for automated semantic layer updates.

# .github/workflows/schema-sync.yml
name: Schema Sync
on:
push:
branches: [main]
jobs:
sync-schema:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: npm install -g sed-cli
- run: sed sync --force

Monitoring & Analytics

Performance Monitoring

Monitor SED performance, track usage patterns, and identify optimization opportunities.

# Get performance statistics
npx sed stats
# Monitor rule execution
npx sed rules --stats
# Export analytics data
npx sedql export-analytics > analytics.json

Key Metrics

  • • Query Performance - Execution times and throughput
  • • Rule Effectiveness - Hit rates and impact
  • • Cache Performance - Hit rates and efficiency
  • • Error Rates - Failed queries and rule violations
  • • Usage Patterns - Most common queries and entities

Alerting

  • • Performance Thresholds - Slow query alerts
  • • Error Rate Monitoring - High failure rate alerts
  • • Rule Violations - Security breach notifications
  • • Schema Changes - Breaking change alerts

Integration with Monitoring Tools

Connect SED metrics to your existing monitoring infrastructure for comprehensive observability.

# Prometheus metrics endpoint
npx sed serve-metrics --port 9090
# Health check endpoint
npx sed health-check
# Structured logging
export SED_LOG_FORMAT=json

Examples & Use Cases

Real-world examples of how SED can be used to solve common AI-database integration challenges. Each example includes schema overview, business requirements, setup instructions, and integration patterns.

E-commerce Platform

Business Requirements

  • • AI-powered product recommendations
  • • Customer behavior analysis
  • • Revenue and conversion tracking
  • • PII protection for customer data
  • • Inventory and order management

Database Schema Overview

-- Core tables
customers (id, email, name, created_at)
products (id, name, price, category_id)
orders (id, customer_id, total_amount, status)
order_items (id, order_id, product_id, quantity, price)

Business Rules Setup

// ecommerce-rules.json
{
"rules": [
{
"id": "customer-pii-protection",
"type": "access_policy",
"condition": { "pattern": ".*email.*" },
"action": { "type": "deny" }
}
]
}

AI Integration Example

import { openai } from 'openai';
import { execSync } from 'child_process';
// Get semantic context
const semanticContext = execSync('npx sedql export-context').toString();
const response = await openai.chat.completions.create({
model: 'gpt-4',
messages: [
{
role: 'system',
content: `You have access to an e-commerce database: ${semanticContext}. Generate SQL for product recommendations.`
},
{
role: 'user',
content: 'Recommend products for customer ID 123 based on their purchase history'
}
]
});

SaaS Platform

Business Requirements

  • • Customer churn prediction
  • • Feature usage analytics
  • • MRR (Monthly Recurring Revenue) tracking
  • • User engagement metrics
  • • Subscription management

Database Schema Overview

-- Core tables
users (id, email, plan_id, created_at)
subscriptions (id, user_id, plan_id, amount, status)
feature_usage (id, user_id, feature_id, usage_count)
events (id, user_id, event_type, timestamp)

Business Rules Setup

// saas-rules.json
{
"rules": [
{
"id": "mrr-calculation",
"type": "metric_definition",
"condition": { "pattern": ".*mrr.*" },
"action": {
"type": "modify",
"code": "SELECT SUM(amount) FROM subscriptions WHERE status = 'active' AND created_at >= DATE_TRUNC('month', NOW())"
}
}
]
}

AI Integration Example

import { ChatOpenAI } from 'langchain/chat_models';
import { initializeAgentExecutorWithOptions } from 'langchain/agents';
const model = new ChatOpenAI({ temperature: 0 });
const sedTool = new SEDTool();
const executor = await initializeAgentExecutorWithOptions([
sedTool
], model, {
agentType: 'chat-zero-shot-react-description'
});
const result = await executor.invoke({
input: 'Identify customers at risk of churning based on feature usage patterns'
});

Healthcare System

Business Requirements

  • • HIPAA compliance and PHI protection
  • • Patient outcome analysis
  • • Treatment effectiveness tracking
  • • Appointment scheduling optimization
  • • Medical record management

Database Schema Overview

-- Core tables
patients (id, ssn, name, date_of_birth)
appointments (id, patient_id, doctor_id, appointment_date)
medical_records (id, patient_id, diagnosis, treatment)
prescriptions (id, patient_id, medication, dosage)

Business Rules Setup

// healthcare-rules.json
{
"rules": [
{
"id": "phi-protection",
"type": "access_policy",
"condition": { "pattern": ".*(ssn|diagnosis|medication).*" },
"action": { "type": "deny" }
}
]
}

AI Integration Example

// Custom AI application with SED integration
import express from 'express';
import { execSync } from 'child_process';
app.post('/api/analyze-treatment', async (req, res) => {
try {
const { treatment_type } = req.body;
const result = execSync(`npx sedql search "treatment effectiveness ${treatment_type}"`).toString();
res.json({ success: true, data: result });
} catch (error) {
res.status(500).json({ error: error.message });
}
});

Financial Services

Business Requirements

  • • Fraud detection and prevention
  • • Risk assessment and compliance
  • • Transaction monitoring
  • • Customer portfolio analysis
  • • Regulatory reporting

Database Schema Overview

-- Core tables
accounts (id, customer_id, balance, account_type)
transactions (id, account_id, amount, transaction_type)
fraud_alerts (id, transaction_id, risk_score, status)
compliance_reports (id, report_type, generated_date, status)

Business Rules Setup

// financial-rules.json
{
"rules": [
{
"id": "large-transaction-alert",
"type": "data_validation",
"condition": { "pattern": ".*amount.*" },
"action": { "type": "modify" }
}
]
}

AI Integration Example

// Fraud detection with SED validation
async function detectFraud(transaction) {
const query = `SELECT * FROM transactions WHERE account_id = ${transaction.accountId} AND amount > 10000`;
// Validate query through SED
const validation = execSync(`npx sedql validate-query "${query}"`).toString();
if (validation.includes('blocked')) {
throw new Error('Query blocked by business rules');
}
// Execute validated query
return await executeQuery(query);
}