NyanSQLite API Reference

Complete documentation for the Pydantic-native NyanSQLite class.

NyanSQLite

class NyanSQLite(path: str = ':memory:', wal: bool = True, strict_deserialization: bool = False)

Pydantic-native SQLite wrapper. Supports automatic schema creation, B-tree indexes, FTS5 full-text search, partial reads/writes, and advanced query operators. Powered by the high-performance apsw backend.

Quick start::

    from nyansqlite import NyanSQLite, Indexed, Searchable
    from pydantic import BaseModel

    class Article(BaseModel):
        id:      int
        author:  Indexed[str]
        title:   Searchable[str]
        body:    Searchable[str]
        views:   int = 0

    db = NyanSQLite("blog.sqlite")
    db.register(Article)

    db.insert(Article(id=1, author="neko", title="Hello SQLite", body="…"))
    db.search(Article, "SQLite")
    db.update(Article, where={"id": 1}, views=42)
    db.select(Article, fields=["title", "views"], author="neko")

---

Constructor

Core Methods

register

def register(model: type[BaseModel]) -> None

Parameter

Parameter	Type	Description
model	type[BaseModel]

---

close

def close() -> None

---

registered_models

def registered_models() -> list[str]

---

CRUD Operations

insert

def insert(obj: M) -> M

Parameter

Parameter	Type	Description
obj	M

Returns

Type: M

---

insert_many

def insert_many(objs: list[M]) -> int

Parameter

Parameter	Type	Description
objs	list[M]

Returns

Type: int

---

update

def update(model: type[BaseModel], where: dict[str, Any], **fields: Any) -> int

Parameter

Parameter	Type	Description
model	type[BaseModel]
where	dict[str, Any]

Returns

Type: int

Raises

Example

    db.update(User, where={"id": 1}, age=26, bio="updated")

---

delete

def delete(model: type[BaseModel], *filters: str, **kwargs: Any) -> int

Parameter

Parameter	Type	Description
model	type[BaseModel]
filters	str

Returns

Type: int

Example

    db.delete(User, id=42)
    db.delete(User, "age > 50")
    db.delete(Session, user_id=1, active=True)

---

Query & Search

get

def get(model: type[M], *filters: str, **kwargs: Any) -> Optional[M]

Parameter

Parameter	Type	Description
model	type[M]
filters	str

Returns

Type: Optional[M]

Example

    user = db.get(User, id=1)
    user = db.get(User, "age > 30", name="Alice")
    user = db.get(User, email="[email protected]")

---

query

def query(model: type[M], *filters: str, limit: Optional[int] = None, offset: Optional[int] = None, order_by: Optional[str] = None, desc: bool = False, **kwargs: Any) -> list[M]

Parameter

Parameter	Type	Description
model	type[M]
filters	str
limit	Optional[int]
offset	Optional[int]
order_by	Optional[str]
desc	bool

Returns

Type: list[M]

Example

    db.query(User)                                  # 全ての行
    db.query(User, age=25)                          # 完全一致
    db.query(User, "age > 20", limit=10)            # 文字列フィルタ
    db.query(User, age__gte=20, limit=10)           # 演算子サフィックス
    db.query(User, order_by="name", desc=True)      # ソート
    db.query(User, order_by="id", limit=20, offset=40)  # ページネーション

---

select

def select(model: type[BaseModel], fields: list[str], *filters: str, limit: Optional[int] = None, offset: Optional[int] = None, order_by: Optional[str] = None, desc: bool = False, **kwargs: Any) -> list[dict[str, Any]]

Parameter

Parameter	Type	Description
model	type[BaseModel]
fields	list[str]
filters	str
limit	Optional[int]
offset	Optional[int]
order_by	Optional[str]
desc	bool

Returns

Type: list[dict[str, Any]]

Example

    db.select(Article, ["title", "views"], author="neko", order_by="views", desc=True)
    db.select(Article, ["title"], "views > 100")

---

search

def search(model: type[M], query: str, *, limit: Optional[int] = None) -> list[M]

Parameter

Parameter	Type	Description
model	type[M]
query	str
limit	Optional[int]

Returns

Type: list[M]

Raises

Example

    db.search(Article, "python sqlite")
    db.search(Article, "python sqlite", limit=5)

    db.search(Article, "title:python")

---

count

def count(model: type[BaseModel], *filters: str, **kwargs: Any) -> int

Parameter

Parameter	Type	Description
model	type[BaseModel]
filters	str

Returns

Type: int

Example

    total  = db.count(User)
    adults = db.count(User, "age >= 18")
    adults = db.count(User, age__gte=18)

---

exists

def exists(model: type[BaseModel], *filters: str, **kwargs: Any) -> bool

Parameter

Parameter	Type	Description
model	type[BaseModel]
filters	str

Returns

Type: bool

Example

    if db.exists(User, email="[email protected]"):
        ...

---

Maintenance

rebuild_fts

def rebuild_fts(model: type[BaseModel]) -> None

---

vacuum

def vacuum() -> None

---

Raw SQL Execution

execute_raw

def execute_raw(sql: str, params: tuple = ()) -> list[dict[str, Any]]

Parameter

Parameter	Type	Description
sql	str
params	tuple

Returns

Type: list[dict[str, Any]]

Example

    db.execute_raw("SELECT count(*) AS n FROM user WHERE age > ?", (18,))

---

Other Methods

atomic

def atomic() -> Generator[None, None, None]

Example

    with db.atomic():
        db.insert(User(id=1, name="Taro"))
        # ここで例外が発生するとロールバックされます

---