Connecting to Nemo Database

This guide explains how to connect to, configure, and manage Nemo databases using the Python SDK.

The nemo.connect() Function

The primary entry point for connecting to a Nemo database is nemo.connect().

import nemo

# Syntax:
db = nemo.connect(name: str, path: Optional[str] = None, timeout: float = 0.0)

Parameters

• name (str, required): The logical name of the database (e.g., "production", "analytics", "users").
• Only the database name is accepted.
• Do not include file extensions. Nemo strictly manages persistent .nm database files on disk.
• path (Optional[str], optional): The directory where the database file should reside. Defaults to the current working directory. Parent directories are created automatically if they do not exist.
• timeout (float, default 0.0): Connection timeout in seconds. 0.0 disables connection timeout.

Persistent Local Production Only

Nemo is designed strictly as a high-concurrency, embedded on-disk production engine. In-memory databases (:memory:) are not supported; attempting to connect with :memory: will raise a ValueError.

Return Value

Returns an instance of nemo.Database.

Connection Examples

1. Connecting by Database Name

import nemo

# Connects to or creates ./analytics.nm in current directory
db = nemo.connect("analytics")

2. Connecting with a Target Directory and Timeout

import nemo

# Connects to or creates ./data/storage/production.nm with a 5-second timeout
# Automatically creates the 'data/storage' directory if needed
db = nemo.connect("production", path="data/storage", timeout=5.0)

The nemo.Database Object

The Database instance manages the database handle, path resolution, and connector creation.

Attributes

• db.name (str): Base name of the database.
• db.path (str): Absolute filesystem path to the persistent .nm file.
• db.timeout (float): Configured connection timeout in seconds.

Connector Methods

Context Manager Usage

The Database object supports Python's with statement for automatic closing and resource cleanup.

Synchronous Context Manager

import nemo

with nemo.connect("analytics", path="data") as db:
    with db.connect_sync() as conn:
        conn.execute("CREATE TABLE metrics (id INTEGER PRIMARY KEY, value DOUBLE);")
        conn.execute("INSERT INTO metrics VALUES (?, ?);", (1, 99.4))
        result = conn.execute("SELECT * FROM metrics;")
        print(result.fetchall())

Asynchronous Context Manager

import asyncio
import nemo

async def main():
    with nemo.connect("analytics", path="data") as db:
        async with db.connect_async() as conn:
            await conn.execute("CREATE TABLE metrics (id INTEGER PRIMARY KEY, value DOUBLE);")
            await conn.execute("INSERT INTO metrics VALUES (?, ?);", (1, 99.4))
            result = await conn.execute("SELECT * FROM metrics;")
            print(await result.fetchall())

asyncio.run(main())

Connection Pooling

For multi-threaded or high-concurrency workloads, use connection pools to reuse connection leases.

Synchronous Pool

import nemo

with nemo.connect("production") as db:
    pool = db.create_pool_sync(max_connections=8)

    with pool.acquire() as conn:
        conn.execute("INSERT INTO logs VALUES (?);", ("Application started",))

    pool.close()

Asynchronous Pool

import asyncio
import nemo

async def worker(pool, worker_id: int):
    async with pool.connection() as conn:
        await conn.execute("INSERT INTO worker_events VALUES (?, ?);", (worker_id, "active"))

async def main():
    with nemo.connect("production") as db:
        pool = db.create_pool_async(max_connections=8)
        tasks = [worker(pool, i) for i in range(10)]
        await asyncio.gather(*tasks)
        await pool.close()

asyncio.run(main())

Installation

Nemo is distributed on PyPI under the official package name nemo-py:

pip install nemo-py

Import in Python as:

import nemo

Related Runnable Examples

• example_1.py: Basic Synchronous CRUD Operations and Connection Management.
• example_2.py: Asynchronous Operations and AsyncConnectionPool.
• example_10.py: Multi-Threaded Sync Connection Pooling and Concurrency.
• example_40.py: End-to-End Microservice Architecture with Connection Pools.