{"id":47608946,"url":"https://github.com/xdb-dev/xdb","last_synced_at":"2026-04-01T19:50:28.931Z","repository":{"id":161354010,"uuid":"597338658","full_name":"xdb-dev/xdb","owner":"xdb-dev","description":"XDB is a new kind of database library based on tuples. Rather than writing database specific schemas, queries, and migrations, XDB allows developers to model their domain once and use it with one or more databases.","archived":false,"fork":false,"pushed_at":"2026-03-17T10:49:28.000Z","size":1122,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-18T01:39:33.980Z","etag":null,"topics":["database","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xdb-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-04T08:23:47.000Z","updated_at":"2026-03-17T10:49:30.000Z","dependencies_parsed_at":"2026-01-08T11:08:16.769Z","dependency_job_id":null,"html_url":"https://github.com/xdb-dev/xdb","commit_stats":null,"previous_names":["xdb-dev/xdb"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/xdb-dev/xdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdb-dev%2Fxdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdb-dev%2Fxdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdb-dev%2Fxdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdb-dev%2Fxdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xdb-dev","download_url":"https://codeload.github.com/xdb-dev/xdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdb-dev%2Fxdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","go","golang"],"created_at":"2026-04-01T19:50:24.795Z","updated_at":"2026-04-01T19:50:28.919Z","avatar_url":"https://github.com/xdb-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XDB\n\nXDB is an agent-first data layer. Model once, store anywhere. Simple URIs, structured tuples, and a pipe-friendly CLI that agents and humans both get right on the first try.\n\n## Why XDB?\n\nRead about the motivation behind XDB in [Introducing XDB](https://raviatluri.in/articles/introducing-xdb).\n\n## Core Concepts\n\n\u003e For in-depth documentation on each concept, see [docs/concepts](./docs/concepts/).\n\nThe XDB data model can be visualized as a tree of **Namespaces**, **Schemas**, **Records**, and **Tuples**.\n\n```\n┌─────────────────────────────────┐\n│            Namespace            │\n└────────────────┬────────────────┘\n                 ↓\n┌─────────────────────────────────┐\n│             Schema              │\n└────────────────┬────────────────┘\n                 ↓\n┌─────────────────────────────────┐\n│             Record              │\n└────────────────┬────────────────┘\n                 ↓\n┌─────────────────────────────────┐\n│             Tuple               │\n├─────────────────────────────────┤\n│   ID | Attr | Value | Options   │\n└─────────────────────────────────┘\n```\n\n### Tuple\n\nA **Tuple** is the fundamental building block in XDB. It combines:\n\n- ID: a string that uniquely identifies the record\n- Attr: a string that identifies the attribute. It supports dot-separated nesting.\n- Value: The attribute's value\n- Options: Key-value pairs for metadata\n\n![tuple.png](./docs/tuple.png)\n\n### Record\n\nOne or more **Tuples**, with the same **ID**, make up a **Record**. Records are similar to objects, structs, or rows in a database. Records typically represent a single entity or object of domain data.\n\n### Namespace\n\nA **Namespace** (NS) groups one or more **Schemas**. Namespaces are typically used to organize schemas by domain, application, or tenant.\n\n### Schema\n\nA **Schema** defines the structure of records and groups them together. Schemas can be \"strict\" or \"flexible\". Strict schemas enforce a predefined structure on the data, while flexible schemas allow for arbitrary data. Each schema is uniquely identified by its name within a namespace.\n\n### URI\n\nXDB URIs are valid Uniform Resource Identifiers (URI) according to [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986). URIs are used to uniquely identify resources in XDB.\n\nThe general format of a URI is:\n\n```\n    [SCHEME]://[DOMAIN] [ \"/\" PATH] [ \"?\" QUERY] [ \"#\" FRAGMENT]\n```\n\nXDB URIs follow the following format:\n\n```\n    xdb:// NS [ \"/\" SCHEMA ] [ \"/\" ID ] [ \"#\" ATTRIBUTE ]\n```\n\n```\n    xdb://com.example/posts/123-456-789#author.id\n    └─┬──┘└────┬────┘└──┬─┘└─────┬─────┘└─────┬─────┘\n   scheme     NS    SCHEMA      ID        ATTRIBUTE\n              └───────────┬───────────┘\n                       path\n```\n\nThe components of the URI are:\n\n- **NS**: The namespace.\n- **SCHEMA**: The schema name.\n- **ID**: The unique identifier of the record.\n- **ATTRIBUTE**: The name of the attribute.\n- **path**: NS, SCHEMA, and ID combined uniquely identify a record (URI without xdb://)\n\nValid examples:\n\n```\nNamespace:  xdb://com.example\nSchema:     xdb://com.example/posts\nRecord:     xdb://com.example/posts/123-456-789\nAttribute:  xdb://com.example/posts/123-456-789#author.id\n```\n\n## Supported Types\n\n| Type       | PostgreSQL         | SQLite    | Description                  |\n| ---------- | ------------------ | --------- | ---------------------------- |\n| `string`   | `TEXT`             | `TEXT`    | UTF-8 string                 |\n| `integer`  | `BIGINT`           | `INTEGER` | 64-bit signed integer        |\n| `unsigned` | `BIGINT`           | `INTEGER` | 64-bit unsigned integer      |\n| `float`    | `DOUBLE PRECISION` | `REAL`    | 64-bit floating point        |\n| `boolean`  | `BOOLEAN`          | `INTEGER` | True or false                |\n| `time`     | `TIMESTAMPTZ`      | `INTEGER` | Date and time in UTC         |\n| `json`     | `JSONB`            | `TEXT`    | Arbitrary JSON data          |\n| `bytes`    | `BYTEA`            | `BLOB`    | Binary data                  |\n| `array`    | `[]T`              | `TEXT`    | Array of typed values        |\n\n## Getting Started\n\n### Installation\n\n```bash\ngo install github.com/xdb-dev/xdb/cmd/xdb@latest\n```\n\n#### Check Version\n\n```bash\nxdb --version\n```\n\n### Quick Start\n\n```bash\n# Create schema\nxdb make-schema xdb://com.example/posts --schema posts.json\n\n# List schemas\nxdb ls xdb://com.example\n\n# Get schema\nxdb get xdb://com.example/posts\n\n# Remove schema\nxdb rm xdb://com.example/posts\n\n# Put record\nxdb put xdb://com.example/posts/post-123 --file post.json\n\n# Get record\nxdb get xdb://com.example/posts/post-123\n\n# List records\nxdb ls xdb://com.example/posts\n\n# Filter records\nxdb ls xdb://com.example/posts --filter 'title.contains(\"Hello\")'\n\n# Remove record\nxdb rm xdb://com.example/posts/post-123\n```\n\n## CLI Reference\n\n### Commands\n\n#### Make Schema\n\n```bash\n# Create schema from definition file\nxdb make-schema xdb://com.example/posts --schema ./posts.json\n\n# Create flexible schema (no definition file)\nxdb make-schema xdb://com.example/users\n```\n\n`make-schema` creates or updates a schema at the given URI. The URI must include both NS and Schema components (e.g., `xdb://com.example/posts`).\n\nIf no schema definition file is provided, a flexible schema is created. Flexible schemas allow arbitrary data without validation. Schema definitions enforce structure and types on all Tuple and Record operations.\n\n**Note:** You can update a schema by calling `make-schema` again with the same URI and a new schema definition.\n\n#### List\n\n```bash\n# List schemas in namespace\nxdb ls xdb://com.example\n\n# List with pagination\nxdb ls xdb://com.example/users --limit 10\nxdb ls xdb://com.example/users --limit 10 --offset 20\n\n# List all (default limit is 100)\nxdb ls xdb://com.example\n\n# Filter records (CEL expressions)\nxdb ls xdb://com.example/users --filter 'age \u003e 30'\nxdb ls xdb://com.example/users --filter 'name == \"alice\"'\n\n# Compound filters\nxdb ls xdb://com.example/users --filter 'age \u003e= 25 \u0026\u0026 status != \"inactive\"'\n\n# String functions\nxdb ls xdb://com.example/posts --filter 'title.contains(\"hello\")'\n\n# Combine filters with pagination\nxdb ls xdb://com.example/users --filter 'age \u003e 30' --limit 10\n```\n\n`ls` lists namespaces, schemas, or records depending on the URI. If no URI is provided, it lists all namespaces. Filters are only applied when listing records.\n\n**Flags:**\n\n- `--limit N`: Maximum number of results to return (default: 100)\n- `--offset N`: Number of results to skip (default: 0)\n- `--filter EXPR`: CEL filter expression ([AIP-160](https://google.aip.dev/160)). Operators: `==`, `!=`, `\u003e`, `\u003e=`, `\u003c`, `\u003c=`, `\u0026\u0026`, `||`, `!`, `in`. Functions: `.contains()`, `.startsWith()`, `.endsWith()`, `size()`.\n\n#### Get\n\n```bash\n# Get Namespace\nxdb get xdb://com.example\n\n# Get Schema\nxdb get xdb://com.example/posts\n\n# Get Record\nxdb get xdb://com.example/posts/post-123\n\n# Get Attribute\nxdb get xdb://com.example/posts/post-123#title\n```\n\n`get` retrieves a Namespace, Schema, Record, or Attribute from the given URI.\n\n#### Put\n\n```bash\n# Put Record from JSON file\nxdb put xdb://com.example/posts/post-123 --file post.json\n\n# Put Record from stdin (JSON)\necho '{\"title\":\"Hello\",\"content\":\"World\"}' | xdb put xdb://com.example/posts/post-123\n\n# Put Record from YAML file\nxdb put xdb://com.example/posts/post-123 --file post.yaml --format yaml\n\n# Put with explicit format\necho 'title: Hello\ncontent: World' | xdb put xdb://com.example/posts/post-123 --format yaml\n```\n\n`put` creates or updates a Record at the given URI from a JSON or YAML file, or from stdin.\n\n**Flags:**\n\n- `--file`, `-f`: Path to file (reads from stdin if omitted)\n- `--format`: Input format: json (default) or yaml\n\n#### Remove\n\n```bash\n# Remove record (with confirmation prompt)\nxdb remove xdb://com.example/posts/post-123\n\n# Remove without confirmation\nxdb rm xdb://com.example/posts/post-123 --force\n\n# Remove schema and all its records\nxdb rm xdb://com.example/posts --force --cascade\n```\n\n`remove` (aliases: `rm`, `delete`) deletes a Record, Attribute, or Schema at the given URI.\n\n**Flags:**\n\n- `--force`, `-f`: Skip confirmation prompt\n- `--cascade`: Delete schema and all its records (schema delete only)\n\n#### Daemon\n\n```bash\n# Start the daemon\nxdb daemon start\n\n# Check daemon status\nxdb daemon status\n\n# Stop the daemon\nxdb daemon stop\n\n# Force stop the daemon\nxdb daemon stop --force\n\n# Restart the daemon\nxdb daemon restart\n```\n\nThe daemon runs an HTTP server that handles all XDB operations. By default it listens on `localhost:8147` and a Unix socket at `~/.xdb/xdb.sock`.\n\n### Global Flags\n\nThese flags are available for all commands:\n\n- `--output`, `-o`: Output format (json, table, yaml). Auto-detected by default (table for TTY, JSON for pipes)\n- `--config`, `-c`: Path to config file (defaults to `~/.xdb/config.json`)\n- `--verbose`, `-v`: Enable verbose logging (INFO level)\n- `--debug`: Enable debug logging with source locations\n\n### Output Formats\n\n#### Automatic Format Selection\n\nBy default, XDB automatically selects the appropriate format:\n\n- **Table format**: When output is a terminal (TTY) - human-readable tables\n- **JSON format**: When output is piped or redirected - machine-parseable\n\n#### Available Formats\n\n- `json`: Indented JSON output (machine-readable)\n- `table`: Human-readable tables with borders\n- `yaml`: YAML output\n\n#### Example\n\n```bash\n# Uses table format (interactive terminal)\nxdb get xdb://com.example/users/123\n\n# Uses JSON format (piped to jq)\nxdb get xdb://com.example/users/123 | jq '.name'\n\n# Force JSON output even in terminal\nxdb get xdb://com.example/users/123 --output json\n\n# Force table output even when piping\nxdb ls xdb://com.example/users --output table\n```\n\n### Piping and Automation\n\nXDB commands work well with Unix pipes:\n\n```bash\n# Get record and pipe to jq\nxdb get xdb://com.example/posts/post-123 | jq '.title'\n\n# List schemas and count them\nxdb ls xdb://com.example | jq '. | length'\n\n# Export records to file\nxdb get xdb://com.example/posts/post-123 --output json \u003e backup.json\n\n# Import from file\ncat backup.json | xdb put xdb://com.example/posts/post-123\n```\n\n## Configuration\n\nXDB uses a JSON config file at `~/.xdb/config.json`. A default config is created automatically on first run.\n\n```json\n{\n  \"dir\": \"~/.xdb\",\n  \"daemon\": {\n    \"addr\": \"localhost:8147\",\n    \"socket\": \"xdb.sock\"\n  },\n  \"log_level\": \"info\",\n  \"store\": {\n    \"backend\": \"memory\"\n  }\n}\n```\n\n### Store Backends\n\n- **memory** (default): In-memory store, data is lost on restart\n- **sqlite**: SQLite database, stored in `\u003cdir\u003e/data/`\n- **redis**: Redis server, requires `addr` to be configured\n- **fs**: Filesystem store, stored in `\u003cdir\u003e/data/` by default\n\nExample with SQLite:\n\n```json\n{\n  \"store\": {\n    \"backend\": \"sqlite\",\n    \"sqlite\": {\n      \"dir\": \"\",\n      \"name\": \"xdb.db\"\n    }\n  }\n}\n```\n\nExample with Redis:\n\n```json\n{\n  \"store\": {\n    \"backend\": \"redis\",\n    \"redis\": {\n      \"addr\": \"localhost:6379\"\n    }\n  }\n}\n```\n\nSee `xdb.example.yaml` for a full reference of all configuration options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdb-dev%2Fxdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxdb-dev%2Fxdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdb-dev%2Fxdb/lists"}