Encore.ts 声明式基础设施：PostgreSQL、Redis、Pub/Sub、定时任务、对象存储

encore-infrastructure by encoredev/skills

167 周安装量

20 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/encoredev/skills --skill encore-infrastructure

开发云服务开发运维

🇨🇳中文介绍

Encore 基础设施声明

说明

Encore.ts 使用声明式基础设施——您在代码中定义资源，Encore 负责配置：

本地环境 (encore run) - Encore 在 Docker 中运行基础设施（Postgres、Redis 等）
生产环境 - 通过 Encore Cloud 部署到您的 AWS/GCP，或使用生成的基础设施配置自行托管

关键规则

所有基础设施必须在包级别（文件顶部）声明，不能在函数内部。

数据库 (PostgreSQL)

import { SQLDatabase } from "encore.dev/storage/sqldb";

// 正确：包级别
const db = new SQLDatabase("mydb", {
  migrations: "./migrations",
});

// 错误：在函数内部
async function setup() {
  const db = new SQLDatabase("mydb", { migrations: "./migrations" });
}

迁移

在 migrations/ 目录中创建迁移文件：

service/
├── encore.service.ts
├── api.ts
├── db.ts
└── migrations/
    ├── 001_create_users.up.sql
    └── 002_add_email_index.up.sql

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

843,800 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

278,000 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

224,400 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

152,900 周安装

迁移文件命名格式：{数字}_{描述}.up.sql

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

interface OrderCreatedEvent {
  orderId: string;
  userId: string;
  total: number;
}

// 包级别声明
export const orderCreated = new Topic<OrderCreatedEvent>("order-created", {
  deliveryGuarantee: "at-least-once",
});

await orderCreated.publish({
  orderId: "123",
  userId: "user-456",
  total: 99.99,
});

import { Subscription } from "encore.dev/pubsub";

const _ = new Subscription(orderCreated, "send-confirmation-email", {
  handler: async (event) => {
    await sendEmail(event.userId, event.orderId);
  },
});

使用 Attribute<T> 标记应作为消息属性的字段（用于过滤/排序）：

import { Topic, Attribute } from "encore.dev/pubsub";

interface CartEvent {
  cartId: Attribute<string>;  // 用于排序
  userId: string;
  action: "add" | "remove";
  productId: string;
}

// 有序主题 - 相同 cartId 的事件按顺序传递
export const cartEvents = new Topic<CartEvent>("cart-events", {
  deliveryGuarantee: "at-least-once",
  orderingAttribute: "cartId",
});

将主题访问权限传递给其他代码，同时保持静态分析：

import { Publisher } from "encore.dev/pubsub";

// 创建具有发布权限的引用
const publisherRef = orderCreated.ref<Publisher>();

// 使用引用
async function notifyOrder(ref: typeof publisherRef, orderId: string) {
  await ref.publish({ orderId, userId: "123", total: 99.99 });
}

import { CronJob } from "encore.dev/cron";
import { api } from "encore.dev/api";

// 要调用的端点
export const cleanupExpiredSessions = api(
  { expose: false },
  async (): Promise<void> => {
    // 清理逻辑
  }
);

// 包级别定时任务声明
const _ = new CronJob("cleanup-sessions", {
  title: "清理过期会话",
  schedule: "0 * * * *",  // 每小时
  endpoint: cleanupExpiredSessions,
});

格式	示例	描述
`every`	`"1h"`, `"30m"`	简单间隔（必须能整除 24 小时）
`schedule`	`"0 9 * * 1"`	Cron 表达式（每周一上午 9 点）

import { Bucket } from "encore.dev/storage/objects";

// 包级别
export const uploads = new Bucket("user-uploads", {
  versioned: false,  // 设置为 true 可保留对象的多个版本
});

// 公共存储桶（文件可通过公共 URL 访问）
export const publicAssets = new Bucket("public-assets", {
  public: true,
  versioned: false,
});

// 上传
const attrs = await uploads.upload("path/to/file.jpg", buffer, {
  contentType: "image/jpeg",
});

// 下载
const data = await uploads.download("path/to/file.jpg");

// 检查是否存在
const exists = await uploads.exists("path/to/file.jpg");

// 获取属性（大小、内容类型、ETag）
const attrs = await uploads.attrs("path/to/file.jpg");

// 删除
await uploads.remove("path/to/file.jpg");

// 列出对象
for await (const entry of uploads.list({})) {
  console.log(entry.key, entry.size);
}

// 公共 URL（仅适用于公共存储桶）
const url = publicAssets.publicUrl("image.jpg");

生成临时 URL 用于上传/下载，而无需暴露您的存储桶：

// 签名上传 URL（2 小时后过期）
const uploadUrl = await uploads.signedUploadUrl("user-uploads/avatar.jpg", { ttl: 7200 });

// 签名下载 URL
const downloadUrl = await uploads.signedDownloadUrl("documents/report.pdf", { ttl: 7200 });

将具有特定权限的存储桶访问权限传递给其他代码：

import { Uploader, Downloader } from "encore.dev/storage/objects";

// 创建仅具有上传权限的引用
const uploaderRef = uploads.ref<Uploader>();

// 创建仅具有下载权限的引用
const downloaderRef = uploads.ref<Downloader>();

// 权限类型：Downloader、Uploader、Lister、Attrser、Remover、
// SignedDownloader、SignedUploader、ReadWriter

import { CacheCluster } from "encore.dev/storage/cache";

// 包级别
const cluster = new CacheCluster("my-cache", {
  evictionPolicy: "allkeys-lru",
});

引用在另一个服务中定义的集群：

const cluster = CacheCluster.named("my-cache");

驱逐策略："allkeys-lru"（默认）、"noeviction"、"allkeys-lfu"、"allkeys-random"、"volatile-lru"、"volatile-lfu"、"volatile-ttl"、"volatile-random"。

每个键空间都有一个键类型（用于生成 Redis 键）和一个值类型。

import {
  StringKeyspace,
  IntKeyspace,
  FloatKeyspace,
  StructKeyspace,
  StringListKeyspace,
  NumberListKeyspace,
  StringSetKeyspace,
  NumberSetKeyspace,
  expireIn,
} from "encore.dev/storage/cache";

// 字符串值
const tokens = new StringKeyspace<{ tokenId: string }>(cluster, {
  keyPattern: "token/:tokenId",
  defaultExpiry: expireIn(3600 * 1000), // 1 小时，以毫秒为单位
});

await tokens.set({ tokenId: "abc" }, "value");
const val = await tokens.get({ tokenId: "abc" }); // 未命中时返回 undefined
await tokens.delete({ tokenId: "abc" });

// 整数值（支持递增/递减）
const counters = new IntKeyspace<{ userId: string }>(cluster, {
  keyPattern: "requests/:userId",
  defaultExpiry: expireIn(10 * 1000),
});

const count = await counters.increment({ userId: "user123" }, 1);
await counters.decrement({ userId: "user123" }, 1);

// 浮点值
const scores = new FloatKeyspace<{ oddsId: string }>(cluster, {
  keyPattern: "odds/:oddsId",
});

// 结构化数据（以 JSON 格式存储）
interface UserProfile {
  name: string;
  email: string;
}

const profiles = new StructKeyspace<{ userId: string }, UserProfile>(cluster, {
  keyPattern: "profile/:userId",
  defaultExpiry: expireIn(3600 * 1000),
});

await profiles.set({ userId: "123" }, { name: "Alice", email: "alice@example.com" });

// 列表
const recentItems = new StringListKeyspace<{ userId: string }>(cluster, {
  keyPattern: "recent/:userId",
});

await recentItems.pushRight({ userId: "user123" }, "item1", "item2");
const items = await recentItems.getRange({ userId: "user123" }, 0, -1);

// 集合
const tags = new StringSetKeyspace<{ articleId: string }>(cluster, {
  keyPattern: "tags/:articleId",
});

await tags.add({ articleId: "post1" }, "typescript", "encore", "backend");
const hasTag = await tags.contains({ articleId: "post1" }, "typescript");

interface ResourceKey {
  userId: string;
  resourcePath: string;
}

const resourceRequests = new IntKeyspace<ResourceKey>(cluster, {
  keyPattern: "requests/:userId/:resourcePath",
  defaultExpiry: expireIn(10 * 1000),
});

import {
  expireIn,          // 毫秒
  expireInSeconds,
  expireInMinutes,
  expireInHours,
  expireDailyAt,     // 每天特定的 UTC 时间
  neverExpire,
  keepTTL,           // 更新时保留现有的 TTL
} from "encore.dev/storage/cache";

// 覆盖默认过期时间
await keyspace.set(key, value, { expiry: expireInMinutes(30) });

// 保留现有的 TTL
await keyspace.set(key, value, { expiry: keepTTL });

// 仅当键不存在时设置（否则抛出 CacheKeyExists）
await keyspace.setIfNotExists(key, value);

// 仅当键已存在时设置（否则抛出 CacheMiss）
await keyspace.replace(key, value);

import { CacheMiss, CacheKeyExists } from "encore.dev/storage/cache";

// get() 在未命中时返回 undefined（不抛出异常）
const value = await keyspace.get(key);

// replace() 在键不存在时抛出 CacheMiss
// setIfNotExists() 在键已存在时抛出 CacheKeyExists

import { secret } from "encore.dev/config";

// 包级别
const stripeKey = secret("StripeSecretKey");

// 使用方式（作为函数调用）
const key = stripeKey();

通过 CLI 设置密钥：

encore secret set --type prod StripeSecretKey

基础设施声明必须在包级别
为资源使用描述性名称
保持迁移文件顺序编号
订阅处理程序必须是幂等的（至少一次传递）
通过将密钥作为函数调用来访问
定时任务端点应设置为 expose: false（仅内部使用）

🇺🇸English

Encore Infrastructure Declaration

Instructions

Encore.ts uses declarative infrastructure - you define resources in code and Encore handles provisioning:

Locally (encore run) - Encore runs infrastructure in Docker (Postgres, Redis, etc.)
Production - Deploy via Encore Cloud to your AWS/GCP, or self-host using generated infrastructure config

Critical Rule

All infrastructure must be declared at package level (top of file), not inside functions.

Databases (PostgreSQL)

import { SQLDatabase } from "encore.dev/storage/sqldb";

// CORRECT: Package level
const db = new SQLDatabase("mydb", {
  migrations: "./migrations",
});

// WRONG: Inside function
async function setup() {
  const db = new SQLDatabase("mydb", { migrations: "./migrations" });
}

Migrations

Create migrations in the migrations/ directory:

service/
├── encore.service.ts
├── api.ts
├── db.ts
└── migrations/
    ├── 001_create_users.up.sql
    └── 002_add_email_index.up.sql

Migration naming: {number}_{description}.up.sql

Pub/Sub

Topics

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

interface OrderCreatedEvent {
  orderId: string;
  userId: string;
  total: number;
}

// Package level declaration
export const orderCreated = new Topic<OrderCreatedEvent>("order-created", {
  deliveryGuarantee: "at-least-once",
});

Publishing

await orderCreated.publish({
  orderId: "123",
  userId: "user-456",
  total: 99.99,
});

Subscriptions

import { Subscription } from "encore.dev/pubsub";

const _ = new Subscription(orderCreated, "send-confirmation-email", {
  handler: async (event) => {
    await sendEmail(event.userId, event.orderId);
  },
});

Message Attributes

Use Attribute<T> for fields that should be message attributes (for filtering/ordering):

import { Topic, Attribute } from "encore.dev/pubsub";

interface CartEvent {
  cartId: Attribute<string>;  // Used for ordering
  userId: string;
  action: "add" | "remove";
  productId: string;
}

// Ordered topic - events with same cartId delivered in order
export const cartEvents = new Topic<CartEvent>("cart-events", {
  deliveryGuarantee: "at-least-once",
  orderingAttribute: "cartId",
});

Topic References

Pass topic access to other code while maintaining static analysis:

import { Publisher } from "encore.dev/pubsub";

// Create a reference with publish permission
const publisherRef = orderCreated.ref<Publisher>();

// Use the reference
async function notifyOrder(ref: typeof publisherRef, orderId: string) {
  await ref.publish({ orderId, userId: "123", total: 99.99 });
}

Cron Jobs

import { CronJob } from "encore.dev/cron";
import { api } from "encore.dev/api";

// The endpoint to call
export const cleanupExpiredSessions = api(
  { expose: false },
  async (): Promise<void> => {
    // Cleanup logic
  }
);

// Package level cron declaration
const _ = new CronJob("cleanup-sessions", {
  title: "Clean up expired sessions",
  schedule: "0 * * * *",  // Every hour
  endpoint: cleanupExpiredSessions,
});

Schedule Formats

Format	Example	Description
`every`	`"1h"`, `"30m"`	Simple interval (must divide 24h evenly)
`schedule`	`"0 9 * * 1"`	Cron expression (9am every Monday)

Object Storage

import { Bucket } from "encore.dev/storage/objects";

// Package level
export const uploads = new Bucket("user-uploads", {
  versioned: false,  // Set to true to keep multiple versions of objects
});

// Public bucket (files accessible via public URL)
export const publicAssets = new Bucket("public-assets", {
  public: true,
  versioned: false,
});

Operations

// Upload
const attrs = await uploads.upload("path/to/file.jpg", buffer, {
  contentType: "image/jpeg",
});

// Download
const data = await uploads.download("path/to/file.jpg");

// Check existence
const exists = await uploads.exists("path/to/file.jpg");

// Get attributes (size, content type, ETag)
const attrs = await uploads.attrs("path/to/file.jpg");

// Delete
await uploads.remove("path/to/file.jpg");

// List objects
for await (const entry of uploads.list({})) {
  console.log(entry.key, entry.size);
}

// Public URL (only for public buckets)
const url = publicAssets.publicUrl("image.jpg");

Signed URLs

Generate temporary URLs for upload/download without exposing your bucket:

// Signed upload URL (expires in 2 hours)
const uploadUrl = await uploads.signedUploadUrl("user-uploads/avatar.jpg", { ttl: 7200 });

// Signed download URL
const downloadUrl = await uploads.signedDownloadUrl("documents/report.pdf", { ttl: 7200 });

Bucket References

Pass bucket access with specific permissions to other code:

import { Uploader, Downloader } from "encore.dev/storage/objects";

// Create a reference with upload permission only
const uploaderRef = uploads.ref<Uploader>();

// Create a reference with download permission only
const downloaderRef = uploads.ref<Downloader>();

// Permission types: Downloader, Uploader, Lister, Attrser, Remover,
// SignedDownloader, SignedUploader, ReadWriter

Caching (Redis)

Cache Clusters

import { CacheCluster } from "encore.dev/storage/cache";

// Package level
const cluster = new CacheCluster("my-cache", {
  evictionPolicy: "allkeys-lru",
});

Reference a cluster defined in another service:

const cluster = CacheCluster.named("my-cache");

Eviction policies: "allkeys-lru" (default), "noeviction", "allkeys-lfu", "allkeys-random", "volatile-lru", "volatile-lfu", "volatile-ttl", "volatile-random".

Keyspace Types

Each keyspace has a key type (used to generate the Redis key) and a value type.

import {
  StringKeyspace,
  IntKeyspace,
  FloatKeyspace,
  StructKeyspace,
  StringListKeyspace,
  NumberListKeyspace,
  StringSetKeyspace,
  NumberSetKeyspace,
  expireIn,
} from "encore.dev/storage/cache";

// String values
const tokens = new StringKeyspace<{ tokenId: string }>(cluster, {
  keyPattern: "token/:tokenId",
  defaultExpiry: expireIn(3600 * 1000), // 1 hour in ms
});

await tokens.set({ tokenId: "abc" }, "value");
const val = await tokens.get({ tokenId: "abc" }); // undefined on miss
await tokens.delete({ tokenId: "abc" });

// Integer values (supports increment/decrement)
const counters = new IntKeyspace<{ userId: string }>(cluster, {
  keyPattern: "requests/:userId",
  defaultExpiry: expireIn(10 * 1000),
});

const count = await counters.increment({ userId: "user123" }, 1);
await counters.decrement({ userId: "user123" }, 1);

// Float values
const scores = new FloatKeyspace<{ oddsId: string }>(cluster, {
  keyPattern: "odds/:oddsId",
});

// Structured data (stored as JSON)
interface UserProfile {
  name: string;
  email: string;
}

const profiles = new StructKeyspace<{ userId: string }, UserProfile>(cluster, {
  keyPattern: "profile/:userId",
  defaultExpiry: expireIn(3600 * 1000),
});

await profiles.set({ userId: "123" }, { name: "Alice", email: "alice@example.com" });

// Lists
const recentItems = new StringListKeyspace<{ userId: string }>(cluster, {
  keyPattern: "recent/:userId",
});

await recentItems.pushRight({ userId: "user123" }, "item1", "item2");
const items = await recentItems.getRange({ userId: "user123" }, 0, -1);

// Sets
const tags = new StringSetKeyspace<{ articleId: string }>(cluster, {
  keyPattern: "tags/:articleId",
});

await tags.add({ articleId: "post1" }, "typescript", "encore", "backend");
const hasTag = await tags.contains({ articleId: "post1" }, "typescript");

Key Patterns with Multiple Fields

interface ResourceKey {
  userId: string;
  resourcePath: string;
}

const resourceRequests = new IntKeyspace<ResourceKey>(cluster, {
  keyPattern: "requests/:userId/:resourcePath",
  defaultExpiry: expireIn(10 * 1000),
});

Expiry Options

import {
  expireIn,          // milliseconds
  expireInSeconds,
  expireInMinutes,
  expireInHours,
  expireDailyAt,     // specific UTC time each day
  neverExpire,
  keepTTL,           // keep existing TTL when updating
} from "encore.dev/storage/cache";

Write Options

// Override default expiry
await keyspace.set(key, value, { expiry: expireInMinutes(30) });

// Keep existing TTL
await keyspace.set(key, value, { expiry: keepTTL });

// Only set if key doesn't exist (throws CacheKeyExists otherwise)
await keyspace.setIfNotExists(key, value);

// Only set if key already exists (throws CacheMiss otherwise)
await keyspace.replace(key, value);

Error Handling

import { CacheMiss, CacheKeyExists } from "encore.dev/storage/cache";

// get() returns undefined on miss (does not throw)
const value = await keyspace.get(key);

// replace() throws CacheMiss if key doesn't exist
// setIfNotExists() throws CacheKeyExists if key already exists

Secrets

import { secret } from "encore.dev/config";

// Package level
const stripeKey = secret("StripeSecretKey");

// Usage (call as function)
const key = stripeKey();

Set secrets via CLI:

encore secret set --type prod StripeSecretKey

Guidelines

Infrastructure declarations MUST be at package level
Use descriptive names for resources
Keep migrations sequential and numbered
Subscription handlers must be idempotent (at-least-once delivery)
Secrets are accessed by calling the secret as a function
Cron endpoints should be expose: false (internal only)

Weekly Installs

167

Repository

encoredev/skills

GitHub Stars

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex130

opencode128

gemini-cli124

claude-code112

github-copilot108

cursor102

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

125,100 周安装

Encore.ts 声明式基础设施：PostgreSQL、Redis、Pub/Sub、定时任务、对象存储

🇨🇳中文介绍

Encore 基础设施声明

说明

关键规则

数据库 (PostgreSQL)

迁移

相关 Skills

发布/订阅

主题

发布

订阅

消息属性

主题引用

定时任务

计划格式

对象存储

操作

签名 URL

存储桶引用

缓存 (Redis)

缓存集群

键空间类型

多字段键模式

过期选项

写入选项

错误处理

密钥

指南