API Reference

Mobjects

MTable

class manim_databases.MTable(columns: list[str], rows: list[list[~typing.Any]] | None = None, primary_key: str | None = None, style: ~manim_databases.constants.MTableStyle._DefaultStyle = <manim_databases.constants.MTableStyle._DefaultStyle object>)[source]

Bases: VGroup, Labelable

An animated database table.

Renders columns and rows as a grid of cells with optional primary-key highlighting and animated CRUD operations. Designed so that other mobjects in this library (MIndex, MWal, MLock) can hold stable references to individual MRow instances and animate against them.

Parameters:

  • columns (list[str]) – Column names, displayed as the header row.

  • rows (list[list], optional) – Initial row values. Each inner list must have len(columns) items.

  • primary_key (str or None, optional) – Name of the primary key column. When set, the column header text is colored style.primary_key_color to mark it visually.

  • style (MTableStyle._DefaultStyle, optional) – Style configuration. Default MTableStyle.DEFAULT.

Examples

>>> table = MTable(
...     columns=["id", "name", "status"],
...     rows=[[1, "alice", "active"], [2, "bob", "pending"]],
...     primary_key="id",
...     style=MTableStyle.BLUE,
... )
>>> self.play(Create(table))
>>> self.play(table.animate.insert_row([3, "carol", "active"]))
>>> self.play(table.animate.update_cell(1, "status", "active"))
>>> self.play(table.animate.delete_row(0))
animation_overrides = {}
delete_row(row_index: int) → MTable[source]

Remove a row by position and shift everything below upward.

get_cell_value(row_index: int, column: int | str) → Any[source]

Return the current value of a cell.

get_row(row_index: int) → MRow[source]

Return the MRow at a given position.

The returned reference is stable across subsequent inserts and deletes on the table — other mobjects can hold it without worrying about row index invalidation.

highlight_row(row_index: int) → MTable[source]

Apply a highlight stroke to a row.

insert_row(values: list[Any]) → MTable[source]

Append a row to the bottom of the table.

Parameters:

values (list) – Cell values matching self.columns length.

unhighlight_row(row_index: int) → MTable[source]

Remove the highlight from a row.

update_cell(row_index: int, column: int | str, new_value: Any) → MTable[source]

Replace a cell value in place.

Parameters:

  • row_index (int) – Row position.

  • column (int or str) – Column position or column name.

  • new_value (Any) – New value (coerced to string for display).

MBTree

class manim_databases.MBTree(order: int = 4, keys: list[Any] | None = None, style: _DefaultStyle = <manim_databases.constants.MBTreeStyle._DefaultStyle object>, max_width: float | None = None)[source]

Bases: VGroup, Labelable

An animated B-tree visualization.

Two construction modes:

  1. Manual structure — primary API for educational scenes:

    >>> tree = MBTree.from_structure({
...     "keys": [10, 20],
...     "children": [
...         {"keys": [3, 7]},
...         {"keys": [12, 17]},
...         {"keys": [25, 30]},
...     ],
... })

  2. Auto-build from a flat key list (sequential insertion with splits, just like a real B-tree):

    >>> tree = MBTree(order=4, keys=[10, 20, 5, 6, 12, 30, 7, 17])
Parameters:

  • order (int) – Maximum number of children per node. A node with more than order - 1 keys triggers a split.

  • keys (list, optional) – Initial keys to insert sequentially.

  • style (MBTreeStyle._DefaultStyle, optional) – Style configuration. Default MBTreeStyle.DEFAULT.

Notes

Insertion with cascading splits is supported. Deletion (with merges and borrows) is intentionally not implemented in this version — it will land after insert/split is validated against real scenes.

animation_overrides = {}
background_image: Image | str | None
background_stroke_color: ManimColor
background_stroke_opacity: float
background_stroke_width: float
cap_style: CapStyleType
close_new_points: bool
classmethod from_structure(structure: dict, order: int = 4, style: _DefaultStyle = <manim_databases.constants.MBTreeStyle._DefaultStyle object>, max_width: float | None = None) → MBTree[source]

Build a tree from an explicit nested-dict spec.

Each dict has keys (list) and an optional children list of further dicts. order defaults to 4 (max 3 keys per node); if any node in the structure has more keys than order - 1, the structure is rejected as inconsistent.

If max_width is provided, the tree is uniformly scaled down after layout so its bounding box width does not exceed that value. Useful for deep trees that would otherwise clip the frame.

get_nodes() → list[MBTreeNode][source]

Return all nodes in BFS order (root first).

get_root() → MBTreeNode | None[source]
get_search_path(key: Any) → list[tuple[MBTreeNode, int | None]][source]

Return (node, key_index) tuples visited during a key search.

At each internal node, key_index is the position of the key whose comparison decided which child to descend into — i.e., the smallest key in the node that is >= key (or the last key if all node keys are smaller). At the terminating leaf, key_index is the position of the matching key, or None if not found.

insert(key: Any) → MBTree[source]

Insert a key into the tree, splitting nodes as needed.

Empty tree → creates a single-node root. Otherwise descends to the correct leaf, inserts the key in sorted order, and cascades splits upward through the tree (creating a new root if the old root itself overflows).

joint_type: LineJointType
make_smooth_after_applying_functions: bool
n_points_per_cubic_curve: int
pre_function_handle_to_anchor_scale_factor: float
search(key: Any) → MBTree[source]

Walk the search path for a key. Non-animated; use .animate.

shade_in_3d: bool
submobjects: list[VMobject]
tolerance_for_point_equality: float
class manim_databases.MBTreeNode(keys: list[~typing.Any], style: ~manim_databases.constants.MBTreeStyle._DefaultStyle = <manim_databases.constants.MBTreeStyle._DefaultStyle object>)[source]

Bases: VGroup, Highlightable

A single B-tree node — a horizontal strip of cells, one per key.

A node with N keys has N cells and N+1 child slots (gaps), labeled 0 through N. Edges from a parent node attach to specific gaps:

  • gap 0 → before the first key

  • gap i → between key (i-1) and key i

  • gap N → after the last key

Use get_gap_bottom() to retrieve the (x, y, z) attachment point for an edge originating from a given gap. The point lies on the bottom edge of the node so that downward edges look natural.

Parameters:

  • keys (list) – Initial keys, in sorted order. Each is converted to a string for rendering. The order is the caller’s responsibility — this class does not sort.

  • style (MBTreeStyle._DefaultStyle) – Style configuration controlling cell and key appearance.

animation_overrides = {}
background_image: Image | str | None
background_stroke_color: ManimColor
background_stroke_opacity: float
background_stroke_width: float
cap_style: CapStyleType
close_new_points: bool
get_gap_bottom(gap_index: int) → ndarray[source]

Return the bottom-edge attachment point for a child slot.

Parameters:

gap_index (int) – Index in [0, len(self.keys)]. 0 is before the first key, len(self.keys) is after the last key, and intermediate values are between adjacent cells.

get_key_target(key_index: int) → VGroup[source]

Return a VGroup of (cell, text) for animating a single key.

Useful for Indicate-style highlights of a specific key during search animations.

insert_key_at(position: int, key: Any) → tuple[Rectangle, Text][source]

Insert a key at the given position and reflow cells around the node’s existing center.

After this call, every cell in the node is repositioned left-to-right anchored on the same center, so the node grows symmetrically and existing cells slide instead of overlapping. The new cell is also scaled to match the size of existing cells (so a post-construction .scale() on the parent tree doesn’t break the layout).

joint_type: LineJointType
make_smooth_after_applying_functions: bool
n_points_per_cubic_curve: int
pre_function_handle_to_anchor_scale_factor: float
shade_in_3d: bool
submobjects: list[VMobject]
take_keys_after(position: int) → tuple[list[Any], VGroup][source]

Remove all keys at index > position and return them.

After removal, the remaining cells reflow around the original node center so the node shrinks symmetrically.

Returns:

(removed_keys, removed_mobjects) – The removed key values and the mobjects (cells + texts) that were detached from this node.

Return type:

(list, VGroup)

tolerance_for_point_equality: float

MIndex

class manim_databases.MIndex(table: MTable, column: str, name: str | None = None, order: int = 4, max_tree_width: float = 4.5, style: _DefaultStyle = <manim_databases.constants.MIndexStyle._DefaultStyle object>)[source]

Bases: VGroup, Labelable

A visual database index that composes an MBTree with an MTable.

The index holds a B-tree whose leaf keys are values from one column of the table. Each leaf key has a curved pointer arrow to the corresponding MRow in the table.

The hero animation is lookup() — the search walks the B-tree, then follows the pointer arrow to highlight the matching row.

Parameters:

  • table (MTable) – The table this index points into. The index does not own or manage the table — it just draws arrows to its rows.

  • column (str) – Column name whose values become the B-tree keys.

  • name (str, optional) – Human-readable index name (e.g. "idx_orders_total").

  • order (int, optional) – B-tree order. Default 4.

  • max_tree_width (float, optional) – Maximum width for the B-tree. When the tree grows past this (e.g. after splits), it auto-scales to fit. Default 4.5.

  • style (MIndexStyle._DefaultStyle, optional) – Style configuration.

Examples

>>> table = MTable(columns=["id", "total"], rows=[[1, 120], [2, 85]])
>>> index = MIndex.from_table(table, "total")
>>> self.play(Create(index))
>>> self.play(index.animate.lookup(120))
animation_overrides = {}
background_image: Image | str | None
background_stroke_color: ManimColor
background_stroke_opacity: float
background_stroke_width: float
cap_style: CapStyleType
close_new_points: bool
classmethod from_table(table: MTable, column: str, name: str | None = None, order: int = 4, max_tree_width: float = 4.5, style: _DefaultStyle = <manim_databases.constants.MIndexStyle._DefaultStyle object>) → MIndex[source]

Build an index from an existing table and column.

This is the primary construction API. The index is positioned to the left of the table with curved pointer arrows drawn automatically.

Parameters:

  • table (MTable) – The table to index.

  • column (str) – Column name to index.

  • name (str, optional) – Index name for labelling.

  • order (int, optional) – B-tree order. Default 4.

  • max_tree_width (float, optional) – Maximum tree width before auto-scaling. Default 4.5.

  • style (MIndexStyle._DefaultStyle, optional) – Style configuration.

insert_key(value: Any, row: MRow) → MIndex[source]

Insert a key into the index pointing to the given row.

Call this after inserting a row into the table to keep the index in sync. The tree repositions and arrows rebuild automatically.

Parameters:

  • value (Any) – The column value to insert as a B-tree key.

  • row (MRow) – The table row this key points to.

joint_type: LineJointType
lookup(value: Any) → MIndex[source]

Perform a lookup (non-animated). Use .animate.lookup(value).

make_smooth_after_applying_functions: bool
n_points_per_cubic_curve: int
pre_function_handle_to_anchor_scale_factor: float
shade_in_3d: bool
submobjects: list[VMobject]
tolerance_for_point_equality: float

MQueryPlan

class manim_databases.MQueryPlan(plan: dict, style: _DefaultStyle = <manim_databases.constants.MQueryPlanStyle._DefaultStyle object>, max_width: float | None = None)[source]

Bases: VGroup, Labelable

Animated query execution plan as a tree of operators.

Renders a top-down operator tree matching PostgreSQL’s EXPLAIN (FORMAT JSON) output. Each node shows its type, optional relation name, and cost/rows annotation.

The hero animation is execute() — leaf nodes highlight first (they scan data), then data “flows” upward through edges to parent nodes, cascading to the root.

Parameters:

  • plan (dict) – Plan tree as a nested dict. Each node has at least "Node Type" and may have "Plans" (children), "Total Cost", "Plan Rows", "Relation Name", etc.

  • style (MQueryPlanStyle._DefaultStyle, optional) – Style configuration.

  • max_width (float or None, optional) – If set, the tree is uniformly scaled so its width does not exceed this value.

Examples

>>> plan = {
...     "Node Type": "Hash Join",
...     "Total Cost": 1234.56,
...     "Plans": [
...         {"Node Type": "Seq Scan", "Relation Name": "orders"},
...         {"Node Type": "Index Scan", "Relation Name": "customers"},
...     ],
... }
>>> mplan = MQueryPlan(plan, style=MQueryPlanStyle.BLUE)
animation_overrides = {}
background_image: Image | str | None
background_stroke_color: ManimColor
background_stroke_opacity: float
background_stroke_width: float
cap_style: CapStyleType
close_new_points: bool
execute() → MQueryPlan[source]

Execute the plan (non-animated). Use .animate.execute().

get_nodes() → list[_PlanNodeBox][source]

Return all node boxes in BFS order.

joint_type: LineJointType
make_smooth_after_applying_functions: bool
n_points_per_cubic_curve: int
pre_function_handle_to_anchor_scale_factor: float
shade_in_3d: bool
submobjects: list[VMobject]
tolerance_for_point_equality: float

Stubs

The following mobjects are planned but not yet implemented. They export a stable public API that raises NotImplementedError — this keeps the namespace consistent from day one.

class manim_databases.MWal(initial_lsn: int = 0, style: _DefaultStyle = <manim_databases.constants.MWalStyle._DefaultStyle object>)[source]

Bases: VGroup

Animated write-ahead log as an append-only sequence.

Will support:

  • LSN-labeled entries appearing left to right

  • Different entry types (INSERT, UPDATE, DELETE, COMMIT, CHECKPOINT)

  • Checkpoint markers

  • Replay animation (cursor walking through entries)

  • Visual link between WAL entries and the MTable rows they describe

Parameters:

  • initial_lsn (int) – Starting log sequence number.

  • style (MWalStyle._DefaultStyle, optional) – Style configuration.

Notes

Not yet implemented. Tracking issue: https://github.com/pg-pilot/manim-databases/issues

animation_overrides = {}
background_image: Image | str | None
background_stroke_color: ManimColor
background_stroke_opacity: float
background_stroke_width: float
cap_style: CapStyleType
close_new_points: bool
joint_type: LineJointType
make_smooth_after_applying_functions: bool
n_points_per_cubic_curve: int
pre_function_handle_to_anchor_scale_factor: float
shade_in_3d: bool
submobjects: list[VMobject]
tolerance_for_point_equality: float
class manim_databases.MReplicationTopology(primary: str, replicas: list[str], style: ~manim_databases.constants.MReplicationTopologyStyle._DefaultStyle = <manim_databases.constants.MReplicationTopologyStyle._DefaultStyle object>)[source]

Bases: VGroup

Animated database replication topology.

Will support:

  • Primary node + N replica nodes

  • Sync vs async replication modes (different edge styles)

  • Animated write propagation from primary to replicas

  • Replication lag visualization (delayed pulse on slower replicas)

  • Failover animation (primary → replica promotion)

  • Cascading replication (replica-of-a-replica)

Parameters:

  • primary (str) – Name of the primary node.

  • replicas (list[str]) – Names of replica nodes.

  • style (MReplicationTopologyStyle._DefaultStyle, optional) – Style configuration.

Notes

Not yet implemented. Tracking issue: https://github.com/pg-pilot/manim-databases/issues

animation_overrides = {}
background_image: Image | str | None
background_stroke_color: ManimColor
background_stroke_opacity: float
background_stroke_width: float
cap_style: CapStyleType
close_new_points: bool
joint_type: LineJointType
make_smooth_after_applying_functions: bool
n_points_per_cubic_curve: int
pre_function_handle_to_anchor_scale_factor: float
shade_in_3d: bool
submobjects: list[VMobject]
tolerance_for_point_equality: float
class manim_databases.MLock(target: str, mode: str = 'EXCLUSIVE', style: _DefaultStyle = <manim_databases.constants.MLockStyle._DefaultStyle object>)[source]

Bases: VGroup

Animated database lock with contention visualization.

Will support:

  • Row-level and table-level lock granularity

  • Lock modes (SHARE, EXCLUSIVE, ROW EXCLUSIVE, etc.)

  • Animated waiter queue when contention occurs

  • Deadlock detection cycle visualization

  • Integration with MTable to lock specific rows

Parameters:

  • target (str) – Name of the locked resource (e.g., "orders.row[42]").

  • mode (str) – Lock mode (e.g., "EXCLUSIVE").

  • style (MLockStyle._DefaultStyle, optional) – Style configuration.

Notes

Not yet implemented. Tracking issue: https://github.com/pg-pilot/manim-databases/issues

animation_overrides = {}
background_image: Image | str | None
background_stroke_color: ManimColor
background_stroke_opacity: float
background_stroke_width: float
cap_style: CapStyleType
close_new_points: bool
joint_type: LineJointType
make_smooth_after_applying_functions: bool
n_points_per_cubic_curve: int
pre_function_handle_to_anchor_scale_factor: float
shade_in_3d: bool
submobjects: list[VMobject]
tolerance_for_point_equality: float

Styles

Each mobject has a companion style class with DEFAULT, BLUE, PURPLE, and GREEN variants.

class manim_databases.MTableStyle[source]

Bases: object

Style configuration for MTable.

DEFAULT

Clean default style with white outlines.

Type:

MTableStyle._DefaultStyle

BLUE

Blue accent variant.

Type:

MTableStyle._BlueStyle

PURPLE

Purple accent variant.

Type:

MTableStyle._PurpleStyle

GREEN

Green accent variant.

Type:

MTableStyle._GreenStyle

BLUE = <manim_databases.constants.MTableStyle._BlueStyle object>
DEFAULT = <manim_databases.constants.MTableStyle._DefaultStyle object>
GREEN = <manim_databases.constants.MTableStyle._GreenStyle object>
PURPLE = <manim_databases.constants.MTableStyle._PurpleStyle object>
class manim_databases.MBTreeStyle[source]

Bases: object

Style configuration for MBTree.

DEFAULT, BLUE, PURPLE, GREEN

Predefined style variants matching the rest of the library.

BLUE = <manim_databases.constants.MBTreeStyle._BlueStyle object>
DEFAULT = <manim_databases.constants.MBTreeStyle._DefaultStyle object>
GREEN = <manim_databases.constants.MBTreeStyle._GreenStyle object>
PURPLE = <manim_databases.constants.MBTreeStyle._PurpleStyle object>
class manim_databases.MIndexStyle[source]

Bases: object

Style configuration for MIndex.

DEFAULT, BLUE, PURPLE, GREEN

Predefined style variants matching the rest of the library.

BLUE = <manim_databases.constants.MIndexStyle._BlueStyle object>
DEFAULT = <manim_databases.constants.MIndexStyle._DefaultStyle object>
GREEN = <manim_databases.constants.MIndexStyle._GreenStyle object>
PURPLE = <manim_databases.constants.MIndexStyle._PurpleStyle object>