{"id":23886,"library":"infi-clickhouse-orm","title":"infi.clickhouse-orm","description":"A Python ORM-like library for interacting with ClickHouse databases, providing high-level abstractions for creating, querying, and manipulating data. Current version: 2.1.3. Release cadence is irregular.","status":"active","version":"2.1.3","language":"python","source_language":"en","source_url":"https://github.com/Infinidat/infi.clickhouse_orm","tags":["clickhouse","orm","database","infi"],"install":[{"cmd":"pip install infi-clickhouse-orm","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Used internally for database connection","package":"clickhouse-driver","optional":false},{"reason":"Date parsing utilities","package":"python-dateutil","optional":false},{"reason":"Timezone support","package":"pytz","optional":false}],"imports":[{"note":"The package is installed as infi-clickhouse-orm but imported as infi.clickhouse_orm","wrong":"from clickhouse_orm import Database","symbol":"Database","correct":"from infi.clickhouse_orm import Database"},{"note":"","wrong":null,"symbol":"Model","correct":"from infi.clickhouse_orm import Model"}],"quickstart":{"code":"from infi.clickhouse_orm import Database, Model, StringField, Int32Field\n\nclass Person(Model):\n    name = StringField()\n    age = Int32Field()\n    tablename = 'persons'\n\n# Connect to ClickHouse (adjust host/port as needed)\ndb = Database('default', db_url='http://localhost:8123/')\ndb.create_table(Person)\n\n# Insert a record\nperson = Person(name='Alice', age=30)\ndb.insert([person])\n\n# Query\nresults = db.select('SELECT * FROM persons')\nfor row in results:\n    print(row.name, row.age)","lang":"python","description":"Basic usage: define a model, create table, insert and query data."},"warnings":[{"fix":"Explicitly set tablename attribute in Model subclasses to match existing tables.","message":"Table names are case-sensitive and must match the database schema. The ORM does not automatically lowercase or uppercase table names.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Change import statements to from infi.clickhouse_orm import ...","message":"In version 2.0.0, the import path changed from clickhouse_orm to infi.clickhouse_orm. Old code using from clickhouse_orm import ... will break.","severity":"breaking","affected_versions":"2.0.0 and later"},{"fix":"Always pass a list: db.insert([instance])","message":"The insert() method expects a list of model instances; inserting a single instance without wrapping in a list causes a TypeError.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use 'from infi.clickhouse_orm import ...' instead.","cause":"Importing using old module name, but the package is installed as infi-clickhouse-orm.","error":"ModuleNotFoundError: No module named 'clickhouse_orm'"},{"fix":"Ensure you have created a Database instance with a valid db_url. In version 2.x, use db.create_table(ModelClass).","cause":"Attempting to use create_table before establishing a connection or using an older API version.","error":"AttributeError: 'Database' object has no attribute 'create_table'"},{"fix":"Set tablename explicitly on the model class to match the existing table name or run create_table() first.","cause":"The table does not exist or the tablename attribute is not set correctly on the Model.","error":"clickhouse_driver.errors.ServerException: Code: 60, e.displayText() = DB::Exception: Table default.persons doesn't exist"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}