datly

Datly 1.0

High-performance data APIs, graphs and workflows.

Keep database schemas, generated code and API contracts aligned. Datly's schema-aware transcription turns DQL and database metadata into typed Go shapes, resources and component contracts. Regenerate as projections and schemas evolve: carry type/nullability changes forward, remove generator-owned fields no longer projected, and preserve authored hooks and protected edits.

Datly is a programmable data application platform that connects databases, business logic and delivery. Compose typed data graphs across databases, orchestrate reads and mutations with scoped dependency injection, and expose the same application contracts through HTTP APIs and MCP tools for AI agents.

Build rich relational views, transactional workflows and composable analytical cubes. Extend their behavior with Go handlers, row-reading hooks, typed mutation hooks and lifecycle finalizers. Inputs, authorization predicates, validation and invocation capabilities flow through a shared execution model.

Datly's execution path combines compiled metadata, typed row processing and native SQLX readers with configurable caching, dedicated cache warmup and asynchronous jobs. Native timing records and optional OpenTelemetry export help you measure the workloads you actually run.

From a single endpoint to a data-driven service spanning multiple databases, Datly brings query execution, dependency injection, business workflows, analytics and API delivery into one programmable platform.

Start here: Programming model: DAO/service → components · DQL and grammar · Reader/writer hook flows · Generated mutators · Errors and output · Transcription · All guides

From DAO/service layers to generated components

A conventional application coordinates controllers, services, DAOs, SQL and DTOs. Datly makes the data contract and execution plan explicit, then generates the selected component artifacts while keeping business behavior in Go and scoped services.

Conventional application

sequenceDiagram
    participant API as HTTP controller
    participant Service as Application service
    participant DAO as DAO / repository
    participant DB as Database
    API->>Service: Map request and invoke business logic
    Service->>DAO: Request data or persist changes
    DAO->>DB: Execute SQL
    DB-->>DAO: Rows / write result
    DAO-->>Service: Map domain objects
    Service-->>API: Assemble response

Datly component

sequenceDiagram
    participant API as HTTP / MCP
    participant Component as Generated component
    participant Lifecycle as Application lifecycle
    participant DB as Configured databases
    Note over Component: Generated from DQL plus schema and/or Go types
    API->>Component: Bind typed input and scoped dependencies
    Component->>Lifecycle: Invoke callbacks for the selected operation
    Lifecycle-->>Component: Application behavior / validation
    Component->>DB: Execute the declared data graph
    DB-->>Component: Typed results / write outcome
    Component-->>API: Finalize and deliver output

The Datly diagram summarizes responsibilities; the reader and writer guides below show the exact callback order for each operation.

Reader and writer generation are separate choices. Datly does not automatically put both into one generated struct. Share domain contracts where appropriate and author each component for its own operation.

Explore the programming model · Read the DQL grammar · See reader and writer execution flows · Understand generated mutators and Has markers

Use it to:

• Turn database queries into useful API responses. Return typed records, assembled child collections, and separate counts or bounds without writing a DAO and transport adapter for each endpoint.
• Expose analytical views with controlled flexibility. Declare dimensions, measures, filters and selection rules; compose bounded cube queries for comparisons such as current versus previous spend.
• Keep write behavior explicit. Combine sparse input, original identities, validation, sequencing, hooks and buffered DML in generated policies or custom handlers.
• Reuse application contracts across HTTP and MCP. Select public packages, keep dependencies private, and describe the same input/output types in API metadata.
• Make operational choices deliberately. Use native SQLX read caching, separately configured warmup queries, durable async services and native execution capture, with optional OpenTelemetry export.

Release preparation on the local v1 branch. This checkout uses the canonical github.com/viant/datly module and published github.com/viant/xdatly SDK v0.5.4-0.20260914204318-08752d9972c1, with pinned native dependencies. No Datly 1.0 release tag or published CLI version is claimed. The Go Reference badge links to the public module index; it may show an earlier published version. Status records integrated behavior and remaining release gates, including separate DQL destination and native dependency integration.

Try a typed API locally

This SQLite demo builds a custom application with a reader, a writer, input initialization and output finalization. datly build discovers components and links their types and factories internally. Authors do not maintain registration or import lists.

Prerequisites: this v1 checkout, Go 1.25.8, a C compiler for SQLite, Python 3 and curl. Dependencies use the exact published versions in go.mod. Run from datly:

export GOWORK=off
export GOTOOLCHAIN=go1.25.8
export DATLY_DEMO_DIR="$(python3 doc/examples/prepare-demo.py)"
go run ./cmd/datly init -dir "$DATLY_DEMO_DIR"
go -C "$DATLY_DEMO_DIR" list -mod=mod -deps ./... > /dev/null
go run ./cmd/datly build -dir "$DATLY_DEMO_DIR" -o bin/records
"$DATLY_DEMO_DIR/bin/records" run -conf "$DATLY_DEMO_DIR/config.json"

The setup script copies the checked-in project fixture to a new disposable directory, preserves exact dependency requirements and maps the unpublished Datly main module to this checkout. Its v0.0.0 main-module requirement is a local-only placeholder paired with an explicit replacement, not a downloadable version. The go list step resolves the application build graph; Go may raise that placeholder to satisfy dependency requirements while the explicit replacement continues to select this checkout. Configuration selects a package pattern for route exposure; component discovery and linking remain build-owned.

Leave the server running. In another terminal:

curl --fail-with-body http://127.0.0.1:8080/records/1
curl --fail-with-body -H 'Content-Type: application/json' \
  -d '{"data":{"id":2,"name":"second"}}' http://127.0.0.1:8080/records
curl --fail-with-body http://127.0.0.1:8080/records/2
curl --fail-with-body http://127.0.0.1:8080/v1/api/meta/openapi

GET returns rows containing the seeded record and then the inserted record. POST returns the record under data and finalized: true. Stop with Ctrl-C; the printed demo directory retains the source, configuration and database. The demo is an unauthenticated loopback application. Add your declared authorization policy before exposing business data.

Keep the source and resources available while running this executable: custom builds are source-backed. Embedding selected assets does not make the entire application a relocatable, source-free deployment. Quickstart details and project builds explain authoring and deployment.

The source baseline's integration acceptance covers real TCP reader/mutation endpoints and add/remove package rebuilds for the custom-build fixture. Release validation must repeat these paths against the selected published dependencies.

Choose how to author

A complete DQL reader explicitly declares its package, input/output type names, a named typed output/view holder and the root row type(...). The holder binds the root result to the response field; global case_format('lc') gives the envelope and nested fields lowerCamel names. Naming an output type alone does not define that shape. See the complete Records reader and Orders reader with JSON output.

A component has typed input/output contracts and registered behavior. A view is one query-shaped dataset; relations connect datasets. A DerivedView computes another output from a parent query, while SelfReference describes an entity tree. Learn the model.

Guides

The documentation index includes reading paths. The status and evidence guide explains what each example proves and which requested features still need implementation or integration.

Develop with Datly

The authoring skills provide focused reader, writer and custom-component workflows, with grammar, examples and acceptance references. They describe both current behavior and requested contracts; pending capabilities must be checked against the connected build.

Public authoring contracts belong to the matching xdatly SDK. Datly reuses Bindly for binding, viant/x for canonical type mechanics, and SQLX for typed reads, native caches and database primitives. Original Datly is the behavior and service-boundary reference; the 1.0 implementation separates immutable metadata from invocation state. Architecture and ownership explains these boundaries.

For contribution scope and quality rules, read CONTRIBUTING.md. Review and release evidence is maintained separately from these product guides.

License and notices

Datly is licensed under the Apache License 2.0. Preserve NOTICE and the attribution files described in third-party notices when redistributing source, binaries or generated authoring bundles. The separate xdatly SDK and native dependencies retain their own licenses.