Documentation

5. Data Operations

Insert, update and delete rows safely with validation, constraints and encrypted-column behavior.

Data operations mental model

Data operations change the rows stored in a table. RelPyDB validates schema, types, nullability, primary keys, foreign keys and encrypted columns before committing changes.

Safety design: update() and delete() refuse to affect every row unless you pass allow_all=True.

insert

`insert(table_name, values)`

insert(table_name: str, values: dict[str, Any]) -> dict[str, Any]

Creates one row. Missing AutoNumber values are generated automatically. Missing columns use defaults or None if nullable.

Parameter	Type	Description
`table_name`	`str`	The target table.
`values`	`dict[str, Any]`	The single row to insert.

alice = db.insert("users", {
    "name": "Alice",
    "email": "alice@example.com",
})

print(alice)
# {"id": 1, "name": "Alice", "email": "alice@example.com"}
# insert() always returns plaintext - use to_list() for masked exports

insert_many

`insert_many(table_name, rows)`

insert_many(table_name: str, rows: list[dict[str, Any]]) -> list[dict[str, Any]]

Creates many rows in the same table. Use it when you already have a list of dictionaries, such as JSON arrays, API results, CSV-normalized rows or generated test data.

Parameter	Type	Description
`table_name`	`str`	The target table.
`rows`	`list[dict[str, Any]]`	The rows to insert.

users = db.insert_many("users", [
    {"name": "Bob", "email": "bob@example.com"},
    {"name": "Carol", "email": "carol@example.com"},
])

print(users)
# [
#     {"id": 2, "name": "Bob", "email": "bob@example.com"},
#     {"id": 3, "name": "Carol", "email": "carol@example.com"},
# ]

Rule of thumb: use insert() for one row, then use insert_many() immediately after when you need to load multiple rows.

insert vs insert_many

Function	Best for	Input shape	Output shape
`insert`	One row	`{"name": "Alice"}`	`dict[str, Any]`
`insert_many`	Many rows	`[{"name": "Bob"}, {"name": "Carol"}]`	`list[dict[str, Any]]`

update

`update(table_name, values, where=None, allow_all=False)`

update("users", {"status": "active"}, where=lambda row: row["id"] == 1) -> int

Updates matching rows and returns the number of updated rows. Primary key and AutoNumber columns are not mutable in the current implementation.

updated = db.update(
    "users",
    {"status": "inactive"},
    where=lambda row: row["id"] == 2,
)

Encrypted tables: updating a table with encrypted values requires an encryption key so RelPyDB can safely rebuild the stored row.

delete

`delete(table_name, where=None, allow_all=False)`

delete("users", where=lambda row: row["id"] == 2) -> int

Deletes matching rows. Foreign-key on_delete rules are applied: RESTRICT, CASCADE, or SET NULL.

deleted = db.delete(
    "users",
    where=lambda row: row["id"] == 2,
)

When to use lambdas vs col conditions

Use	Example	Notes
`col()` in queries	`where(col("email") == "a@example.com")`	Can use equality metadata and indexes.
`lambda` in update/delete	`where=lambda row: row["id"] == 1`	Simple and Pythonic for mutation filters.