Quickstart Guide

The endpoint throws APIError.notFound. Encore returns a 404 and records the error in the trace.

The database returns sql.ErrNoRows, which the endpoint passes back. Encore maps it to a 404, returns the message sql: no rows in result set, and records the error in the trace.

Open url/url.ts. This is the endpoint you just traced:

url/url.ts
TypeScript
import { api } from "encore.dev/api";
import { SQLDatabase } from "encore.dev/storage/sqldb";
import { randomBytes } from "node:crypto";

// 'url' database is used to store the URLs that are being shortened.
const db = new SQLDatabase("url", { migrations: "./migrations" });

// shorten shortens a URL.
export const shorten = api(
  { expose: true, auth: false, method: "POST", path: "/url" },
  async ({ url }: ShortenParams): Promise<URL> => {
    const id = randomBytes(6).toString("base64url");
    await db.exec`
        INSERT INTO url (id, original_url)
        VALUES (${id}, ${url})
    `;
    return { id, url };
  }
);

This is standard TypeScript. Two declarations connect it to Encore:

• api defines a public endpoint. Encore handles routing, request validation, error handling, observability, and API documentation.
• new SQLDatabase(...) declares the database. Encore uses the declaration to provision PostgreSQL and include its queries in traces.

The shorten endpoint belongs to the url service, defined by encore.service.ts in the same folder:

url/encore.service.ts
TypeScript
import { Service } from "encore.dev/service";

export default new Service("url");

Everything under url/ belongs to the url service. To add another service, create a directory with an encore.service.ts that exports a new Service.

Learn more about services, APIs, and databases.

Open url/url.go. This is the endpoint you just traced:

url/url.go
TypeScript
package url

import (
	"context"

	"encore.dev/storage/sqldb"
)

// Shorten shortens a URL.
//
//encore:api public method=POST path=/url
func Shorten(ctx context.Context, p *ShortenParams) (*URL, error) {
	id, err := generateID()
	if err != nil {
		return nil, err
	} else if err := insert(ctx, id, p.URL); err != nil {
		return nil, err
	}
	return &URL{ID: id, URL: p.URL}, nil
}

// 'url' database is used to store the URLs that are being shortened.
var db = sqldb.NewDatabase("url", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})

This is standard Go. Two declarations connect it to Encore:

• //encore:api public defines Shorten as a public endpoint in the url service. Encore handles routing, request validation, error handling, observability, and API documentation.
• sqldb.NewDatabase(...) declares the database. Encore uses the declaration to provision PostgreSQL and include its queries in traces.

To add another service, create a Go package and annotate its endpoints the same way. Learn more about defining APIs and databases.

The Encore.ts SDK lets you declare infrastructure directly in code, including Pub/Sub topics, object storage, and cron jobs.

The Encore.go SDK lets you declare infrastructure directly in code, including Pub/Sub topics, object storage, and cron jobs.

A directory containing an encore.service.ts defines a service, so add stats/ next to the existing url/ directory:

TypeScript
/your-app-name
├── url                       // existing url service
│   ├── encore.service.ts
│   ├── migrations
│   └── url.ts
└── stats                     // new stats service
    ├── encore.service.ts
    └── stats.ts

Create stats/encore.service.ts:

stats/encore.service.ts
TypeScript
import { Service } from "encore.dev/service";

export default new Service("stats");

Next, create stats/stats.ts. Importing from ~encore/clients lets you call the url service like a local function:

stats/stats.ts
TypeScript
import { api } from "encore.dev/api";
import { url } from "~encore/clients";

export const count = api(
  { expose: true, method: "GET", path: "/stats" },
  async (): Promise<{ total: number }> => {
    const { urls } = await url.list();
    return { total: urls.length };
  }
);

A Go package with an API endpoint defines a service, so add stats/ next to the existing url/ directory:

TypeScript
/your-app-name
├── url                       // existing url service
│   ├── migrations
│   ├── index.go
│   └── url.go
└── stats                     // new stats service
    └── stats.go

The url service doesn't have an endpoint that returns a total, so add one to url/url.go. Marking it private makes it callable from other services, but not from outside the application:

url/url.go
TypeScript
var db = sqldb.NewDatabase("url", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})

type CountResponse struct {
	Total int
}

// The path can't be /url/count, which would conflict with /url/:id.
//
//encore:api private method=GET path=/url-count
func Count(ctx context.Context) (*CountResponse, error) {
	var total int
	err := db.QueryRow(ctx, `SELECT count(*) FROM url`).Scan(&total)
	return &CountResponse{Total: total}, err
}

Create stats/stats.go. Importing encore.app/url lets you call the url service like a local function:

stats/stats.go
TypeScript
package stats

import (
	"context"

	"encore.app/url"
)

type Response struct {
	Total int
}

//encore:api public method=GET path=/stats
func Count(ctx context.Context) (*Response, error) {
	resp, err := url.Count(ctx)
	if err != nil {
		return nil, err
	}
	return &Response{Total: resp.Total}, nil
}

In the API Explorer, call stats.count, then open its trace. You'll see a single request spanning two services, including the call to url.list and its database query.

In the API Explorer, call stats.Count, then open its trace. You'll see a single request spanning two services, including the call to url.Count and its database query.

Create the migration that defines its schema:

stats/migrations/1_create_clicks.up.sql
TypeScript
CREATE TABLE clicks (
    id TEXT PRIMARY KEY,
    clicks BIGINT NOT NULL DEFAULT 0
);

Declare the database and an endpoint to record clicks in stats/stats.ts:

stats/stats.ts
TypeScript
import { api } from "encore.dev/api";
import { url } from "~encore/clients";
import { SQLDatabase } from "encore.dev/storage/sqldb";

export const db = new SQLDatabase("stats", { migrations: "./migrations" });

export const record = api(
  { expose: true, method: "POST", path: "/stats/:id" },
  async ({ id }: { id: string }): Promise<void> => {
    await db.exec`
        INSERT INTO clicks (id, clicks) VALUES (${id}, 1)
        ON CONFLICT (id) DO UPDATE SET clicks = clicks.clicks + 1
    `;
  }
);

export const count = api(
  { expose: true, method: "GET", path: "/stats" },
  async (): Promise<{ total: number }> => {
    const { urls } = await url.list();
    return { total: urls.length };
  }
);

Create the migration that defines its schema:

stats/migrations/1_create_clicks.up.sql
TypeScript
CREATE TABLE clicks (
    id TEXT PRIMARY KEY,
    clicks BIGINT NOT NULL DEFAULT 0
);

Declare the database and an endpoint to record clicks in stats/stats.go:

stats/stats.go
TypeScript
package stats

import (
	"context"

	"encore.app/url"
	"encore.dev/storage/sqldb"
)

var db = sqldb.NewDatabase("stats", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})

//encore:api public method=POST path=/stats/:id
func Record(ctx context.Context, id string) error {
	_, err := db.Exec(ctx, `
        INSERT INTO clicks (id, clicks) VALUES ($1, 1)
        ON CONFLICT (id) DO UPDATE SET clicks = clicks.clicks + 1
    `, id)
	return err
}

type Response struct {
	Total int
}

//encore:api public method=GET path=/stats
func Count(ctx context.Context) (*Response, error) {
	resp, err := url.Count(ctx)
	if err != nil {
		return nil, err
	}
	return &Response{Total: resp.Total}, nil
}

In the API Explorer, call stats.record with any id, a few times over. Open DB Explorer, switch to the stats database, and select the clicks table to see the count increase.

In the API Explorer, call stats.Record with any id, a few times over. Open DB Explorer, switch to the stats database, and select the clicks table to see the count increase.

First, add the Pub/Sub import to url/url.ts:

url/url.ts
TypeScript
import { Topic } from "encore.dev/pubsub";

Then declare the topic alongside the existing database:

url/url.ts
TypeScript
const db = new SQLDatabase("url", { migrations: "./migrations" });

export interface ShortenedEvent {
  id: string;
  url: string;
}

export const shortened = new Topic<ShortenedEvent>("shortened", {
  deliveryGuarantee: "at-least-once",
});

Then publish an event from shorten, immediately after the INSERT:

url/url.ts
TypeScript
export const shorten = api(
  { expose: true, auth: false, method: "POST", path: "/url" },
  async ({ url }: ShortenParams): Promise<URL> => {
    const id = randomBytes(6).toString("base64url");
    await db.exec`
        INSERT INTO url (id, original_url)
        VALUES (${id}, ${url})
    `;
    await shortened.publish({ id, url });
    return { id, url };
  }
);

Finally, create stats/subscriptions.ts to subscribe from the stats service:

stats/subscriptions.ts
TypeScript
import { Subscription } from "encore.dev/pubsub";
import { shortened } from "../url/url";
import { db } from "./stats";

const _ = new Subscription(shortened, "count-shortened", {
  handler: async (event) => {
    await db.exec`
        INSERT INTO clicks (id, clicks) VALUES (${event.id}, 1)
        ON CONFLICT (id) DO UPDATE SET clicks = clicks.clicks + 1
    `;
  },
});

First, add the Pub/Sub import to url/url.go:

url/url.go
TypeScript
import "encore.dev/pubsub"

Then declare the topic alongside the existing database:

url/url.go
TypeScript
var db = sqldb.NewDatabase("url", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})

type ShortenedEvent struct {
	ID  string
	URL string
}

var Shortened = pubsub.NewTopic[*ShortenedEvent]("shortened", pubsub.TopicConfig{
	DeliveryGuarantee: pubsub.AtLeastOnce,
})

Then publish an event from Shorten, immediately after the insert:

url/url.go
TypeScript
//encore:api public method=POST path=/url
func Shorten(ctx context.Context, p *ShortenParams) (*URL, error) {
	id, err := generateID()
	if err != nil {
		return nil, err
	} else if err := insert(ctx, id, p.URL); err != nil {
		return nil, err
	}
	if _, err := Shortened.Publish(ctx, &ShortenedEvent{ID: id, URL: p.URL}); err != nil {
		return nil, err
	}
	return &URL{ID: id, URL: p.URL}, nil
}

Finally, create stats/subscriptions.go to subscribe from the stats service:

stats/subscriptions.go
TypeScript
package stats

import (
	"context"

	"encore.app/url"
	"encore.dev/pubsub"
)

var _ = pubsub.NewSubscription(
	url.Shortened, "count-shortened",
	pubsub.SubscriptionConfig[*url.ShortenedEvent]{
		Handler: func(ctx context.Context, event *url.ShortenedEvent) error {
			_, err := db.Exec(ctx, `
        INSERT INTO clicks (id, clicks) VALUES ($1, 1)
        ON CONFLICT (id) DO UPDATE SET clicks = clicks.clicks + 1
    `, event.ID)
			return err
		},
	},
)