@atomservice/postgres 0.1.5

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@atomservice/postgres",
+  "version": "0.1.5",
+  "description": "PostgreSQL 原子服务",
+  "type": "module",
+  "author": "openorson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openorson/atomservice.git",
+    "directory": "services/postgres"
+  },
+  "bugs": "https://github.com/openorson/atomservice/issues",
+  "homepage": "https://github.com/openorson/atomservice/tree/main/services/postgres#readme",
+  "keywords": [
+    "atomservice",
+    "postgres",
+    "postgresql",
+    "self-hosted",
+    "podman"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@atomservice/core": "0.1.5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export type { PostgresInstance } from "./postgres.instance.ts"
+export type { DatabaseConfig, PostgresOptions } from "./postgres.options.ts"
+export { postgres } from "./postgres.service.ts"

package/src/postgres.compose.ts

@@ -0,0 +1,45 @@
+import { tmpl } from "@atomservice/core"
+import { POSTGRES_IMAGE } from "./postgres.consts.ts"
+import type { PostgresOptions } from "./postgres.options.ts"
+
+export function postgresCompose(
+  containerName: string,
+  version: string,
+  dataDir: string,
+  opts: Pick<PostgresOptions, "password" | "hostPort" | "maxConnections" | "sharedBuffers">,
+): string {
+  const { password, hostPort, maxConnections, sharedBuffers } = opts
+
+  const portsBlock = hostPort ? `\n    ports:\n      - "${hostPort}:5432"` : ""
+
+  const cmdArgs: string[] = []
+  if (maxConnections) cmdArgs.push(`-c max_connections=${maxConnections}`)
+  if (sharedBuffers) cmdArgs.push(`-c shared_buffers=${sharedBuffers}`)
+  const cmdBlock = cmdArgs.length > 0 ? `\n    command: postgres ${cmdArgs.join(" ")}` : ""
+
+  const envPassword = password ? `\n      POSTGRES_PASSWORD: ${password}` : `\n      POSTGRES_HOST_AUTH_METHOD: trust`
+
+  return tmpl`\
+services:
+  ${containerName}:
+    image: ${POSTGRES_IMAGE}:${version}-alpine
+    container_name: ${containerName}${cmdBlock}
+    environment:${envPassword}
+      PGDATA: /var/lib/postgresql/pgdata
+    volumes:
+      - ${dataDir}:/var/lib/postgresql${portsBlock}
+    networks:
+      - atomservice
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+networks:
+  atomservice:
+    name: atomservice
+    external: true
+`
+}

package/src/postgres.consts.ts

@@ -0,0 +1 @@
+export const POSTGRES_IMAGE = "postgres"

package/src/postgres.instance.ts

@@ -0,0 +1,39 @@
+export interface PostgresInstance {
+  /**
+   * 容器 `hostname`
+   */
+  readonly host: string
+  /**
+   * 容器内端口
+   */
+  readonly port: 5432
+  /**
+   * 超级用户名
+   */
+  readonly user: "postgres"
+  /**
+   * 超级用户密码
+   *
+   * - 未设置密码时为 `undefined`
+   */
+  readonly password: string | undefined
+  /**
+   * 默认数据库名（主库，`options.database` 的第一个）
+   */
+  readonly database: string
+  /**
+   * 获取指定数据库的连接字符串
+   *
+   * @param dbName 数据库名，默认为 `options.database ?? "postgres"`
+   *
+   * @example `"postgres://postgres:secret@postgres:5432/myapp"`
+   */
+  connectionString(dbName?: string): string
+  /**
+   * 创建一个新数据库（幂等）
+   *
+   * @param name 数据库名
+   * @returns 该数据库的连接字符串
+   */
+  createDatabase(name: string): Promise<string>
+}

package/src/postgres.options.ts

@@ -0,0 +1,66 @@
+export interface DatabaseConfig {
+  /**
+   * 数据库名
+   */
+  name: string
+  /**
+   * 在此数据库中初始化的 PG 扩展列表（幂等，已存在则跳过）
+   *
+   * - 常用值：`"uuid-ossp"` / `"pgvector"` / `"pg_trgm"` / `"hstore"`
+   */
+  extensions?: string[]
+}
+
+export interface PostgresOptions {
+  /**
+   * 实例标识
+   *
+   * - 用于区分不同实例
+   *
+   * @default "default"
+   */
+  id?: string
+  /**
+   * 镜像版本
+   *
+   * @default "18"
+   */
+  version?: string
+  /**
+   * 超级用户密码
+   *
+   * - 不填则不设置密码（仅限容器内网访问时可不设）
+   */
+  password?: string
+  /**
+   * 映射到宿主机的端口
+   *
+   * - 不填则不对外暴露，仅容器网络内访问
+   */
+  hostPort?: number
+  /**
+   * 初始化时自动创建的数据库，第一个为主库。
+   *
+   * @example "myapp" // 单数据库
+   * @example { name: "myapp", extensions: ["uuid-ossp"] } // 单数据库并安装扩展
+   * @example [{ name: "myapp" }, { name: "analytics", extensions: ["pg_trgm"] }] // 多数据库
+   */
+  database?: string | DatabaseConfig | DatabaseConfig[]
+  /**
+   * 最大连接数
+   *
+   * - `Postgres` 默认 `100`，高并发场景建议调高
+   *
+   * @default 100
+   */
+  maxConnections?: number
+  /**
+   * 共享内存大小
+   *
+   * - 对查询性能影响最大，建议配为机器 `RAM` 的 `25%`
+   * - 支持 `Postgres` 原生格式：`"128mb"` / `"512mb"` / `"1gb"` 等
+   *
+   * @default "128mb"
+   */
+  sharedBuffers?: string
+}

package/src/postgres.service.ts

@@ -0,0 +1,164 @@
+import path from "node:path"
+import type { CallableService } from "@atomservice/core"
+import {
+  defineService,
+  onDown,
+  onHealth,
+  onUp,
+  UserError,
+  useConfig,
+  useLogger,
+  useShell,
+  useState,
+} from "@atomservice/core"
+import { postgresCompose } from "./postgres.compose.ts"
+import type { PostgresInstance } from "./postgres.instance.ts"
+import type { PostgresOptions } from "./postgres.options.ts"
+import type { PostgresState } from "./postgres.types.ts"
+import { normalizeDatabases } from "./postgres.utils.ts"
+
+export function postgres(opts: PostgresOptions = {}): CallableService<PostgresInstance> {
+  const serviceId = opts.id && opts.id !== "default" ? opts.id : "default"
+  const containerName = serviceId !== "default" ? `postgres-${serviceId}` : "postgres"
+  const version = opts.version ?? "18"
+
+  return defineService({
+    name: "postgres",
+    id: opts.id,
+    setup: () => {
+      const logger = useLogger()
+      const $ = useShell()
+      const config = useConfig()
+      const dir = path.join(config.root, containerName)
+      const composePath = path.join(dir, "compose.yml")
+
+      const { save, watch, checkChanges } = useState<PostgresState>()
+
+      watch("version", {
+        risk: "low",
+        changed: (previousValue, currentValue) =>
+          `Postgres 版本已变更 ${previousValue} → ${currentValue}，将在下次启动时拉取新镜像`,
+      })
+
+      watch("password", {
+        risk: "high",
+        added: (currentValue) =>
+          `已新增密码认证，已有数据目录不会自动更新，需手动执行 ALTER USER postgres WITH PASSWORD '${currentValue}'`,
+        removed: () => `已移除密码认证，已有数据目录没有自动切换为 trust 模式，需删除数据目录重新初始化`,
+        changed: (_, currentValue) => `密码已变更，需手动执行 ALTER USER postgres WITH PASSWORD '${currentValue}'`,
+      })
+
+      watch("primaryDatabase", {
+        risk: "high",
+        changed: (previousValue, currentValue) =>
+          `主数据库名已变更 ${previousValue} → ${currentValue}，旧库数据不会自动迁移`,
+      })
+
+      onUp(async () => {
+        const databases = normalizeDatabases(opts.database)
+        const primaryDb = databases[0]
+        const currentState: PostgresState = {
+          version,
+          password: opts.password,
+          primaryDatabase: primaryDb?.name,
+        }
+        await checkChanges(currentState)
+
+        await $`mkdir -p ${dir}/data`
+        await Bun.write(composePath, postgresCompose(containerName, version, `${dir}/data`, opts))
+
+        logger.info(`正在启动 ${containerName}…`)
+        await $`podman compose -f ${composePath} up -d`
+
+        logger.info(`等待 ${containerName} 就绪`)
+        // 初始化阶段 Postgres 会先启动临时服务再重启正式服务，
+        // 因此用真实查询确认就绪，避免命中临时服务导致后续连接被中断
+        let ready = false
+        for (let i = 0; i < 60; i++) {
+          const probe = await $`podman exec ${containerName} psql -U postgres -tAc ${"SELECT 1"}`.quiet().nothrow()
+          if (probe.exitCode === 0 && probe.stdout.toString().trim() === "1") {
+            ready = true
+            break
+          }
+          await Bun.sleep(1000)
+        }
+        if (!ready) {
+          throw new UserError(`${containerName} 启动超时，未能在 60 秒内就绪`)
+        }
+
+        for (const db of databases) {
+          const exists =
+            await $`podman exec ${containerName} psql -U postgres -tAc ${`SELECT 1 FROM pg_database WHERE datname='${db.name}'`}`.text()
+          if (exists.trim() !== "1") {
+            await $`podman exec ${containerName} psql -U postgres -c ${`CREATE DATABASE "${db.name}"`}`
+            logger.success(`数据库 "${db.name}" 已创建`)
+          }
+          for (const ext of db.extensions ?? []) {
+            await $`podman exec ${containerName} psql -U postgres -d ${db.name} -c ${`CREATE EXTENSION IF NOT EXISTS "${ext}"`}`
+            logger.success(`扩展 "${ext}" 已就绪`)
+          }
+        }
+
+        logger.success(`${containerName} 已启动`)
+        await save(currentState)
+      })
+
+      onDown(async () => {
+        logger.info(`正在停止 ${containerName}`)
+        await $`podman compose -f ${composePath} down`
+        logger.success(`${containerName} 已停止`)
+      })
+
+      onHealth(async () => {
+        try {
+          const result = await $`podman inspect --format {{.State.Health.Status}} ${containerName}`.text()
+          const status = result.trim()
+          if (status === "healthy") return { status: "healthy" }
+          return { status: "unhealthy", message: `容器健康状态：${status}` }
+        } catch {
+          return {
+            status: "unhealthy",
+            message: `容器 ${containerName} 不存在`,
+          }
+        }
+      })
+
+      const databases = normalizeDatabases(opts.database)
+      const primaryDb = databases[0]
+      const auth = opts.password ? `postgres:${opts.password}` : "postgres"
+
+      return {
+        get host() {
+          return containerName
+        },
+        get port(): 5432 {
+          return 5432
+        },
+        get user(): "postgres" {
+          return "postgres"
+        },
+        get password() {
+          return opts.password
+        },
+        get database(): string {
+          if (!primaryDb) throw new Error(`[postgres] 未配置 database，请在选项中指定`)
+          return primaryDb.name
+        },
+        connectionString(dbName?: string): string {
+          const name = dbName ?? (primaryDb ? primaryDb.name : undefined)
+          if (!name) throw new Error(`[postgres] 未配置 database，请传入数据库名或在选项中指定`)
+          return `postgres://${auth}@${containerName}:5432/${name}`
+        },
+        async createDatabase(name: string): Promise<string> {
+          const exists =
+            await $`podman exec ${containerName} psql -U postgres -tAc ${`SELECT 1 FROM pg_database WHERE datname='${name}'`}`.text()
+          if (exists.trim() !== "1") {
+            await $`podman exec ${containerName} psql -U postgres -c ${`CREATE DATABASE "${name}"`}`
+            logger.success(`数据库 "${name}" 已创建`)
+          }
+          return `postgres://${auth}@${containerName}:5432/${name}`
+        },
+      }
+    },
+  })
+}

package/src/postgres.types.ts

@@ -0,0 +1,5 @@
+export type PostgresState = {
+  version: string
+  password: string | undefined
+  primaryDatabase: string | undefined
+}

package/src/postgres.utils.ts

@@ -0,0 +1,8 @@
+import type { DatabaseConfig, PostgresOptions } from "./postgres.options.ts"
+
+export function normalizeDatabases(database: PostgresOptions["database"]): DatabaseConfig[] {
+  if (!database) return []
+  if (typeof database === "string") return [{ name: database }]
+  if (Array.isArray(database)) return database
+  return [database]
+}