Backends

DatabaseBackend (ABC)

Abstract base class for all sqbooster database backends.

Defines the unified interface that all backends must implement, enabling seamless switching between databases.

class sqbooster.backends.DatabaseBackend(serialization='json', **kwargs)

Bases: ABC

Abstract base class defining the unified database interface.

Every backend (SQLite, PostgreSQL, etc.) must implement these methods. This ensures you can swap backends by changing only the constructor call.

abstract property placeholder

Return the query placeholder character (‘?’ for SQLite, ‘%s’ for PostgreSQL).

abstractmethod __init__(serialization='json', **kwargs)

Initialize the backend.

Parameters:

serialization – Serialization format for key-value mode. ‘json’ (default) or ‘pickle’.

abstractmethod create_table(name, columns)

Create a new table.

Parameters:

• name – Table name.

• columns – List of Column instances or a TableSchema.

Returns:

True on success.

abstractmethod drop_table(name, if_exists=True)

Drop a table.

Parameters:

• name – Table name.

• if_exists – If True, don’t raise error when table doesn’t exist.

Returns:

True on success.

abstractmethod table_exists(name)

Check if a table exists.

Parameters:

name – Table name.

Returns:

True if table exists.

abstractmethod get_tables()

List all table names.

Returns:

List of table name strings.

abstractmethod get_schema(table_name)

Get the schema for a table.

Parameters:

table_name – Table name.

Returns:

TableSchema instance.

abstractmethod insert(table, data)

Insert a single row.

Parameters:

• table – Table name.

• data – Dict of column_name -> value.

Returns:

True on success.

abstractmethod insert_many(table, data_list)

Insert multiple rows at once.

Parameters:

• table – Table name.

• data_list – List of dicts, each representing a row.

Returns:

True on success.

abstractmethod update(table, data, **filters)

Update rows matching filters.

Parameters:

• table – Table name.

• data – Dict of column_name -> new_value.

• **filters – Filter conditions (same syntax as Query.filter).

Returns:

Number of rows updated.

abstractmethod delete(table, **filters)

Delete rows matching filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

Number of rows deleted.

abstractmethod query(table)

Create a Query builder for this table.

Parameters:

table – Table name.

Returns:

Query instance for chaining.

abstractmethod execute(sql, params=None, fetch=False)

Execute raw SQL.

Parameters:

• sql – SQL string.

• params – Query parameters.

• fetch – If True, return results.

Returns:

Query results if fetch=True, else None.

abstractmethod count(table, **filters)

Count rows matching filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

Row count.

abstractmethod write(key, value, commit=None)

Write a key-value pair (backward-compatible API).

Uses an internal _kv_store table. Serialization depends on the serialization mode (json or pickle).

abstractmethod read(key, default=None)

Read a value by key (backward-compatible API).

abstractmethod delete_key(key, commit=None)

Delete a key-value pair (backward-compatible API).

abstractmethod keys(pattern=None)

Get all keys, optionally filtered (backward-compatible API).

abstractmethod exists(key)

Check if a key exists (backward-compatible API).

abstractmethod get_size()

Get number of key-value pairs (backward-compatible API).

abstractmethod delete_database(commit=None)

Clear all data (backward-compatible API).

clear()

Convenience alias for delete_database().

abstractmethod close()

Close the database connection.

SQLiteBackend

SQLite database backend for sqbooster.

Supports real typed tables, JSON/pickle serialization, and the full query builder API.

class sqbooster.backends.sqlite.SQLiteBackend(name=':memory:', auto_commit=True, serialization='json')

Bases: DatabaseBackend

SQLite database backend with real tables and optional pickle support.

Parameters:

• name – Path to the SQLite database file (or ‘:memory:’ for in-memory).

• auto_commit – Whether to auto-commit after each write operation.

• serialization – Serialization mode for key-value storage: ‘json’ or ‘pickle’.

placeholder = '?'

create_table(name, columns)

Create a new table with typed columns.

Parameters:

• name – Table name.

• columns – List of Column instances or a TableSchema.

Returns:

True on success.

drop_table(name, if_exists=True)

Drop a table.

Parameters:

• name – Table name.

• if_exists – Suppress error if table doesn’t exist.

Returns:

True on success.

table_exists(name)

Check if a table exists.

get_tables()

List all user-defined table names.

get_schema(table_name)

Get the schema for a table.

insert(table, data)

Insert a single row into a table.

Parameters:

• table – Table name.

• data – Dict of column_name -> value.

Returns:

True on success.

insert_many(table, data_list)

Insert multiple rows at once.

Parameters:

• table – Table name.

• data_list – List of dicts.

Returns:

True on success.

update(table, data, **filters)

Update rows matching filters.

Parameters:

• table – Table name.

• data – Dict of column_name -> new_value.

• **filters – Filter conditions.

Returns:

Number of rows updated.

delete(table, **filters)

Delete rows matching filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

Number of rows deleted.

query(table)

Create a Query builder for the given table.

Parameters:

table – Table name.

Returns:

Query instance for chaining filters, ordering, etc.

execute(sql, params=None, fetch=False)

Execute raw SQL.

Parameters:

• sql – SQL string.

• params – Query parameters.

• fetch – If True, return results as list of dicts.

Returns:

List of dicts if fetch=True, else None.

count(table, **filters)

Count rows matching filters.

write(key, value, commit=None)

Write a key-value pair using JSON or pickle serialization.

read(key, default=None)

Read a value by key.

delete_key(key, commit=None)

Delete a key-value pair.

keys(pattern=None)

Get all keys, optionally filtered by pattern.

exists(key)

Check if a key exists.

get_size()

Get number of key-value pairs.

delete_database(commit=None)

Clear all data from all tables including key-value store.

close()

Close the database connection.

remove_database()

Close the connection and delete the database file from disk.

commit()

Manually commit pending changes.

rollback()

Roll back pending changes.

PostgreSQLBackend

PostgreSQL database backend for sqbooster.

Supports real typed tables, JSON/pickle serialization, and the full query builder API.

class sqbooster.backends.postgresql.PostgreSQLBackend(*args, **kwargs)

Bases: object

Fallback when psycopg2 is not installed.

JSONFileDatabase

JSON file database backend for sqbooster.

Stores key-value pairs and table data in a single JSON file. Supports the full DatabaseBackend interface with in-memory querying.

class sqbooster.databases.jsonfile.JSONFileDatabase(name='database.json', auto_commit=True, serialization='json')

Bases: DatabaseBackend

A file-based JSON database implementing the full DatabaseBackend interface.

Data is stored in-memory and persisted to a JSON file on commit. Supports both key-value operations and real typed tables.

Parameters:

• name – Filename for the JSON database.

• auto_commit – Whether to automatically save changes to file.

Example

db = JSONFileDatabase(“app.json”) db.create_table(“users”, [Column(“id”, Integer()), Column(“name”, Text())]) db.insert(“users”, {“name”: “Ali”}) results = db.query(“users”).filter(name=”Ali”).all()

placeholder = ':ph'

create_table(name, columns)

Create a new table.

Parameters:

• name – Table name.

• columns – List of Column instances or a TableSchema.

Returns:

True on success.

drop_table(name, if_exists=True)

Drop a table.

Parameters:

• name – Table name.

• if_exists – If True, don’t raise error when table doesn’t exist.

Returns:

True on success.

table_exists(name)

Check if a table exists.

Parameters:

name – Table name.

Returns:

True if table exists.

get_tables()

List all table names.

Returns:

List of table name strings.

get_schema(table_name)

Get the schema for a table.

Parameters:

table_name – Table name.

Returns:

TableSchema instance.

insert(table, data)

Insert a single row.

Parameters:

• table – Table name.

• data – Dict of column_name -> value.

Returns:

True on success.

insert_many(table, data_list)

Insert multiple rows at once.

Parameters:

• table – Table name.

• data_list – List of dicts, each representing a row.

Returns:

True on success.

update(table, data, **filters)

Update rows matching filters.

Parameters:

• table – Table name.

• data – Dict of column_name -> new_value.

• **filters – Filter conditions (same syntax as Query.filter).

Returns:

Number of rows updated.

delete(table, **filters)

Delete rows matching filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

Number of rows deleted.

query(table)

Create a Query builder for this table.

Parameters:

table – Table name.

Returns:

Query instance for chaining.

execute(sql, params=None, fetch=False)

Execute raw SQL.

Parameters:

• sql – SQL string.

• params – Query parameters.

• fetch – If True, return results.

Returns:

Query results if fetch=True, else None.

count(table, **filters)

Count rows matching filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

Row count.

write(key, value, commit=None)

Write a key-value pair (backward-compatible API).

Uses an internal _kv_store table. Serialization depends on the serialization mode (json or pickle).

read(key, default=None)

Read a value by key (backward-compatible API).

delete_key(key, commit=None)

Delete a key-value pair (backward-compatible API).

keys(pattern=None)

Get all keys, optionally filtered (backward-compatible API).

exists(key)

Check if a key exists (backward-compatible API).

get_size()

Get number of key-value pairs (backward-compatible API).

delete_database(commit=None)

Clear all data (backward-compatible API).

close()

Close the database connection.

remove_database()

PickleFileDatabase

Pickle file database backend for sqbooster.

Stores key-value pairs and table data in a single pickle file. Supports the full DatabaseBackend interface with in-memory querying and arbitrary Python object storage.

class sqbooster.databases.picklefile.PickleFileDatabase(name='database.pkl', auto_commit=True, serialization='pickle')

Bases: DatabaseBackend

A file-based pickle database implementing the full DatabaseBackend interface.

Data is stored in-memory and persisted to a pickle file on commit. Supports both key-value operations and real typed tables. Can store arbitrary Python objects (not just JSON-serializable ones).

Parameters:

• name – Filename for the pickle database.

• auto_commit – Whether to automatically save changes to disk.

Example

db = PickleFileDatabase(“app.pkl”) db.create_table(“cache”, [Column(“id”, Integer()), Column(“data”, Blob())]) db.insert(“cache”, {“data”: {1, 2, 3}})

placeholder = ':ph'

create_table(name, columns)

Create a new table.

Parameters:

• name – Table name.

• columns – List of Column instances or a TableSchema.

Returns:

True on success.

drop_table(name, if_exists=True)

Drop a table.

Parameters:

• name – Table name.

• if_exists – If True, don’t raise error when table doesn’t exist.

Returns:

True on success.

table_exists(name)

Check if a table exists.

Parameters:

name – Table name.

Returns:

True if table exists.

get_tables()

List all table names.

Returns:

List of table name strings.

get_schema(table_name)

Get the schema for a table.

Parameters:

table_name – Table name.

Returns:

TableSchema instance.

insert(table, data)

Insert a single row.

Parameters:

• table – Table name.

• data – Dict of column_name -> value.

Returns:

True on success.

insert_many(table, data_list)

Insert multiple rows at once.

Parameters:

• table – Table name.

• data_list – List of dicts, each representing a row.

Returns:

True on success.

update(table, data, **filters)

Update rows matching filters.

Parameters:

• table – Table name.

• data – Dict of column_name -> new_value.

• **filters – Filter conditions (same syntax as Query.filter).

Returns:

Number of rows updated.

delete(table, **filters)

Delete rows matching filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

Number of rows deleted.

query(table)

Create a Query builder for this table.

Parameters:

table – Table name.

Returns:

Query instance for chaining.

execute(sql, params=None, fetch=False)

Execute raw SQL.

Parameters:

• sql – SQL string.

• params – Query parameters.

• fetch – If True, return results.

Returns:

Query results if fetch=True, else None.

count(table, **filters)

Count rows matching filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

Row count.

write(key, value, commit=None)

Write a key-value pair (backward-compatible API).

Uses an internal _kv_store table. Serialization depends on the serialization mode (json or pickle).

read(key, default=None)

Read a value by key (backward-compatible API).

delete_key(key, commit=None)

Delete a key-value pair (backward-compatible API).

keys(pattern=None)

Get all keys, optionally filtered (backward-compatible API).

exists(key)

Check if a key exists (backward-compatible API).

get_size()

Get number of key-value pairs (backward-compatible API).

delete_database(commit=None)

Clear all data (backward-compatible API).

close()

Close the database connection.

remove_database()

RedisDatabase

Redis database backend for sqbooster.

Stores key-value pairs and table data using Redis hashes and sets. Supports the full DatabaseBackend interface with in-memory querying.

class sqbooster.databases.redis.RedisDatabase(*args, **kwargs)

Bases: object

MongoDatabase

MongoDB database backend for sqbooster.

Stores key-value pairs and table data in MongoDB collections. Supports the full DatabaseBackend interface with native MongoDB querying.

class sqbooster.databases.mongo.MongoDatabase(*args, **kwargs)

Bases: object