Metadata-Version: 2.2
Name: orbexdb-connect
Version: 0.1.0
Summary: Official Python SDK for connecting to Genorbex OrbexDB.
Author-email: Genorbex AI <support@genorbex.com>
License: MIT
Project-URL: Homepage, https://www.genorbex.com/orbexdb
Project-URL: Documentation, https://www.genorbex.com/orbexdb
Keywords: orbexdb,genorbex,database,sql,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database :: Front-Ends
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"

# OrbexDB Connect Python SDK

Connect Python applications and Genorbex notebooks directly to OrbexDB. The
SDK uses the OrbexDB native query API and has no third-party dependencies.

## Installation

```bash
python -m pip install orbexdb-connect
```

Create an OrbexDB connection/API key in the OrbexDB connection settings, then
configure the SDK:

```bash
export ORBEXDB_API_KEY="your-64-character-api-key"
export ORBEXDB_DATABASE_ID="your-database-id"
```

Managed Genorbex notebooks can use the injected runtime token instead:

```python
from orbexdb_connect import connect

db = connect(database_id="your-database-id")
```

For an external Python application:

```python
from orbexdb_connect import connect

db = connect(
    database_id="your-database-id",
    api_key="your-api-key",
    schema="PUBLIC",
)
```

## Table operations

```python
db.create_table(
    "customers",
    {
        "id": "NUMBER NOT NULL",
        "name": "VARCHAR(100)",
        "email": "VARCHAR(255)",
        "active": "BOOLEAN",
    },
)

db.insert("customers", {
    "id": 1,
    "name": "Ada",
    "email": "ada@example.com",
    "active": True,
})

db.insert("customers", [
    {"id": 2, "name": "Grace", "email": "grace@example.com", "active": True},
    {"id": 3, "name": "Linus", "email": "linus@example.com", "active": False},
])

db.update("customers", {"active": False}, where={"id": 2})
db.delete("customers", where={"id": 3})

db.merge(
    "customers",
    [
        {"id": 1, "name": "Ada Lovelace", "email": "ada@example.com", "active": True},
        {"id": 4, "name": "Margaret", "email": "margaret@example.com", "active": True},
    ],
    key_columns=["id"],
)

result = db.query("SELECT id, name FROM customers ORDER BY id")
for row in result:
    print(row["id"], row["name"])

db.truncate_table("customers")
db.drop_table("customers")
```

`update` and `delete` require a `where` mapping by default. To intentionally
affect every row, pass `allow_all=True`.

## Metadata

```python
schemas = db.list_schemas()
tables = db.list_tables()
columns = db.describe_table("customers")
```

## Raw SQL

Any SQL operation supported by OrbexDB can be executed directly:

```python
result = db.execute("SELECT CURRENT_TIMESTAMP AS now")
print(result.first())
```

Configuration can also be supplied using `ORBEXDB_TOKEN`, `ORBEXDB_USERNAME`
and `ORBEXDB_PASSWORD`, `ORBEXDB_BASE_URL`, and `ORBEXDB_DATABASE_ID`.
