{"id":7653,"library":"queries","title":"Queries","description":"Queries is a BSD licensed opinionated wrapper of the `psycopg2` library for interacting with PostgreSQL. It aims to reduce the complexity of `psycopg2` while adding features like a simplified API, connection pooling, and asynchronous support for Tornado. The library supports Python 2.7+ and 3.4+ and is currently at version 2.1.1.","status":"active","version":"2.1.1","language":"en","source_language":"en","source_url":"https://github.com/gmr/queries","tags":["database","postgresql","psycopg2","sql","async","tornado"],"install":[{"cmd":"pip install queries psycopg2-binary","lang":"bash","label":"Install with binary Psycopg2 (recommended for quick start)"},{"cmd":"pip install queries psycopg2","lang":"bash","label":"Install with Psycopg2 from source (recommended for production)"}],"dependencies":[{"reason":"Core PostgreSQL adapter; `queries` is a wrapper around it.","package":"psycopg2","optional":false},{"reason":"A pre-compiled binary version of `psycopg2` for easier installation, especially on Windows or without build tools.","package":"psycopg2-binary","optional":true},{"reason":"Required for `TornadoSession` and asynchronous PostgreSQL operations.","package":"tornado","optional":true}],"imports":[{"symbol":"Session","correct":"from queries import Session"},{"note":"Used for asynchronous operations with the Tornado web framework.","symbol":"TornadoSession","correct":"from queries import TornadoSession"}],"quickstart":{"code":"import os\nfrom queries import Session\n\n# Configure your PostgreSQL connection URI\n# Example: \"postgresql://user:password@host:port/database_name\"\n# If omitted, defaults to \"postgresql://<current_os_user>@localhost:5432/<current_os_user>\"\nDB_URI = os.environ.get('POSTGRES_URI', 'postgresql://postgres@localhost:5432/postgres')\n\ndef main():\n    try:\n        with Session(DB_URI) as session:\n            # Create a table\n            session.query(\"CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(255))\")\n            print(\"Table 'users' ensured.\")\n\n            # Insert data\n            result = session.query(\"INSERT INTO users (name) VALUES (%s) RETURNING id\", ('Alice',))\n            new_id = result.scalar()\n            print(f\"Inserted user Alice with ID: {new_id}\")\n\n            # Query data\n            results = session.query(\"SELECT id, name FROM users\")\n            print(\"Current users:\")\n            for row in results:\n                print(f\"  ID: {row.id}, Name: {row.name}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == '__main__':\n    main()","lang":"python","description":"This quickstart demonstrates how to connect to a PostgreSQL database using `queries.Session`, create a table, insert data, and retrieve results. It utilizes environment variables for the database URI for flexible configuration."},"warnings":[{"fix":"Upgrade to Python 2.7 or Python 3.4+.","message":"Version 2.0.0 removed official support for Python 2.6. Users on Python 2.6 must remain on `queries < 2.0.0` or upgrade their Python version.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"For production, `pip install queries psycopg2` and ensure necessary system build tools and `libpq-dev` are installed.","message":"When using `psycopg2-binary` (the easier-to-install dependency), be aware that it includes its own C libraries (like `libpq` and `libssl`). For production environments, it is often recommended to install `psycopg2` from source to ensure it links against system libraries, providing better control over updates and avoiding potential conflicts.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade to `queries` 2.0.0 or later to ensure proper `TornadoSession` cleanup.","message":"Prior to version 2.0.0, a CPU pegging bug could occur in `TornadoSession` on connection errors due to improper cleanup of the IOLoop. This was fixed in `queries` 2.0.0.","severity":"gotcha","affected_versions":"<2.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the necessary PostgreSQL client: `pip install queries psycopg2-binary` or `pip install queries psycopg2`.","cause":"The core dependency `psycopg2` (or `psycopg2-binary`) was not installed alongside `queries`.","error":"ImportError: No module named 'psycopg2'"},{"fix":"Ensure the PostgreSQL server is running and accessible. Verify the connection URI provided to `queries.Session` is correct (e.g., `postgresql://user:password@host:5432/dbname`). Check firewall rules if connecting remotely.","cause":"The PostgreSQL database server is not running, is not accessible from the client, or the connection URI is incorrect (e.g., wrong host, port, username, or database name).","error":"psycopg2.OperationalError: connection to server at \"localhost\" (127.0.0.1), port 5432 failed: Connection refused"},{"fix":"Ensure your SQL `CREATE TABLE` statement has been successfully executed before attempting `SELECT`, `INSERT`, `UPDATE`, or `DELETE` operations on that table.","cause":"Attempting to query a table that has not been created in the connected database schema.","error":"psycopg2.errors.UndefinedTable: relation \"your_table_name\" does not exist"}]}