SQLBag Utilities

Common errors

• ModuleNotFoundError: No module named 'sqlalchemy'

  cause sqlbag relies heavily on SQLAlchemy but does not declare it as a direct dependency in `install_requires`.
  fix Install SQLAlchemy explicitly: `pip install sqlalchemy`.

• AttributeError: 'Session' object has no attribute 'one'

  cause You are attempting to call a `sqlbag` helper function (like `one`, `many`, `chunks`) directly on an SQLAlchemy `Session` object. These are global `sqlbag` functions that take a session as their first argument.
  fix Call the function from the `sqlbag` module, passing the session: `sqlbag.one(session, query)` instead of `session.one(query)`.

• sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: users

  cause The database table you are trying to query or interact with does not exist in the specified database.
  fix Ensure your table schema is created before attempting to interact with it. For example, by executing `CREATE TABLE` statements or using SQLAlchemy's ORM metadata to create tables.

Warnings

• gotcha SQLBag implicitly requires SQLAlchemy but does not list it in its `install_requires`. Users must manually install `SQLAlchemy` for `sqlbag` to function.
  Fix: Always install `SQLAlchemy` alongside `sqlbag` using `pip install sqlbag sqlalchemy`.
• gotcha SQLBag uses a timestamp-based micro-versioning scheme (e.g., `0.1.1617247075`). This indicates that API stability is not guaranteed, and breaking changes might occur frequently without explicit major version bumps or clear announcements in the release notes.
  Fix: Pin `sqlbag` to a specific version in your `requirements.txt` to mitigate unexpected behavior changes. Regularly review the GitHub repository for recent commits if encountering issues after updates.
• gotcha The documentation for `sqlbag` is minimal, primarily consisting of the GitHub README. Advanced usage or debugging often requires inspecting the source code.
  Fix: Be prepared to consult the `sqlbag` source code on GitHub (`https://github.com/djrobstep/sqlbag`) for detailed understanding of functions and their parameters, especially for less common utilities.

Install

• pip install sqlbag Install sqlbag

Imports

• S

  from sqlbag import S

  S is a context manager for SQLAlchemy sessions.
• one

  from sqlbag import one

  one is a helper to fetch a single result from a query.
• many

  from sqlbag import many

  many is a helper to fetch multiple results from a query.
• get_engine
  wrong:

  from sqlbag import get_engine

  correct:

  from sqlbag.engine import get_engine

  Engine-related functions are in the 'engine' submodule.
• make_session
  wrong:

  from sqlbag import make_session

  correct:

  from sqlbag.engine import make_session

  Session creation functions are in the 'engine' submodule.
• upsert
  wrong:

  from sqlbag import upsert

  correct:

  from sqlbag.sqla import upsert

  Specific SQLAlchemy helpers like upsert are in the 'sqla' submodule.

Quickstart

This quickstart demonstrates how to initialize an SQLAlchemy engine, use the `S` context manager for session handling, and perform basic queries with `sqlbag.one` and `sqlbag.many`.

import os
from sqlbag import S, one, many
from sqlbag.engine import get_engine

# Configure your database URL
database_url = os.environ.get('DATABASE_URL', 'sqlite:///./test.db')

engine = get_engine(url=database_url)

# Example usage with S context manager
with S(engine) as session:
    session.execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)')
    session.execute("INSERT INTO users (name) VALUES ('Alice')")
    session.execute("INSERT INTO users (name) VALUES ('Bob')")
    session.commit()

    # Fetch a single result
    alice = one(session, 'SELECT * FROM users WHERE name = :name', name='Alice')
    print(f"Found one: {alice}")

    # Fetch multiple results
    all_users = many(session, 'SELECT * FROM users')
    print(f"Found many: {all_users}")

print("SQLBag quickstart completed successfully.")