SimpleClient

SimpleClient - A high-level wrapper for easy sqbooster usage.

Provides a simplified API for common database operations while still exposing the full backend for advanced use cases.

class sqbooster.simple.SimpleClient(backend)

Bases: object

High-level wrapper around any sqbooster backend.

Simplifies table creation, CRUD operations, and querying.

Parameters:

backend – A DatabaseBackend instance to wrap.

Example:

import sqbooster

db = sqbooster.sqlite()
db.define("users", {"name": str, "email": str, "age": int})
db.add("users", {"name": "Alice", "email": "a@t.co", "age": 30})
user = db.get("users", name="Alice")
adults = db.find("users", age__gte=18)
db.update("users", {"age": 31}, name="Alice")
db.remove("users", name="Alice")

classmethod sqlite(name=':memory:', auto_commit=True, serialization='json')

Create a SimpleClient backed by SQLite.

Parameters:

• name – Database file path or ‘:memory:’ for in-memory.

• auto_commit – Auto-commit after each write.

• serialization – ‘json’ or ‘pickle’ for the key-value store.

classmethod postgresql(host='localhost', port=5432, name='postgres', user='postgres', password='', auto_commit=True, serialization='json')

Create a SimpleClient backed by PostgreSQL.

Parameters:

• host – Database host.

• port – Database port.

• name – Database name.

• user – Database user.

• password – Database password.

• auto_commit – Auto-commit after each write.

• serialization – ‘json’ or ‘pickle’ for the key-value store.

classmethod json(path, auto_commit=True)

Create a SimpleClient backed by a JSON file.

Parameters:

• path – Path to the JSON file.

• auto_commit – Auto-commit after each write.

classmethod pickle(path, auto_commit=True)

Create a SimpleClient backed by a Pickle file.

Parameters:

• path – Path to the pickle file.

• auto_commit – Auto-commit after each write.

classmethod redis(host='localhost', port=6379, db=0, password=None, prefix='', serialization='json')

Create a SimpleClient backed by Redis.

Parameters:

• host – Redis host.

• port – Redis port.

• db – Redis database number.

• password – Redis password.

• prefix – Key prefix for namespacing.

• serialization – ‘json’ or ‘pickle’.

classmethod mongo(uri='mongodb://localhost:27017', database='sqbooster')

Create a SimpleClient backed by MongoDB.

Parameters:

• uri – MongoDB connection URI.

• database – Database name.

define(table_name, columns)

Define and create a table.

Parameters:

• table_name – Name for the new table.

• columns –

  One of:

  • A dict of {name: type} for quick definition.

  • A list of (name, type) tuples.

  • A list of Column objects for full control.

Returns:

True on success.

Example:

# Dict (simplest)
client.define("users", {"name": str, "age": int})

# Tuples
client.define("users", [("name", str), ("age", int)])

add(table, data)

Insert one or more rows.

If the table doesn’t exist yet, it is created automatically from the column types in the data.

Parameters:

• table – Table name.

• data – A dict (single row) or list of dicts (bulk insert).

Returns:

True on success.

get(table, **filters)

Get a single row matching filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

Dict for the row, or None if not found.

Raises:

ValueError – If more than one row matches.

find(table, order_by=None, limit=None, offset=None, **filters)

Find rows matching filters.

Parameters:

• table – Table name.

• order_by – Column name to sort by. Prefix with ‘-’ for descending.

• limit – Maximum rows to return.

• offset – Number of rows to skip.

• **filters – Filter conditions (supports __gt, __lt, __contains, etc.).

Returns:

List of row dicts.

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.

remove(table, **filters)

Delete rows matching filters.

delete(table, **filters)

Delete rows matching filters (alias for remove).

count(table, **filters)

Count rows matching filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

Row count.

exists(table, **filters)

Check if any rows match filters.

Parameters:

• table – Table name.

• **filters – Filter conditions.

Returns:

True if matching rows exist.

tables()

List all table names.

Returns:

List of table name strings.

drop(table_name)

Drop a table.

Parameters:

table_name – Table to drop.

has(table_name)

Check if a table exists.

create_table(table_name, columns)

Create a table with explicit Column definitions.

Use this when you need constraints like unique, nullable=False, or custom defaults. For simple cases, use add() to auto-create.

insert_many(table, rows)

Insert multiple rows (alias for add with a list).

query(table)

Access the query builder directly.

get_tables()

List all table names (alias for tables()).

get_schema(table)

Get the schema for a table.

write(key, value)

Store a key-value pair.

read(key, default=None)

Read a value by key.

delete_key(key)

Delete a key-value pair.

keys(pattern=None)

List keys, optionally filtered by pattern.

property backend

Access the underlying DatabaseBackend directly.

close()

Close the database connection.