Install & Compatibility
Where this runs
tested against v0.1.1617247075 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.941s · 43.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.3s · import 0.850s · 42MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ from sqlbag.engine import get_engine
✗ from sqlbag import get_engine
Engine-related functions are in the 'engine' submodule.
make_session
✓ from sqlbag.engine import make_session
✗ from sqlbag import make_session
Session creation functions are in the 'engine' submodule.
upsert
✓ from sqlbag.sqla import upsert
✗ from sqlbag import upsert
Specific SQLAlchemy helpers like upsert are in the 'sqla' submodule.
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.")
Debug
Known issues
gotchaSQLBag implicitly requires SQLAlchemy but does not list it in its `install_requires`. Users must manually install `SQLAlchemy` for `sqlbag` to function.fixAlways install `SQLAlchemy` alongside `sqlbag` using `pip install sqlbag sqlalchemy`.
affects: All versions
gotchaSQLBag 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.fixPin `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.
affects: All 0.1.x versions
gotchaThe documentation for `sqlbag` is minimal, primarily consisting of the GitHub README. Advanced usage or debugging often requires inspecting the source code.fixBe 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sqlalchemy'
sqlbag relies heavily on SQLAlchemy but does not declare it as a direct dependency in `install_requires`.
fixInstall SQLAlchemy explicitly: `pip install sqlalchemy`.
AttributeError: 'Session' object has no attribute 'one'
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.
fixCall 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
The database table you are trying to query or interact with does not exist in the specified database.
fixEnsure 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.
Upgrade
Version history
0.1.1617247075latest on PyPI · released Apr 1, 2021
Audit
Dependencies
sqlalchemyrequiredSQLAlchemy is the underlying ORM/toolkit that sqlbag wraps; it is not listed in install_requires but is essential for almost all functionality.