Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 21 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# MicroCrate - A CrateDB Driver for MicroPython
# micropython-cratedb - A CrateDB Driver for MicroPython

## Introduction

MicroCrate 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).
micropython-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).

To 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).

Expand Down Expand Up @@ -41,15 +41,15 @@ mip.install("github:simonprickett/microcrate")
Import the driver like this:

```python
import microcrate
import cratedb
```

### Connecting to CrateDB

Connect to a CrateDB cluster in the cloud by providing hostname, user name and password:

```python
crate = microcrate.CrateDB(
crate = cratedb.CrateDB(
host="host",
user="user",
password="password"
Expand All @@ -61,7 +61,7 @@ The driver uses SSL by default.
If you're running CrateDB locally (with Docker for example), connect like this:

```python
crate = microcrate.CrateDB(
crate = cratedb.CrateDB(
host="hostname",
use_ssl=False
)
Expand All @@ -70,7 +70,7 @@ crate = microcrate.CrateDB(
The driver will connect to port 4200 unless you provide an alternative value:

```python
crate = microcrate.CrateDB(
crate = cratedb.CrateDB(
host="host",
user="user",
port=4201,
Expand Down Expand Up @@ -287,7 +287,7 @@ The response includes the number of rows affected by the update:

CrateDB 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.

Here are some basic examples showing how to store objects with MicroCrate and retrieve desired fields from them.
Here are some basic examples showing how to store objects with micropython-cratedb and retrieve desired fields from them.

Assume a table with the following definition having a [dynamic object](https://cratedb.com/blog/handling-dynamic-objects-in-cratedb) column:

Expand Down Expand Up @@ -389,7 +389,7 @@ The driver can throw the following types of exception:
Here's an example showing how to catch a network error:

```python
crate = microcrate.CrateDB("nonexist", use_ssl = False)
crate = cratedb.CrateDB("nonexist", use_ssl = False)

try:
response = crate.execute(
Expand All @@ -399,7 +399,7 @@ try:
],
with_types=True
)
except microcrate.NetworkError as e:
except cratedb.NetworkError as e:
print("Network error:")
print(e)
```
Expand All @@ -418,7 +418,7 @@ try:
response = crate.execute(
"SELECT nonexist FROM temp_humidity"
)
except microcrate.CrateDBError as e:
except cratedb.CrateDBError as e:
print("CrateDB error:")
print(e)
```
Expand All @@ -443,20 +443,23 @@ The [`examples`](examples/) folder contains example MicroPython scripts, some of

## Testing

This driver library was tested using the following MicroPython versions:
This driver library has been tested using the following MicroPython versions:

* **1.23.0** ([download](https://micropython.org/download/))
* macOS/darwin
* Raspberry Pi Pico W
* **1.23.0 (Pimoroni build)** ([download](https://github.com/pimoroni/pimoroni-pico/releases))
* Raspberry Pi Pico W
* **1.24.0**
* macOS/darwin ([install with Homebrew package manager](https://formulae.brew.sh/formula/micropython))
* Raspberry Pi Pico W ([download](https://micropython.org/download/RPI_PICO_W/))
* **1.23.0**
* macOS/darwin ([install with Homebrew package manager](https://formulae.brew.sh/formula/micropython))
* Raspberry Pi Pico W ([download](https://micropython.org/download/RPI_PICO_W/))
* **1.23.0 (Pimoroni build)**
* Raspberry Pi Pico W ([download](https://github.com/pimoroni/pimoroni-pico/releases))

If you have other microcontroller boards that you can test the driver with or provide examples for, we'd love to receive a pull request!
If 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)!

## Need Help?

If 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!

For bugs or feature requests, please raise an issue on GitHub. We also welcome pull requests!
For bugs or feature requests, please raise an [issue](/issues) on GitHub. We also welcome [pull requests](/pulls)!

If 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/).
File renamed without changes.
4 changes: 2 additions & 2 deletions examples/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# MicroCrate Examples
# micropython-cratedb Examples

This folder contains code samples and fully working example code for the MicroCrate driver.
This folder contains code samples and fully working example code for the micropython-cratedb driver.

* `example_usage.py`: Demonstrates various types of query. This does not have any specific microcontroller dependencies, and can be run on desktop MicroPython.
* `object_examples.py`: Demonstrates operations using an [OBJECT](https://cratedb.com/docs/crate/reference/en/latest/general/ddl/data-types.html#objects) column in CrateDB. Also demonstrates the use of the [ARRAY](https://cratedb.com/docs/crate/reference/en/latest/general/ddl/data-types.html#array) container data type.
Expand Down
10 changes: 5 additions & 5 deletions examples/example_usage.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
# in any MicroPython environment. You will need to edit the
# code below to use your CrateDB credentials.

import microcrate
import cratedb

# CrateDB Docker / local network, no SSL.
# crate = microcrate.CrateDB(host="hostname", use_ssl=False)
# crate = cratedb.CrateDB(host="hostname", use_ssl=False)

# CrateDB Cloud.
crate = microcrate.CrateDB(
crate = cratedb.CrateDB(
host="host",
user="user",
password="password"
Expand Down Expand Up @@ -84,9 +84,9 @@
# This will throw a CrateDBError as we dropped the table.
response = crate.execute("select * from driver_test")

except microcrate.NetworkError as e:
except cratedb.NetworkError as e:
print("Caught NetworkError:")
print(e)
except microcrate.CrateDBError as c:
except cratedb.CrateDBError as c:
print("Caught CrateDBError:")
print(c)
10 changes: 5 additions & 5 deletions examples/object_examples.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
# run in any MicroPython environment. You will need to edit the
# code below to use your CrateDB credentials.

import microcrate
import cratedb

# CrateDB Docker / local network, no SSL.
# crate = microcrate.CrateDB(host="hostname", use_ssl=False)
# crate = cratedb.CrateDB(host="hostname", use_ssl=False)

# CrateDB Cloud.
crate = microcrate.CrateDB(
crate = cratedb.CrateDB(
host="host",
user="user",
password="password"
Expand Down Expand Up @@ -325,9 +325,9 @@
# {'rows': [[]], 'rowcount': 1, 'cols': [], 'duration': 67.91708}
print(response)

except microcrate.NetworkError as e:
except cratedb.NetworkError as e:
print("Caught NetworkError:")
print(e)
except microcrate.CrateDBError as c:
except cratedb.CrateDBError as c:
print("Caught CrateDBError:")
print(c)
8 changes: 4 additions & 4 deletions examples/picow_demo.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# MicroCrate Example for the Raspberry Pi Pico W.
# micropython-cratedb Example for the Raspberry Pi Pico W.
# Configure your CrateDB credentials and WiFi SSID
# and password below before running this.

Expand All @@ -7,10 +7,10 @@
import sys
import time

import microcrate
import cratedb

# Configure CrateDB driver.
crate = microcrate.CrateDB(
crate = cratedb.CrateDB(
host="hostname",
user="username",
password="password"
Expand Down Expand Up @@ -65,7 +65,7 @@
"INSERT INTO picow_test (id, temp) VALUES (?, ?)",
[
ip_addr,
temperature # TODO what units are these?
temperature
]
)

Expand Down
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"urls": [
[
"microcrate.py",
"github:simonprickett/microcrate/microcrate.py"
"cratedb.py",
"github:simonprickett/microcrate/cratedb.py"
]
],
"deps": [
Expand Down