NocoDB Client

A simple, Python-based wrapper and CLI for the NocoDB API v2, allowing you to interact with your NocoDB instances programmatically.

Features

• Manage Bases: List, create, and delete bases.
• Manage Tables: Create tables from JSON schema, list tables, view table metadata.
• Data Operations: Insert, update, delete, and read records.
• CLI Tools: Scripts to automate table creation and data ingestion.

Installation

From Source

Clone the repository and install using pip:

git clone <repository-url> nihook-client
cd nihook-client
pip install .

For Development

To install development dependencies (like pytest and requests-mock) along with the package:

pip install ".[dev]"

Configuration

The client relies on environment variables for connection details. You can set them in your shell or use a .env file manager.

Variable	Description	Default
NOCODB_HOST	URL of your NocoDB instance	http://localhost
NOCODB_TOKEN	Your NocoDB API Token	none
NOCODB_SSL_CERT	True/False to enable/disable verification	True

Example:

export NOCODB_HOST="https://my-nocodb.example.com"
export NOCODB_TOKEN="your-api-token-here"

Usage

As a Python Library

import os
from nihook_client import Nocodb

# Initialize client
client = Nocodb(
    host=os.getenv("NOCODB_HOST"),
    auth_token=os.getenv("NOCODB_TOKEN")
)

# List all bases
bases = client.list_bases()
print(bases)

# Get a specific base
base = client.get_base_object("My Project")

if base:
    # List tables in the base
    tables = base.list_tables()
    print(tables)
    
    # Get a specific table
    table = base.get_table_object("Employees")
    
    # Read records
    if table:
        records = table.list_records()
        for record in records['list']:
            print(record)

Error Handling

Failures raise exceptions that carry the message of the underlying problem — for NocoDB API failures that is the message NocoDB itself reported. Every exception derives from NihookClientError, so a single except clause can cover them all.

from nihook_client import NihookClientError, NocodbError, ReservedColumnError
from nihook_client.table_from_schema import create_new_table_from_schema

try:
    table_id = create_new_table_from_schema(host, token, ssl_cert, base_id, "Datasets", schema)

except ReservedColumnError as e:
    # the schema uses a key reserved for 'URL', 'status' or 'branch'
    print(f"rename '{e.column_name}' in the input schema: {e}")

except NocodbError as e:
    # e.response holds the decoded JSON body of the failed request
    print(f"NocoDB refused the request: {e} ({e.response})")

except NihookClientError as e:
    print(f"failed: {e}")

Exception	Raised when
NihookClientError	Base class of all of the below
SchemaError	The input schema cannot be mapped to a table, e.g. a key without a type
ReservedColumnError	The schema uses one of the reserved keys URL, status, branch
UnsupportedTypeError	A key has a type that has no NocoDB column equivalent
NocodbError	The NocoDB API rejected a request; .response holds the JSON body

The python3 -m nihook_client.* scripts catch these, print the message to stderr and exit with a non-zero status, so command line behaviour is unchanged.

CLI Command

The package installs a nihook-client command for checking versions and basic interaction.

nihook-client -v

Utility Scripts

The package includes several distinct modules that can be run to perform automation tasks.

1. Create Table from Schema Creates a new NocoDB table based on a JSON schema file.

python3 -m nihook_client.table_from_schema my_schema.json --base <base_id> --name "New Table"

2. Enter Dataset Imports data from a JSON file into an existing table.

python3 -m nihook_client.enter_dataset --file DATASET.json --base <base_id> --table "TableName"

Development

1. Install in editable mode with dev dependencies:

   pip install -e ".[dev]"

2. Run tests:

   pytest

Requirements

• Python 3.12+
• requests
• pandas
• python-dateutil
• jsonschema