---
name: vibedb-quickstart
description: Get started with VibeDB in 30 seconds. Use when working with VibeDB for the first time, storing document data, or need a quick MongoDB-like database without server setup.
---

# VibeDB Quickstart

Get started with VibeDB - a document database built on SQLite with zero configuration.

## 30-second start

```python
from vibedb import VibeDB

# Create database
db = VibeDB("app.db")  # or ":memory:" for temporary

# Get collection (auto-created)
users = db.collection("users")

# Insert
user_id = users.insert({"name": "Alice", "age": 28})

# Query
results = users.find({"age": {"$gte": 25}}).to_list()

# Update
users.update(user_id, {"age": 29})

# Done!
db.close()
```

## What is VibeDB?

- **Document database** like MongoDB
- **Built on SQLite** - no server needed
- **Zero configuration** - works immediately
- **Python-native** - Pythonic API

## Core concepts

1. **Database**: File (`"app.db"`) or in-memory (`:memory:`)
2. **Collection**: Container for documents (auto-created)
3. **Document**: JSON-like dict with auto `_id`, `_createdAt`, `_updatedAt`
4. **Query**: MongoDB-style dicts or Pythonic Q builder

## Essential CRUD operations

### Create
```python
# Single
user_id = users.insert({"name": "Alice", "email": "alice@example.com"})

# Bulk
ids = users.insert_many([
    {"name": "Bob", "age": 35},
    {"name": "Charlie", "age": 22}
])
```

### Read
```python
# By ID
user = users.get(user_id)

# Find with filter
adults = users.find({"age": {"$gte": 18}}).to_list()

# Find one
alice = users.find_one({"name": "Alice"})

# Count
total = users.count()
```

### Update
```python
# Update (merges, doesn't replace)
users.update(user_id, {"age": 29})

# Update multiple
users.update_many({"role": "user"}, {"status": "active"})
```

### Delete
```python
users.delete(user_id)
users.delete_many({"status": "inactive"})
```

## Query operators

```python
# Comparison
{"age": {"$eq": 28}}       # equals
{"age": {"$gte": 25}}      # >=
{"age": {"$lt": 30}}       # <

# Range
{"age": {"$gte": 25, "$lte": 40}}

# In list
{"role": {"$in": ["admin", "moderator"]}}

# Sort and limit
users.find({}).sort("age", -1).limit(10).to_list()
```

## Two query styles

**Style 1: Dict (MongoDB-like)**
```python
users.find({"age": {"$gte": 25}})
```

**Style 2: Q Builder (Pythonic)**
```python
from vibedb import Q

users.find(Q.gte("age", 25))

# Complex queries with logic
users.find(
    (Q.gte("age", 25) & Q.lt("age", 40)) | Q.eq("vip", True)
)
```

## Quick patterns

See `examples.md` for ready-to-use patterns:
- Key-value store
- Session management
- Event logging
- Agent state persistence

## Important notes

- Use `doc["_id"]` not `doc._id` for internal fields
- Updates merge (don't replace entire document)
- Collections auto-create (no setup needed)
- Call `db.close()` when done

## When you're ready

- **Speed up queries?** → Use `/vibedb-indexing` skill
- **Add validation?** → See `reference.md` for schema validation
- **Complex queries?** → See `reference.md` for all operators
- **Production patterns?** → Use `/vibedb-patterns` skill

## Quick reference

```python
from vibedb import VibeDB, Q

db = VibeDB("app.db")
users = db.collection("users")

# CRUD
user_id = users.insert({"name": "Alice"})
user = users.get(user_id)
users.update(user_id, {"age": 29})
users.delete(user_id)

# Query
users.find({"age": {"$gte": 25}}).to_list()
users.find(Q.gte("age", 25)).to_list()

db.close()
```
