cinchdb


Namecinchdb JSON
Version 0.1.3 PyPI version JSON
download
home_pageNone
SummaryA Git-like SQLite database management system with branching and multi-tenancy
upload_time2025-07-31 21:46:31
maintainerNone
docs_urlNone
authorRussell Romney
requires_python>=3.10
licenseMIT
keywords branching database git multi-tenant sqlite
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # CinchDB

**Git-like SQLite database management with branching and multi-tenancy**

NOTE: CinchDB is in early alpha. This is project to test out an idea. Do not use this in production.

CinchDB is for projects that need fast queries, data isolated data per-tenant [or even per-user](https://turso.tech/blog/give-each-of-your-users-their-own-sqlite-database-b74445f4), and a branchable database.

On a meta level, I made this because I wanted a database structure that I felt comfortable letting AI agents take full control over, safely, and I didn't want to run my own Postgres instance somewhere or pay for it on e.g. Neon - I don't need hyperscaling, I just need super fast queries.

Because it's so lightweight and its only dependencies are pydantic, requests, and Typer, it makes for a perfect local development database that can be controlled programmatically.


```bash
uv pip install cinchdb

# Initialize project
cinch init 

# Create and query tables
cinch table create users name:TEXT email:TEXT
cinch query "SELECT * FROM users"

# Git-like branching
cinch branch create feature
cinch branch switch feature
cinch table create products name:TEXT price:REAL
cinch branch merge-into-main feature

# Multi-tenant support
cinch tenant create customer_a
cinch query "SELECT * FROM users" --tenant customer_a

# Connect to remote CinchDB instance
cinch remote add production https://your-cinchdb-server.com your-api-key
cinch remote use production

# Autogenerate Python SDK from database
cinch codegen generate python cinchdb_models/
```

## What is CinchDB?

CinchDB combines SQLite with Git-like workflows for database schema management:

- **Branch schemas** like code - create feature branches, make changes, merge back
- **Multi-tenant isolation** - shared schema, isolated data per tenant
- **Automatic change tracking** - all schema changes tracked and mergeable
- **Safe structure changes** - change merges happen atomically with zero rollback risk (seriously)
- **Remote connectivity** - Connect to hosted CinchDB instances
- **Type-safe SDK** - Python and TypeScript SDKs with full type safety
- **Remote-capable** - CLI and SDK can connect to remote instances
- **SDK generation from database schema** - Generate a typesafe SDK from your database models for CRUD operations

## Installation

Requires Python 3.10+:

```bash
pip install cinchdb
```

## Quick Start

### CLI Usage

```bash
# Initialize project
cinch init my_app
cd my_app

# Create schema on feature branch
cinch branch create user-system
cinch table create users username:TEXT email:TEXT
cinch view create active_users "SELECT * FROM users WHERE created_at > datetime('now', '-30 days')"

# Merge to main
cinch branch merge-into-main user-system

# Multi-tenant operations
cinch tenant create customer_a
cinch tenant create customer_b
cinch query "SELECT COUNT(*) FROM users" --tenant customer_a
```

### Python SDK

```python
import cinchdb
from cinchdb.models import Column

# Local connection
db = cinchdb.connect("myapp")

# Create schema
db.create_table("posts", [
    Column(name="title", type="TEXT",nullable=False),
    Column(name="content", type="TEXT")
])

# Query data
results = db.query("SELECT * FROM posts WHERE title LIKE ?", ["%python%"])

# CRUD operations
post_id = db.insert("posts", {"title": "Hello World", "content": "First post"})
db.update("posts", post_id, {"content": "Updated content"})
```

### Remote Connection

```python
# Connect to remote instance
db = cinchdb.connect("myapp", url="https://your-cinchdb-server.com", api_key="your-api-key")

# Same interface as local
results = db.query("SELECT * FROM users")
user_id = db.insert("users", {"username": "alice", "email": "alice@example.com"})
```

## Remote Access

Connect to a remote CinchDB instance:

```bash
cinch remote add production https://your-cinchdb-server.com your-api-key
cinch remote use production
# Now all commands will use the remote instance
```

Interactive docs at `/docs`, health check at `/health`.

## Architecture

- **Python SDK**: Core functionality (local + remote)
- **CLI**: Full-featured command-line interface  
- **Remote Access**: Connect to hosted CinchDB instances
- **TypeScript SDK**: Browser and Node.js client

## Development

```bash
git clone https://github.com/russellromney/cinchdb.git
cd cinchdb
make install-all
make test
```

## Future

Though probably not, perhaps I'll evolve it into something bigger and more full-featured, with things like
- data backups
- replication to S3
- audit access
- SaaS-like dynamics
- multi-project hosting
- auth proxying
- leader-follower abilities for edge deployment


## License

Apache 2.0 - see [LICENSE](LICENSE)

---

**CinchDB** - Database management as easy as version control

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "cinchdb",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "branching, database, git, multi-tenant, sqlite",
    "author": "Russell Romney",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/08/34/5fe286f65849f4978c00eec48c29d3bf8a5859e6d6d7c26e4f9a407b46e1/cinchdb-0.1.3.tar.gz",
    "platform": null,
    "description": "# CinchDB\n\n**Git-like SQLite database management with branching and multi-tenancy**\n\nNOTE: CinchDB is in early alpha. This is project to test out an idea. Do not use this in production.\n\nCinchDB is for projects that need fast queries, data isolated data per-tenant [or even per-user](https://turso.tech/blog/give-each-of-your-users-their-own-sqlite-database-b74445f4), and a branchable database.\n\nOn a meta level, I made this because I wanted a database structure that I felt comfortable letting AI agents take full control over, safely, and I didn't want to run my own Postgres instance somewhere or pay for it on e.g. Neon - I don't need hyperscaling, I just need super fast queries.\n\nBecause it's so lightweight and its only dependencies are pydantic, requests, and Typer, it makes for a perfect local development database that can be controlled programmatically.\n\n\n```bash\nuv pip install cinchdb\n\n# Initialize project\ncinch init \n\n# Create and query tables\ncinch table create users name:TEXT email:TEXT\ncinch query \"SELECT * FROM users\"\n\n# Git-like branching\ncinch branch create feature\ncinch branch switch feature\ncinch table create products name:TEXT price:REAL\ncinch branch merge-into-main feature\n\n# Multi-tenant support\ncinch tenant create customer_a\ncinch query \"SELECT * FROM users\" --tenant customer_a\n\n# Connect to remote CinchDB instance\ncinch remote add production https://your-cinchdb-server.com your-api-key\ncinch remote use production\n\n# Autogenerate Python SDK from database\ncinch codegen generate python cinchdb_models/\n```\n\n## What is CinchDB?\n\nCinchDB combines SQLite with Git-like workflows for database schema management:\n\n- **Branch schemas** like code - create feature branches, make changes, merge back\n- **Multi-tenant isolation** - shared schema, isolated data per tenant\n- **Automatic change tracking** - all schema changes tracked and mergeable\n- **Safe structure changes** - change merges happen atomically with zero rollback risk (seriously)\n- **Remote connectivity** - Connect to hosted CinchDB instances\n- **Type-safe SDK** - Python and TypeScript SDKs with full type safety\n- **Remote-capable** - CLI and SDK can connect to remote instances\n- **SDK generation from database schema** - Generate a typesafe SDK from your database models for CRUD operations\n\n## Installation\n\nRequires Python 3.10+:\n\n```bash\npip install cinchdb\n```\n\n## Quick Start\n\n### CLI Usage\n\n```bash\n# Initialize project\ncinch init my_app\ncd my_app\n\n# Create schema on feature branch\ncinch branch create user-system\ncinch table create users username:TEXT email:TEXT\ncinch view create active_users \"SELECT * FROM users WHERE created_at > datetime('now', '-30 days')\"\n\n# Merge to main\ncinch branch merge-into-main user-system\n\n# Multi-tenant operations\ncinch tenant create customer_a\ncinch tenant create customer_b\ncinch query \"SELECT COUNT(*) FROM users\" --tenant customer_a\n```\n\n### Python SDK\n\n```python\nimport cinchdb\nfrom cinchdb.models import Column\n\n# Local connection\ndb = cinchdb.connect(\"myapp\")\n\n# Create schema\ndb.create_table(\"posts\", [\n    Column(name=\"title\", type=\"TEXT\",nullable=False),\n    Column(name=\"content\", type=\"TEXT\")\n])\n\n# Query data\nresults = db.query(\"SELECT * FROM posts WHERE title LIKE ?\", [\"%python%\"])\n\n# CRUD operations\npost_id = db.insert(\"posts\", {\"title\": \"Hello World\", \"content\": \"First post\"})\ndb.update(\"posts\", post_id, {\"content\": \"Updated content\"})\n```\n\n### Remote Connection\n\n```python\n# Connect to remote instance\ndb = cinchdb.connect(\"myapp\", url=\"https://your-cinchdb-server.com\", api_key=\"your-api-key\")\n\n# Same interface as local\nresults = db.query(\"SELECT * FROM users\")\nuser_id = db.insert(\"users\", {\"username\": \"alice\", \"email\": \"alice@example.com\"})\n```\n\n## Remote Access\n\nConnect to a remote CinchDB instance:\n\n```bash\ncinch remote add production https://your-cinchdb-server.com your-api-key\ncinch remote use production\n# Now all commands will use the remote instance\n```\n\nInteractive docs at `/docs`, health check at `/health`.\n\n## Architecture\n\n- **Python SDK**: Core functionality (local + remote)\n- **CLI**: Full-featured command-line interface  \n- **Remote Access**: Connect to hosted CinchDB instances\n- **TypeScript SDK**: Browser and Node.js client\n\n## Development\n\n```bash\ngit clone https://github.com/russellromney/cinchdb.git\ncd cinchdb\nmake install-all\nmake test\n```\n\n## Future\n\nThough probably not, perhaps I'll evolve it into something bigger and more full-featured, with things like\n- data backups\n- replication to S3\n- audit access\n- SaaS-like dynamics\n- multi-project hosting\n- auth proxying\n- leader-follower abilities for edge deployment\n\n\n## License\n\nApache 2.0 - see [LICENSE](LICENSE)\n\n---\n\n**CinchDB** - Database management as easy as version control\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A Git-like SQLite database management system with branching and multi-tenancy",
    "version": "0.1.3",
    "project_urls": {
        "Documentation": "https://russellromney.github.io/cinchdb",
        "Homepage": "https://github.com/russellromney/cinchdb",
        "Issues": "https://github.com/russellromney/cinchdb/issues",
        "Repository": "https://github.com/russellromney/cinchdb"
    },
    "split_keywords": [
        "branching",
        " database",
        " git",
        " multi-tenant",
        " sqlite"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "0b8713b8f2f4d6335e6e190c251c19c75d414eab0cac88bf481cc0c3b57656a2",
                "md5": "c629760580f95fa9d59204140e2563dc",
                "sha256": "341c1317bbd7b46c3b7d0a536e1aa93cfce75133fdeb871aa225b681cbedc1f8"
            },
            "downloads": -1,
            "filename": "cinchdb-0.1.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c629760580f95fa9d59204140e2563dc",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 85844,
            "upload_time": "2025-07-31T21:46:30",
            "upload_time_iso_8601": "2025-07-31T21:46:30.780415Z",
            "url": "https://files.pythonhosted.org/packages/0b/87/13b8f2f4d6335e6e190c251c19c75d414eab0cac88bf481cc0c3b57656a2/cinchdb-0.1.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "08345fe286f65849f4978c00eec48c29d3bf8a5859e6d6d7c26e4f9a407b46e1",
                "md5": "185b334f284ecd66fd17608119eb16d0",
                "sha256": "2c42cf0fc1ac8a9379adb33d6aca4ba903d2f5915f71d5764dc960a56299c688"
            },
            "downloads": -1,
            "filename": "cinchdb-0.1.3.tar.gz",
            "has_sig": false,
            "md5_digest": "185b334f284ecd66fd17608119eb16d0",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 60009,
            "upload_time": "2025-07-31T21:46:31",
            "upload_time_iso_8601": "2025-07-31T21:46:31.694667Z",
            "url": "https://files.pythonhosted.org/packages/08/34/5fe286f65849f4978c00eec48c29d3bf8a5859e6d6d7c26e4f9a407b46e1/cinchdb-0.1.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-31 21:46:31",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "russellromney",
    "github_project": "cinchdb",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "cinchdb"
}
        
Elapsed time: 0.76016s