Quickstart

In this quickstart guide, you'll learn the typical workflow with Teo from creating an empty project, setting up a connection with a local database to sending HTTP requests with the generated query client.

Choose your stack

Before getting started, pick and select your own technical stack. And this guide will just be tailored for you. Also, your preferences are saved locally. The next time you open any documentation in our site, your tech stack preferences are preserved and restored for you.

Rust

Node.js

Python

MySQL

PostgreSQL

SQLite

MongoDB

TypeScript

Swift

Kotlin

C#

Dart

Prerequisites

You need Rust 1.75.0 or higher for this guide. If you don't have Rust installed, see this installation guide from Rust.

1. Create a new project and set up Teo

As a first step, create a project with cargo and navigate into it:

cargo new hello-teo --bin
cd hello-teo

Next, install Teo command line tool globally with this command:

cargo install teo

This installs Teo CLI into the cargo global path.

2. Connect to database and set up server

Create a file at project root directory named schema.teo with the following content:

connector {
  provider: .mysql,
  url: "mysql://127.0.0.1:3306/helloteo"
}

Within this connector config block, we specified the database to connect. Next, let's declare a server block to specify the port that this HTTP server should be listening on. We specified the port value 5050. Our server will be listening on port 5050 after started.

server {
  bind: ("0.0.0.0", 5050)
}
 
request middlewares [logRequest]

Look at the request middlewares thing. There is a middleware in the standard library called logRequest. It will log each incoming requests to the console.

3. Model your data in the schema

Now time for modeling data. Let's dive right in to declare some models.

model User {
  @id @autoIncrement @readonly
  id: Int
  @unique @onSet($if($presents, $isEmail))
  email: String
  name: String?
  @relation(fields: .id, references: .authorId)
  posts: Post[]
}
 
model Post {
  @id @autoIncrement @readonly
  id: Int
  title: String
  content: String?
  @default(false)
  published: Bool
  @foreignKey
  authorId: Int
  @relation(fields: .authorId, references: .id)
  author: User
}

Models in the Teo schema have two main purposes:

• Represent the tables or collections in the underlying database
• Represent a group of API resource including handler actions like findMany, findUnique, create, etc.

4. Generate query client

If you start the server with cargo teo serve, you can already see server started and listening on the desired port. Instead of writing each HTTP request on the frontend, Teo can generate a client for you with great auto completion.

Add this block into schema.teo:

client ts {
  provider: .typeScript,
  dest: "../hello-teo-client/",
  package: true,
  host: .string("http://127.0.0.1:5050"),
  gitCommit: true
}

Now let's run this command to generate a brand new client.

cargo teo generate client

5. Send HTTP requests with query client

Start a development server with this command:

cargo teo serve

Now navigate to the generated client and write some code to perform HTTP requests.

cd ../hello-teo-client

Create a file named hello.ts in the root directory of the generated client with the following content:

import { teo } from './src/index.js'
 
async function main() {
  const results = await teo.user.create({
    create: {
      email: "ada@teodev.io",
      name: "Ada",
      posts: {
        create: [
          {
            title: "Framework TEO",
            content: "This post introduces Teo."
          },
          {
            title: "The next generation",
            content: "Use the next generation technology."
          }
        ]
      }
    },
    include: {
      posts: true
    }
  })
  console.log(results.data)
}
 
main()

Install ts-node and run this file.

npm install -D ts-node
node --loader ts-node/esm hello.ts

{
  id: 1,
  email: 'ada@teodev.io',
  name: 'Ada',
  posts: [
    {
      id: 1,
      title: 'Framework TEO',
      content: 'This post introduces Teo.',
      published: false,
      authorId: 1
    },
    {
      id: 2,
      title: 'The next generation',
      content: 'Use the next generation technology.',
      published: false,
      authorId: 1
    }
  ]
}

We've just created an object with nested relations. See how easy it is. We lift Teo to do a lot of heavy work for us.

6. Next steps

In this Quickstart guide, you have a brief overview and understand how Teo works. To learn further, read our Beginner tutorial. Feel free to explore the server & clients API a bit more on your own, e.g. by including filtering, sorting, and pagination options in the findMany requests or exploring more operations like update and delete objects.

Join the Teo community 💚

Teo is great and needs your support. Join us on Discord or ask questions via GitHub Discussions.