{"id":17966839,"url":"https://github.com/crate/micropython-cratedb","last_synced_at":"2026-01-26T23:45:26.809Z","repository":{"id":258294625,"uuid":"868970531","full_name":"crate/micropython-cratedb","owner":"crate","description":"A CrateDB Driver for MicroPython.","archived":false,"fork":false,"pushed_at":"2025-11-15T22:09:49.000Z","size":65,"stargazers_count":10,"open_issues_count":5,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-11-16T00:09:35.962Z","etag":null,"topics":["cratedb","cratedb-driver","iot","iot-device","micropython","micropython-driver","rdbms","sensor-network","sensor-networks","sql","telemetry","telemetry-collection"],"latest_commit_sha":null,"homepage":"https://cratedb.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crate.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-07T13:53:26.000Z","updated_at":"2025-11-15T22:09:51.000Z","dependencies_parsed_at":"2024-12-09T00:19:34.019Z","dependency_job_id":"5858f0ef-0235-4cfe-b68c-f9aa00de0e78","html_url":"https://github.com/crate/micropython-cratedb","commit_stats":{"total_commits":45,"total_committers":4,"mean_commits":11.25,"dds":"0.33333333333333337","last_synced_commit":"b673c7628d53ab71b5feafc0739d7bb99b13f58a"},"previous_names":["simonprickett/microcrate"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/crate/micropython-cratedb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crate%2Fmicropython-cratedb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crate%2Fmicropython-cratedb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crate%2Fmicropython-cratedb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crate%2Fmicropython-cratedb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crate","download_url":"https://codeload.github.com/crate/micropython-cratedb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crate%2Fmicropython-cratedb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28791435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:49:50.245Z","status":"ssl_error","status_checked_at":"2026-01-26T21:48:29.455Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cratedb","cratedb-driver","iot","iot-device","micropython","micropython-driver","rdbms","sensor-network","sensor-networks","sql","telemetry","telemetry-collection"],"created_at":"2024-10-29T14:00:48.068Z","updated_at":"2026-01-26T23:45:26.786Z","avatar_url":"https://github.com/crate.png","language":"Python","readme":"# micropython-cratedb - A CrateDB Driver for MicroPython\n\n[![Tests](https://github.com/crate/micropython-cratedb/actions/workflows/tests.yml/badge.svg)](https://github.com/crate/micropython-cratedb/actions/workflows/tests.yml)\n[![Test coverage](https://img.shields.io/codecov/c/gh/crate/micropython-cratedb.svg?style=flat-square)](https://codecov.io/gh/crate/micropython-cratedb/)\n\n## Introduction\n\nmicropython-cratedb is a [CrateDB](https://cratedb.com) driver for the [MicroPython](https://micropython.org) language.  It connects to CrateDB using the [HTTP Endpoint](https://cratedb.com/docs/crate/reference/en/latest/interfaces/http.html).\n\nTo use this, you'll need a CrateDB database cluster.  Sign up for our cloud free tier [here](https://console.cratedb.cloud/) or get started with Docker [here](https://hub.docker.com/_/crate).\n\nWant to learn more about CrateDB?  Take our free [Fundamentals course](https://learn.cratedb.com/course-overview) at the CrateDB Academy.  You can also [watch this video](https://www.youtube.com/watch?v=c4CArvphNeM) from the [Raspberry Pint Meetup](https://www.meetup.com/raspberry-pint-london/) where [Simon Prickett](https://simonprickett.dev), CrateDB's Developer Advocate, demonstrates how to use this driver with various sensors attached to Raspberry Pi Pico W devices.\n\n## Installation\n\nThere are two ways to install this driver.\n\n### Install with `mpremote`\n\nInstall the driver with [`mpremote`](https://docs.micropython.org/en/latest/reference/mpremote.html) like this:\n\n```bash\nmpremote mip install github:crate/micropython-cratedb\n```\n\nThis will install the driver into `/lib` on the device, along with the [base64](https://github.com/micropython/micropython-lib/tree/master/python-stdlib/base64) module from `micropython-lib`.\n\n### Install with `mip`\n\nYou can also install the driver into `/lib` on the device by running the following commands at the MicroPython REPL on the device:\n\n```python\nimport network\nimport mip\nwlan = network.WLAN(network.STA_IF)\nwlan.active(True)\nwlan.connect(\"\u003cyour wifi SSID\u003e\", \"\u003cyour wifi password\u003e\")\nwlan.isconnected() # Run this until it returns True\nmip.install(\"github:crate/micropython-cratedb\")\n```\n\n## Using the Driver in a MicroPython Script\n\nImport the driver like this:\n\n```python\nimport cratedb\n```\n\n### Connecting to CrateDB\n\nConnect to a CrateDB Cloud cluster using SSL, by providing hostname, username, and password:\n\n```python\ncrate = cratedb.CrateDB(\n    host=\"host\", \n    user=\"user\", \n    password=\"password\"\n)\n```\n\nThe driver uses SSL by default.\n\nIf you're running CrateDB on your workstation (with Docker for example,\nby using `docker run --rm -it --publish=4200:4200 crate`), connect like\nthis:\n\n```python\ncrate = cratedb.CrateDB(\n    host=\"hostname\", \n    use_ssl=False\n)\n```\n\nThe driver will connect to port 4200 unless you provide an alternative value:\n\n```python\ncrate = cratedb.CrateDB(\n    host=\"host\", \n    user=\"user\", \n    port=4201,\n    password=\"password\"\n)\n```\n\n### Interacting with CrateDB\n\nCrateDB is a SQL database: you'll store, update and retieve data using SQL statements.  The examples that follow assume a table schema that looks like this:\n\n```sql\nCREATE TABLE temp_humidity (\n  sensor_id TEXT, \n  ts TIMESTAMP WITH TIME ZONE GENERATED ALWAYS AS current_timestamp,\n  temp DOUBLE PRECISION, \n  humidity DOUBLE PRECISION\n);\n```\n\nAssume that the table contains a few sample rows.\n\n#### Retrieving Data\n\nThe `execute` method sends a SQL statement to the database for execution, and returns the result:\n\n```python\nresponse = crate.execute(\n    \"SELECT sensor_id, ts, temp, humidity FROM temp_humidity ORDER BY ts DESC\"\n)\n```\n\nYou can also use parameterized queries:\n\n```python\nresponse = crate.execute(\n    \"\"\"\n        SELECT sensor_id, ts, temp, humidity\n        FROM temp_humidity WHERE sensor_id = ?\n        ORDER BY ts DESC\n    \"\"\",\n    [\n        \"a01\"\n    ]\n)\n```\n\nData is returned as a dictionary that looks like this:\n\n```python\n{\n    'rows': [\n        ['a01', 1728473302619, 22.8, 59.1], \n        ['a02', 1728473260880, 3.3, 12.9], \n        ['a02', 1728473251188, 3.2, 12.7], \n        ['a03', 1728473237365, 28.4, 65.7], \n        ['a01', 1728473223332, 22.3, 58.6]\n    ], \n    'rowcount': 5, \n    'cols': [\n        'sensor_id', \n        'ts', \n        'temp', \n        'humidity'\n    ], \n    'duration': 18.11329\n}\n```\n\nUse the `with_types` parameter to have CrateDB return information about the data type of each column in the resultset. This feature is off by defaault to minimize network bandwidth.\n\n```python\nresponse = crate.execute(\n    \"SELECT sensor_id, ts, temp FROM temp_humidity WHERE sensor_id = ? ORDER BY ts DESC\",\n    [\n        \"a01\"\n    ],\n    with_types=True\n)\n```\n\nThe resultset then contains an extra key, `col_types`:\n\n```python\n{\n    'col_types': [\n        4, \n        11, \n        6\n    ], \n    'cols': [\n        'sensor_id', \n        'ts', \n        'temp'\n    ], \n    'rowcount': 2, \n    'rows': [\n        ['a01', 1728473302619, 22.8], \n        ['a01', 1728473223332, 22.3]\n    ], \n    'duration': 7.936583\n}\n```\n\nConstants are provided for each type.  For example type `11` is `CRATEDB_TYPE_TIMESTAMP_WITH_TIME_ZONE`.\n\n#### Inserting / Updating Data\n\nHere's an example insert statement:\n\n```python\nresponse = crate.execute(\n    \"INSERT INTO temp_humidity (sensor_id, temp, humidity) VALUES (?, ?, ?)\",\n    [\n        \"a01\",\n        22.8,\n        60.1\n    ]\n)\n```\n\nThe response from CrateDB looks like this:\n\n```python\n{\n    'rows': [\n        []\n    ], \n    'rowcount': 1, \n    'cols': [], \n    'duration': 38.615707\n}\n```\n\nIf you don't need a response, set the `return_response` parameter to `False` (default is `True`). This will save a small amount of time that the driver normally spends on processing the response.\n\n```python\nresponse = crate.execute(\n    \"INSERT INTO temp_humidity (sensor_id, temp, humidity) VALUES (?, ?, ?)\",\n    [\n        \"a01\",\n        22.9,\n        60.3\n    ],\n    return_response=False\n)\n```\n\n`response` will be `None`.\n\nYou can add multiple records in a single network round trip using a bulk insert:\n\n```python\nresponse = crate.execute(\n    \"INSERT INTO temp_humidity (sensor_id, temp, humidity) VALUES (?, ?, ?)\",\n    [\n        [\n            \"a01\",\n            22.7,\n            60.1\n        ],\n        [\n            \"a02\",\n            3.3,\n            12.9\n        ]\n    ]\n)\n```\n\nThe response looks like this, note that you can expect to receive multiple results each containing their own `rowcount`:\n\n```python\n{\n    'results': [\n        {\n            'rowcount': 1\n        }, \n        {\n            'rowcount': 1\n        }\n    ], \n    'cols': [], \n    'duration': 32.546875\n}\n```\n\nExisting rows can also be updated:\n\n```python\nresponse = crate.execute(\n    \"UPDATE temp_humidity SET sensor_id = ? WHERE sensor_id = ?\",\n    [\n        \"a04\",\n        \"a01\"\n    ]\n)\n```\n\nThe response includes the number of rows affected by the update:\n\n```python\n{\n    'rows': [\n        []\n    ], \n    'rowcount': 5, \n    'cols': [], \n    'duration': 696.36975\n}\n```\n\n#### Working with Objects and Arrays\n\nCrateDB supports flexible storage and indexing of objects / JSON data.  To learn more about this, check out our [blog post](https://cratedb.com/blog/handling-dynamic-objects-in-cratedb) that explains the different ways objects can be stored.\n\nHere are some basic examples showing how to store objects with micropython-cratedb and retrieve desired fields from them.\n\nAssume a table with the following definition having a [dynamic object](https://cratedb.com/blog/handling-dynamic-objects-in-cratedb) column:\n\n```sql\nCREATE TABLE driver_object_test (\n    id TEXT PRIMARY KEY, \n    data OBJECT(DYNAMIC)\n)\n```\n\nObjects of arbitrary structure are inserted like this:\n\n```python\nresponse = crate.execute(\n    \"INSERT INTO driver_object_test (id, data) VALUES (?, ?)\",\n    [\n        \"2cae54\",\n        {\n            \"sensor_readings\": {\n                \"temp\": 23.3,\n                \"humidity\": 61.2\n            },\n            \"metadata\": {\n                \"software_version\": \"1.19\",\n                \"battery_percentage\": 57,\n                \"uptime\": 2851200\n            }\n        }\n    ]\n)\n```\n\nAnd values contained in objects can be retrieved selectively like this:\n\n```python\nresponse = crate.execute(\n    \"\"\"SELECT \n            id,\n            data['metadata']['uptime'] AS uptime, \n            data['sensor_readings'] AS sensor_readings \n        FROM driver_object_test \n        WHERE id = ?\"\"\",\n    [\n        \"2cae54\"\n    ]\n)\n```\n\n`response` contains the matching records like this:\n\n```python\n{\n    'rows': [\n        [2851200, {'humidity': 61.2, 'temp': 23.3}]  \n    ], \n    'rowcount': 1, \n    'cols': [\n        'uptime', 'sensor_readings'\n    ], \n    'duration': 4.047666\n}\n```\n\nFor more examples, see the [`object_examples.py`](examples/object_examples.py) script in the `examples` folder.\n\n#### Deleting Data\n\nDelete queries work like any other SQL statement:\n\n```python\nresponse = crate.execute(\n    \"DELETE FROM temp_humidity WHERE sensor_id = ?\",\n    [\n        \"a02\"\n    ]\n)\n```\n\nAnd the response from the above looks like this, again including the number of rows affected:\n\n```python\n{\n    'rows': [\n        []\n    ], \n    'rowcount': 3, \n    'cols': [], \n    'duration': 66.81604\n}\n```\n\n#### Errors / Exceptions\n\nThe driver can throw the following types of exception:\n\n* `NetworkError`: when there is a network level issue, for example the hostname cannot be resolved.\n* `CrateDBError`: errors returned by the CrateDB cluster, for example when invalid SQL is submitted.\n\nHere's an example showing how to catch a network error:\n\n```python\ncrate = cratedb.CrateDB(\"nonexist\", use_ssl=False)\n\ntry:\n    response = crate.execute(\n        \"SELECT sensor_id, ts, temp FROM temp_humidity WHERE sensor_id = ? ORDER BY ts DESC\",\n        [\n            \"a01\"\n        ],\n        with_types=True\n    )\nexcept cratedb.NetworkError as e:\n    print(\"Network error:\")\n    print(e)\n```\n\nOutput:\n\n```python\nNetwork error:\n[addrinfo error 8]\n```\n\nThis example shows a `CrateDBError`:\n\n```python\ntry:\n    response = crate.execute(\n        \"SELECT nonexist FROM temp_humidity\"\n    )\nexcept cratedb.CrateDBError as e:\n    print(\"CrateDB error:\")\n    print(e)\n```\n\nOutput:\n\n```python\nCrateDB error:\n{\n    'error': {\n        'message': 'ColumnUnknownException[Column nonexist unknown]', \n        'code': 4043\n    }\n}\n```\n\nConstants for each value of `code` are provided.  For example `4043` is `CRATEDB_ERROR_UNKNOWN_COLUMN `.\n\n## Examples\n\nThe [`examples`](examples/) folder contains example MicroPython scripts, some of which are for specific microcontroller boards, including the popular Raspberry Pi Pico W.\nHardware-independent example programs also work well on CPython, and the\nMicroPython UNIX and Windows port, see [Running on CPython](./docs/cpython.md)\nand [Running on MicroPython](./docs/micropython.md).\n\n## Testing\n\nThis driver library has been tested using the following MicroPython versions:\n\n* **1.24.0** \n  * macOS/darwin ([install with Homebrew package manager](https://formulae.brew.sh/formula/micropython))\n  * Raspberry Pi Pico W ([download](https://micropython.org/download/RPI_PICO_W/))\n* **1.23.0** \n  * macOS/darwin ([install with Homebrew package manager](https://formulae.brew.sh/formula/micropython))\n  * Raspberry Pi Pico W ([download](https://micropython.org/download/RPI_PICO_W/))\n* **1.23.0 (Pimoroni build)**\n  * Raspberry Pi Pico W ([download](https://github.com/pimoroni/pimoroni-pico/releases))\n\nIf you have other microcontroller boards that you can test the driver with or provide examples for, we'd love to receive a [pull request](/pulls)!\n\n## Need Help?\n\nIf you need help, have a bug report or feature request, or just want to show us your project that uses this driver then we'd love to hear from you!\n\nFor bugs or feature requests, please raise an [issue](/issues) on GitHub.  We also welcome [pull requests](/pulls)!\n\nIf you have a project to share with us, or a more general question about this driver or CrateDB, please post in our [community forum](https://community.cratedb.com/).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrate%2Fmicropython-cratedb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrate%2Fmicropython-cratedb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrate%2Fmicropython-cratedb/lists"}