README
¶
XDB
XDB is a database library that provides a tuple-based abstraction for modeling, storing, and querying data across multiple databases. 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.
Why XDB?
Read about the motivation behind XDB in Introducing XDB.
Core Concepts
The XDB data model can be visualized as a tree of Namespaces, Schemas, Records, and Tuples.
┌─────────────────────────────────┐
│ Namespace │
└────────────────┬────────────────┘
↓
┌─────────────────────────────────┐
│ Schema │
└────────────────┬────────────────┘
↓
┌─────────────────────────────────┐
│ Record │
└────────────────┬────────────────┘
↓
┌─────────────────────────────────┐
│ Tuple │
├─────────────────────────────────┤
│ ID | Attr | Value | Options │
└─────────────────────────────────┘
Tuple
A Tuple is the fundamental building block in XDB. It combines:
- ID: a string that uniquely identifies the record
- Attr: a string that identifies the attribute. It supports dot-separated nesting.
- Value: The attribute's value
- Options: Key-value pairs for metadata
Record
One 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.
Namespace
A Namespace (NS) groups one or more Schemas. Namespaces are typically used to organize schemas by domain, application, or tenant.
Schema
A 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.
URI
XDB URIs are valid Uniform Resource Identifiers (URI) according to RFC 3986. URIs are used to uniquely identify resources in XDB.
The general format of a URI is:
[SCHEME]://[DOMAIN] [ "/" PATH] [ "?" QUERY] [ "#" FRAGMENT]
XDB URIs follow the following format:
xdb:// NS [ "/" SCHEMA ] [ "/" ID ] [ "#" ATTRIBUTE ]
xdb://com.example/posts/123-456-789#author.id
└─┬──┘└────┬────┘└──┬─┘└─────┬─────┘└─────┬─────┘
scheme NS SCHEMA ID ATTRIBUTE
└───────────┬───────────┘
path
The components of the URI are:
- NS: The namespace.
- SCHEMA: The schema name.
- ID: The unique identifier of the record.
- ATTRIBUTE: The name of the attribute.
- path: NS, SCHEMA, and ID combined uniquely identify a record (URI without xdb://)
Valid examples:
Namespace: xdb://com.example
Schema: xdb://com.example/posts
Record: xdb://com.example/posts/123-456-789
Attribute: xdb://com.example/posts/123-456-789#author.id
Supported Types
| Type | PostgreSQL | SQLite | Description |
|---|---|---|---|
| String | TEXT | TEXT | UTF-8 string |
| Integer | BIGINT | INTEGER | 64-bit signed integer |
| Float | DOUBLE PRECISION | REAL | 64-bit floating point number |
| Boolean | BOOLEAN | INTEGER | True or False |
| Timestamp | TIMESTAMPZ | INTEGER | Date and time in UTC |
| JSON | JSONB | TEXT | JSON data type |
| Bytes | BYTEA | BLOB | Binary data |
Building Blocks
Stores
Stores serve as the bridge between XDB's tuple-based model and specific database implementations. All stores implement basic Reader and Writer capabilities, with advanced features like full-text search, aggregation, and iteration available based on the database's capabilities.
Drivers (Deprecated)
The term "driver" has been replaced by "store" to better reflect the role of these components in XDB. Store implementations satisfy capability interfaces, allowing them to be used together or layered for complex scenarios.
Directories
¶
| Path | Synopsis |
|---|---|
|
json
Package json provides JSON encoding and decoding for XDB values.
|
Package json provides JSON encoding and decoding for XDB values. |
|
msgpack
module
|
|
|
Package core provides the fundamental data structures for XDB, a tuple-based database abstraction.
|
Package core provides the fundamental data structures for XDB, a tuple-based database abstraction. |
|
encoding
|
|
|
wkt
Package wkt provides a registry for well-known types in the XDB encoding system.
|
Package wkt provides a registry for well-known types in the XDB encoding system. |
|
xdbstruct
Package xdbstruct provides utilities for converting Go structs to XDB records and vice versa.
|
Package xdbstruct provides utilities for converting Go structs to XDB records and vice versa. |
|
examples
|
|
|
orm
command
|
|
|
Package schema provides utilities for loading and parsing XDB schemas from various file formats including JSON and YAML.
|
Package schema provides utilities for loading and parsing XDB schemas from various file formats including JSON and YAML. |
|
Package store defines core store interfaces for XDB database backends.
|
Package store defines core store interfaces for XDB database backends. |
|
xdbfs
Package xdbfs provides a filesystem-based store implementation for XDB.
|
Package xdbfs provides a filesystem-based store implementation for XDB. |
|
xdbmemory
Package xdbmemory provides an in-memory store implementation for XDB.
|
Package xdbmemory provides an in-memory store implementation for XDB. |
|
xdbsqlite
module
|
|
|
stores
|
|
|
badger
module
|
|
|
sqlite
module
|
|
|
Package tests provides shared test helpers and assertions for XDB.
|
Package tests provides shared test helpers and assertions for XDB. |
|
Package x provides utility and helper functions used throughout XDB.
|
Package x provides utility and helper functions used throughout XDB. |