{"id":10259,"library":"sqlbag","title":"SQLBag Utilities","description":"SQLBag (version 0.1.1617247075) provides various snippets of SQL-related boilerplate, simplifying common SQLAlchemy tasks such as session management, query execution (e.g., `one`, `many`, `chunks`), engine creation, and upsert operations. It aims to reduce repetitive code for database interactions. Releases are frequent, following a timestamp-based micro-versioning system, primarily reflecting a single developer's utility collection.","status":"active","version":"0.1.1617247075","language":"en","source_language":"en","source_url":"https://github.com/djrobstep/sqlbag","tags":["sql","sqlalchemy","database","utilities","boilerplate"],"install":[{"cmd":"pip install sqlbag","lang":"bash","label":"Install sqlbag"}],"dependencies":[{"reason":"SQLAlchemy is the underlying ORM/toolkit that sqlbag wraps; it is not listed in install_requires but is essential for almost all functionality.","package":"sqlalchemy","optional":false}],"imports":[{"note":"S is a context manager for SQLAlchemy sessions.","symbol":"S","correct":"from sqlbag import S"},{"note":"one is a helper to fetch a single result from a query.","symbol":"one","correct":"from sqlbag import one"},{"note":"many is a helper to fetch multiple results from a query.","symbol":"many","correct":"from sqlbag import many"},{"note":"Engine-related functions are in the 'engine' submodule.","wrong":"from sqlbag import get_engine","symbol":"get_engine","correct":"from sqlbag.engine import get_engine"},{"note":"Session creation functions are in the 'engine' submodule.","wrong":"from sqlbag import make_session","symbol":"make_session","correct":"from sqlbag.engine import make_session"},{"note":"Specific SQLAlchemy helpers like upsert are in the 'sqla' submodule.","wrong":"from sqlbag import upsert","symbol":"upsert","correct":"from sqlbag.sqla import upsert"}],"quickstart":{"code":"import os\nfrom sqlbag import S, one, many\nfrom sqlbag.engine import get_engine\n\n# Configure your database URL\ndatabase_url = os.environ.get('DATABASE_URL', 'sqlite:///./test.db')\n\nengine = get_engine(url=database_url)\n\n# Example usage with S context manager\nwith S(engine) as session:\n    session.execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)')\n    session.execute(\"INSERT INTO users (name) VALUES ('Alice')\")\n    session.execute(\"INSERT INTO users (name) VALUES ('Bob')\")\n    session.commit()\n\n    # Fetch a single result\n    alice = one(session, 'SELECT * FROM users WHERE name = :name', name='Alice')\n    print(f\"Found one: {alice}\")\n\n    # Fetch multiple results\n    all_users = many(session, 'SELECT * FROM users')\n    print(f\"Found many: {all_users}\")\n\nprint(\"SQLBag quickstart completed successfully.\")","lang":"python","description":"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`."},"warnings":[{"fix":"Always install `SQLAlchemy` alongside `sqlbag` using `pip install sqlbag sqlalchemy`.","message":"SQLBag implicitly requires SQLAlchemy but does not list it in its `install_requires`. Users must manually install `SQLAlchemy` for `sqlbag` to function.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All 0.1.x versions"},{"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.","message":"The documentation for `sqlbag` is minimal, primarily consisting of the GitHub README. Advanced usage or debugging often requires inspecting the source code.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install SQLAlchemy explicitly: `pip install sqlalchemy`.","cause":"sqlbag relies heavily on SQLAlchemy but does not declare it as a direct dependency in `install_requires`.","error":"ModuleNotFoundError: No module named 'sqlalchemy'"},{"fix":"Call the function from the `sqlbag` module, passing the session: `sqlbag.one(session, query)` instead of `session.one(query)`.","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.","error":"AttributeError: 'Session' object has no attribute 'one'"},{"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.","cause":"The database table you are trying to query or interact with does not exist in the specified database.","error":"sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: users"}]}