Skip to content

Quick Start

Build and run your first Terranova application in under five minutes.

Step 1: Create a specification file

Create a new file called app.kdl with the following content:

application "CatManager" version="0.1" {
    entity "Cat" {
        schema {
            pk "id" type="int"
            field "name" type="string"
            field "age" type="int"
        }

        queries {
            get "cat_by_id" sql="SELECT id, name, age FROM cat WHERE id = :id" {
                param "id" type="int"
            }
        }

        views {
            template "/" query="cat_by_id" html="
                <!DOCTYPE html>
                <html>
                <head><title>Cat Profile</title></head>
                <body>
                    {{#data}}
                        <h1>{{name}}</h1>
                        <p>Age: {{age}} years</p>
                    {{/data}}
                </body>
                </html>
            "
        }
    }

    profile "dev" default=true {
        listen address="127.0.0.1" port=8080
    }
}

What's happening here?

Block Purpose
application Root container; sets name and version.
entity "Cat" Defines a data model for cats.
schema Describes the database table: primary key id, fields name and age.
queries Contains a custom get query to fetch a cat by ID (used by the HTML view).
views Exposes the query as an HTML page at / (home). The id (ie: /id?=1) in the url query is automatically passed to the respective query parameter.
profile Defines a development server listening on 127.0.0.1:8080. this profile will be automatically selected if no profile is profided at the server's starup

Auto-generated CRUD

Even though we only defined a custom get query for the HTML view, Terranova automatically creates full CRUD endpoints for every entity:

  • POST /cat/ – create a new cat
  • GET /cat/ – retrieve all cats as JSON
  • PUT /cat/ – update a cat
  • DELETE /cat/?id=<id> – delete a cat

You don't need to write any SQL for these basic operations.

Step 2: Run the application

Open a terminal in the same directory as app.kdl and run:

terranova serve

Terranova will:

  1. Parse the .kdl file.
  2. Create a SQLite database (if missing) and generate the cat table.
  3. Start an HTTP server on http://127.0.0.1:8080.

Keep the server running.

Note: You can kill the server by hitting ctr+c or cmd+c (in macos)

Step 3: Create a cat via the auto‑generated API

Open a second terminal and use curl or any other tool to send a POST request:

curl -X POST http://127.0.0.1:8080/cat\
-H "Content-Type: application/json"\
-d '{"name":"Garfield","age":5}'

Invoke-WebRequest -Uri http://127.0.0.1:8080/cat -Method POST -ContentType "application/json" -Body '{"name":"Garfield","age":5}'

You should see a response like:

{ "data": [], "count": 0, "error": null, "modified": 1 }

This means Garfield was created.

Note: The auto‑generated POST /cat endpoint expects JSON with the fields defined in the schema (name and age).

Step 4: View the cat’s HTML profile

Open your browser and visit: http://127.0.0.1:8080/?id=1

You should see:

Congratulations — you've built a working REST API with auto‑generated CRUD and a custom HTML view using Terranova!

What you learned

  • Define an entity with a schema – Terranova creates the database table and REST endpoints.
  • Auto‑generated CRUD lets you create, read, update, and delete records without writing SQL.
  • Custom queries and views allow you to build dynamic HTML pages.
  • profiles configure the server for different environments.

Next steps

  • Schemas — data models reference
  • Queries — raw SQL or composed batches of multiple queries