FlinDB - Zero-Config Database

🐘 "E flin nu" — It Remembers Things

FlinDB is powered by the ZeroCore engine. Every entity remembers its complete history. Time-travel is built-in.

Config Required

97%

Complete

∞

History

The .flindb Directory

When you save your first entity, FLIN automatically creates a .flindb/ directory in your project:

                        
                        
                        
                    
Project Structure

                    my-app/
├── app/
│   └── index.flin
├── entities/
│   └── Todo.flin
└── .flindb/              # Auto-created!
    ├── wal.log           # Write-ahead log
    ├── data/
    │   └── Todo_1.json   # Entity data
    └── meta.json         # Metadata
                

No configuration needed. No database server to install. Just save and go.

CRUDD Operations

FLIN uses CRUDD (not CRUD) — with two D's for delete and destroy:

Operation	Syntax	Effect	Recoverable?
Create	`save todo`	Insert new entity	—
Read	`Todo.all`	Query entities	—
Update	`save todo`	Update existing entity	—
Delete	`delete todo`	Soft delete (sets `deleted_at`)	YES
Destroy	`destroy todo`	Hard delete (permanent)	NO

                        
                        
                        
                    
CRUDD Example

                    // Create
todo = Todo { title: "Learn FLIN" }
save todo

// Read
todos = Todo.all
todo = Todo.find(1)

// Update
todo.done = true
save todo

// Delete (soft) - can restore later
delete todo
restore todo  // Undo!

// Destroy (hard) - permanent, GDPR compliant
destroy todo  // Gone forever
                

🐘 delete vs destroy

delete = FLIN remembers (soft delete, can restore)
destroy = FLIN forgets (hard delete, GDPR "right to be forgotten")

Time-Travel Queries

Every entity keeps its complete history. Access any previous version:

                        
Time Travel

                    // Get previous version
todo@-1        // One version back
todo@-2        // Two versions back

// Get version at specific time
todo@"2024-01-15"
todo@"2024-01-15 14:30:00"

// Get complete history
Todo.history(1)  // All versions of todo ID 1

// Restore from history
old_todo = todo@-1
save old_todo  // Creates new version with old data

Why Time-Travel?

Audit Trail — Track who changed what, when
Undo — Restore accidentally deleted/modified data
Compliance — Meet GDPR, HIPAA, SOC2 requirements
Analytics — Study data patterns over time
Debugging — See exactly what happened

Persistence & Recovery

FlinDB uses Write-Ahead Logging (WAL) for durability:

Write-Ahead Log

Every operation is logged before execution. Crash recovery replays the log.

Checkpointing

Periodic snapshots compress the WAL. Faster startup after restart.

Backup & Restore

Full and incremental backups. Point-in-time recovery (PITR).

                        
                        
                        
                    
WAL Entry Example

                    // Every save is logged:
{
  "type": "Save",
  "timestamp": 1705312200000,
  "entity_type": "Todo",
  "entity_id": 1,
  "version": 3,
  "data": { "title": "Learn FLIN", "done": true }
}
                

Semantic Search

Mark fields as semantic to enable AI-powered search:

                        
Semantic Search

                    entity Article {
    title: text
    content: semantic text  // Auto-generates embeddings
}

// Search by meaning, not keywords
results = search "machine learning tutorials" in Article by content

// Combines with regular queries
results = search "AI ethics" in Article by content limit 10

Configuration

FlinDB works with zero config, but you can customize:

                        
flin.config

                    [database]
path = ".flindb"              # Custom location
wal_enabled = true            # Write-ahead log
compaction_interval = 3600    # Seconds

[database.backup]
enabled = true
schedule = "0 2 * * *"        # Daily at 2am

Or use environment variables:

                        
Environment Variables

                    FLIN_DB_PATH=".flindb"
FLIN_DB_WAL_ENABLED=true
FLIN_DB_COMPACTION_INTERVAL=3600

Real-Time Subscriptions

Subscribe to entity changes for live updates:

                        
                        
                        
                    
Real-Time

                    // Subscribe to all Todo changes
Todo.subscribe(event => {
    if event.type == "created" {
        log("New todo: " + event.entity.title)
    }
})

// Subscribe to specific query
Todo.where(done == false).subscribe(todos => {
    pending_count = todos.length
})
                

Intent-Based Queries

Query your database with natural language:

                        
db.ask()

                    // Ask in natural language
result = db.ask("show users created today")
result = db.ask("count orders this month")
result = db.ask("top 5 products by revenue")

// Works with temporal phrases
result = db.ask("users who signed up last week")
result = db.ask("orders between Jan 1 and Jan 15")

FlinDB vs Others

Feature	SQLite	MongoDB	FlinDB
Zero Config	Yes	No	Yes
Embedded	Yes	No	Yes
Time-Travel	No	No	Built-in
Soft Delete	Manual	Manual	Default
Semantic Search	Extension	Atlas	Built-in
Real-Time	No	Change Streams	Built-in
Natural Language	No	No	db.ask()

📖 Deep Dive

For complete FlinDB documentation including relationships, indexes, and advanced queries, visit bible.flin.dev