@tangen/db 0.0.0-stage → 0.1.54

package/drizzle/meta/_journal.json

@@ -0,0 +1,426 @@
+{
+  "version": "6",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1782310803741,
+      "tag": "0000_flimsy_shotgun",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1782400000000,
+      "tag": "0001_app_data",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1782405813836,
+      "tag": "0002_add_indexes",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1782410000000,
+      "tag": "0003_extension_data_rename",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "6",
+      "when": 1782420000000,
+      "tag": "0004_extension_data_published_globals",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "6",
+      "when": 1782500000000,
+      "tag": "0005_auth",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "6",
+      "when": 1782600000000,
+      "tag": "0006_auth_identities",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1782700000000,
+      "tag": "0007_ai",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "6",
+      "when": 1782800000000,
+      "tag": "0008_ai_chat_threads",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1782900000000,
+      "tag": "0009_forms_source_slug",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "6",
+      "when": 1783000000000,
+      "tag": "0010_rbac_roles_status",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "6",
+      "when": 1783900000000,
+      "tag": "0011_jobs_v2",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "6",
+      "when": 1784000000000,
+      "tag": "0012_search_platform",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "6",
+      "when": 1784100000000,
+      "tag": "0013_search_synonym_label",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "6",
+      "when": 1784200000000,
+      "tag": "0014_object_types_disabled",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "6",
+      "when": 1784300000000,
+      "tag": "0015_playground_collections",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "6",
+      "when": 1784390000000,
+      "tag": "0016_catchup_activity_promotion",
+      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "6",
+      "when": 1784480000000,
+      "tag": "0017_fields_disabled",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "6",
+      "when": 1784490000000,
+      "tag": "0018_object_types_plural",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "6",
+      "when": 1784500000000,
+      "tag": "0019_member_profile",
+      "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "6",
+      "when": 1784510000000,
+      "tag": "0020_paused_jobs",
+      "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "6",
+      "when": 1785000000000,
+      "tag": "0021_form_submission_notes",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "6",
+      "when": 1785100000000,
+      "tag": "0022_paused_jobs_env_reason",
+      "breakpoints": true
+    },
+    {
+      "idx": 23,
+      "version": "6",
+      "when": 1785200000000,
+      "tag": "0023_scale_indexes",
+      "breakpoints": true
+    },
+    {
+      "idx": 24,
+      "version": "6",
+      "when": 1785300000000,
+      "tag": "0024_migration_runs",
+      "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "6",
+      "when": 1785400000000,
+      "tag": "0025_porter_transfer",
+      "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "6",
+      "when": 1785500000000,
+      "tag": "0026_cron_timezone",
+      "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "6",
+      "when": 1785600000000,
+      "tag": "0027_rate_limit_counters",
+      "breakpoints": true
+    },
+    {
+      "idx": 28,
+      "version": "6",
+      "when": 1785700000000,
+      "tag": "0028_realtime_events",
+      "breakpoints": true
+    },
+    {
+      "idx": 29,
+      "version": "6",
+      "when": 1785900000000,
+      "tag": "0030_delivery_artifacts",
+      "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "6",
+      "when": 1786000000000,
+      "tag": "0031_realtime_presence",
+      "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "6",
+      "when": 1786100000000,
+      "tag": "0032_schema_pushes",
+      "breakpoints": true
+    },
+    {
+      "idx": 32,
+      "version": "6",
+      "when": 1786200000000,
+      "tag": "0033_studio_design_capability",
+      "breakpoints": true
+    },
+    {
+      "idx": 33,
+      "version": "6",
+      "when": 1786300000000,
+      "tag": "0034_object_types_provided_by",
+      "breakpoints": true
+    },
+    {
+      "idx": 34,
+      "version": "6",
+      "when": 1786400000000,
+      "tag": "0035_custom_table_owners",
+      "breakpoints": true
+    },
+    {
+      "idx": 35,
+      "version": "6",
+      "when": 1786500000000,
+      "tag": "0036_revision_version_unique",
+      "breakpoints": true
+    },
+    {
+      "idx": 36,
+      "version": "6",
+      "when": 1786600000000,
+      "tag": "0037_job_queue_dedupe",
+      "breakpoints": true
+    },
+    {
+      "idx": 37,
+      "version": "6",
+      "when": 1786700000000,
+      "tag": "0038_search_documents",
+      "breakpoints": true
+    },
+    {
+      "idx": 38,
+      "version": "6",
+      "when": 1786800000000,
+      "tag": "0039_job_prune_indexes",
+      "breakpoints": true
+    },
+    {
+      "idx": 39,
+      "version": "6",
+      "when": 1786900000000,
+      "tag": "0040_extension_data_object_idx",
+      "breakpoints": true
+    },
+    {
+      "idx": 40,
+      "version": "6",
+      "when": 1787000000000,
+      "tag": "0041_knowledge",
+      "breakpoints": true
+    },
+    {
+      "idx": 41,
+      "version": "6",
+      "when": 1787100000000,
+      "tag": "0042_schema_pushes_checksum",
+      "breakpoints": true
+    },
+    {
+      "idx": 42,
+      "version": "6",
+      "when": 1787200000000,
+      "tag": "0043_guard_adoption",
+      "breakpoints": true
+    },
+    {
+      "idx": 43,
+      "version": "6",
+      "when": 1787300000000,
+      "tag": "0044_retention_indexes",
+      "breakpoints": true
+    },
+    {
+      "idx": 44,
+      "version": "6",
+      "when": 1787400000000,
+      "tag": "0045_extension_install_per_env",
+      "breakpoints": true
+    },
+    {
+      "idx": 45,
+      "version": "6",
+      "when": 1787400100000,
+      "tag": "0046_extension_migrations",
+      "breakpoints": true
+    },
+    {
+      "idx": 46,
+      "version": "6",
+      "when": 1787400200000,
+      "tag": "0047_environment_role",
+      "breakpoints": true
+    },
+    {
+      "idx": 47,
+      "version": "6",
+      "when": 1787400300000,
+      "tag": "0048_environment_role_adoption",
+      "breakpoints": true
+    },
+    {
+      "idx": 48,
+      "version": "6",
+      "when": 1787400400000,
+      "tag": "0049_release_lifecycle",
+      "breakpoints": true
+    },
+    {
+      "idx": 49,
+      "version": "6",
+      "when": 1787400500000,
+      "tag": "0050_member_env_membership",
+      "breakpoints": true
+    },
+    {
+      "idx": 50,
+      "version": "6",
+      "when": 1787400600000,
+      "tag": "0051_remove_environments",
+      "breakpoints": true
+    },
+    {
+      "idx": 51,
+      "version": "6",
+      "when": 1787400700000,
+      "tag": "0052_release_actor_columns",
+      "breakpoints": true
+    },
+    {
+      "idx": 52,
+      "version": "6",
+      "when": 1787400800000,
+      "tag": "0053_kernel_event_record",
+      "breakpoints": true
+    },
+    {
+      "idx": 53,
+      "version": "6",
+      "when": 1787400900000,
+      "tag": "0054_kernel_run_identity",
+      "breakpoints": true
+    },
+    {
+      "idx": 54,
+      "version": "6",
+      "when": 1787401000000,
+      "tag": "0055_kernel_identities",
+      "breakpoints": true
+    },
+    {
+      "idx": 55,
+      "version": "6",
+      "when": 1787500000000,
+      "tag": "0056_forms_leave_core",
+      "breakpoints": true
+    },
+    {
+      "idx": 56,
+      "version": "6",
+      "when": 1787500100000,
+      "tag": "0057_auth_leave_core",
+      "breakpoints": true
+    },
+    {
+      "idx": 57,
+      "version": "6",
+      "when": 1787500200000,
+      "tag": "0058_member_grants",
+      "breakpoints": true
+    },
+    {
+      "idx": 58,
+      "version": "6",
+      "when": 1787500260000,
+      "tag": "0059_extension_granted_grants",
+      "breakpoints": true
+    },
+    {
+      "idx": 59,
+      "version": "6",
+      "when": 1787500320000,
+      "tag": "0060_connections",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@tangen/db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.54",
+  "description": "Database client and system schema (Drizzle + postgres.js) for the Tangen headless CMS",
+  "homepage": "https://github.com/raghunathj/tangen#readme",
+  "bugs": {
+    "url": "https://github.com/raghunathj/tangen/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raghunathj/tangen.git",
+    "directory": "packages/db"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "default": "./src/index.ts"
+    },
+    "./migrate": {
+      "default": "./src/migrate.ts"
+    },
+    "./content-tables": {
+      "default": "./src/content-tables.ts"
+    },
+    "./custom-tables": {
+      "default": "./src/custom-tables-loader.ts"
+    },
+    "./schema-kit": {
+      "default": "./src/schema-kit.ts"
+    },
+    "./reconcile": {
+      "default": "./src/reconcile.ts"
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "drizzle",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "main": "./src/index.ts",
+    "exports": {
+      ".": {
+        "default": "./src/index.ts"
+      },
+      "./migrate": {
+        "default": "./src/migrate.ts"
+      },
+      "./content-tables": {
+        "default": "./src/content-tables.ts"
+      },
+      "./custom-tables": {
+        "default": "./src/custom-tables-loader.ts"
+      },
+      "./schema-kit": {
+        "default": "./src/schema-kit.ts"
+      },
+      "./reconcile": {
+        "default": "./src/reconcile.ts"
+      }
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir dist --target node --format esm --packages external && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "db:gin-indexes": "bun --env-file=../../.env run src/sql/apply-gin-indexes.ts",
+    "db:generate": "bun --env-file=../../.env drizzle-kit generate",
+    "db:migrate": "bun --env-file=../../.env run src/migrate.ts",
+    "db:reconcile": "bun --env-file=../../.env run src/reconcile.ts",
+    "db:studio": "bun --env-file=../../.env drizzle-kit studio",
+    "seed:skeleton": "bun --env-file=../../.env run src/seed/skeleton.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "postgres": "^3.4.4",
+    "@tangen/types": "^0.2.0"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.21.4"
+  }
+}

package/src/cache-keys.ts

@@ -0,0 +1,43 @@
+/**
+ * File Name: cache-keys.ts
+ * Purpose: The ONE place the Redis key namespace is defined. Cache keys (schema,
+ *   features, stats) are env-id scoped and env ids are global slugs (env_development),
+ *   so two different projects sharing one Redis would collide. Every key is namespaced
+ *   by a fingerprint of the project's database URL. Both the API (which writes/reads the
+ *   cache) and the CLI (which invalidates it on push) MUST derive the prefix identically —
+ *   if they drift, push's invalidation silently misses and the API serves a stale schema
+ *   until the TTL expires.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Uses Bun.hash — both the API and the CLI run under Bun.
+ */
+
+/**
+ * The Redis key prefix for a project, derived from its database URL. Applied by the
+ * API's ioredis client as `keyPrefix`, and prepended by the CLI when it invalidates.
+ */
+export function projectRedisPrefix(dbUrl: string | undefined | null): string {
+  const fingerprint = Bun.hash(dbUrl || 'local').toString(36).slice(0, 10)
+  return `tgn:${fingerprint}:`
+}
+
+/** The (un-prefixed) schema cache key for an env — the prefix is applied separately. */
+export function schemaCacheKey(): string {
+  return 'tangen:schema'
+}
+
+/** The fully-qualified schema cache key (prefix + key) — used where the client has no keyPrefix. */
+export function fullSchemaCacheKey(dbUrl: string | undefined | null): string {
+  return projectRedisPrefix(dbUrl) + schemaCacheKey()
+}
+
+/**
+ * The NOTIFY channel a schema push announces itself on, after its transaction
+ * has committed. The payload is the environment id whose schema changed - the
+ * one dimension the schema query is keyed by - so a listening API drops
+ * exactly that entry. Shared here because the CLI sends and the API listens,
+ * and neither may import the other.
+ */
+export const SCHEMA_CHANNEL = 'tangen_schema'

package/src/client.ts

@@ -0,0 +1,136 @@
+/**
+ * File Name: client.ts
+ * Purpose: Creates and returns a typed Drizzle ORM database client backed by a
+ *          postgres.js connection pool, with an `end()` helper for clean shutdown.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Uses drizzle-orm/postgres-js adapter. NOTICE-level messages
+ *                     from PostgreSQL are suppressed; higher-severity messages are
+ *                     forwarded to console.warn.
+ */
+import postgres from 'postgres'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import * as schema from './schema'
+import { instrumentSql } from './instrument'
+import { applyPreparePolicy } from './prepare-policy'
+
+/** Connection pool tuning options for createDb. */
+export interface DbPoolOptions {
+  /** Maximum pool connections (postgres.js default: 10). */
+  max?: number
+  /** Seconds an idle connection is kept before being closed. */
+  idleTimeout?: number
+  /** Seconds to wait when establishing a connection. */
+  connectTimeout?: number
+  /**
+   * Prepared execution for ordinary parameterized queries. Defaults to TRUE.
+   * Set false only for a proxy or pooler that cannot carry named statements -
+   * see `resolvePrepare` for the deployment contract.
+   */
+  prepare?: boolean
+}
+
+/** Where the effective preparation setting came from. */
+export type PrepareSource = 'option' | 'env' | 'default'
+
+/**
+ * The preparation policy, and why. Tangen owns this contract rather than
+ * inheriting postgres.js's default, so an unset variable has one documented
+ * meaning instead of whatever the driver happens to do.
+ *
+ * Precedence, unchanged by the default flip: an explicit `poolOptions.prepare`
+ * from a caller wins, then `TANGEN_DB_PREPARE`, then the default.
+ *
+ * The default is TRUE. Prepared execution removes one PostgreSQL protocol
+ * round trip from every repeated parameterized statement, which on a remote
+ * database is a large share of every read and write. Direct PostgreSQL and
+ * PgBouncer session pooling support it; so does PgBouncer 1.21+ in transaction
+ * pooling with `max_prepared_statements` above zero. A pooler or proxy that
+ * cannot carry named statements needs `TANGEN_DB_PREPARE=false`, which is a
+ * supported and permanent escape hatch, never overridden.
+ *
+ * Only the exact strings `true` and `false` are recognised; anything else is
+ * treated as unset, and `tangen doctor` reports the effective value with its
+ * source so a typo is visible rather than silent.
+ *
+ * @param opts - Explicit caller options.
+ * @param env - Environment map (injectable for tests).
+ * @returns The effective value and where it came from.
+ */
+export function resolvePrepare(
+  opts: Pick<DbPoolOptions, 'prepare'> = {},
+  env: Record<string, string | undefined> = process.env,
+): { prepare: boolean; source: PrepareSource } {
+  if (opts.prepare !== undefined) return { prepare: opts.prepare, source: 'option' }
+  if (env.TANGEN_DB_PREPARE === 'false') return { prepare: false, source: 'env' }
+  if (env.TANGEN_DB_PREPARE === 'true') return { prepare: true, source: 'env' }
+  return { prepare: true, source: 'default' }
+}
+
+/**
+ * Resolves postgres.js pool options from explicit options with env-var fallbacks
+ * (TANGEN_DB_POOL_MAX, TANGEN_DB_IDLE_TIMEOUT, TANGEN_DB_CONNECT_TIMEOUT,
+ * TANGEN_DB_PREPARE). Unset SIZE values are omitted so postgres.js defaults
+ * apply; `prepare` is always set, because Tangen decides that one.
+ * @param opts - Explicit pool options; win over environment variables.
+ * @param env - Environment map (injectable for tests; defaults to process.env).
+ * @returns Options object in postgres.js naming (max, idle_timeout, ...).
+ */
+export function resolvePoolOptions(
+  opts: DbPoolOptions,
+  env: Record<string, string | undefined> = process.env,
+): Record<string, number | boolean> {
+  const out: Record<string, number | boolean> = {}
+
+  const num = (explicit: number | undefined, envKey: string): number | undefined => {
+    if (explicit !== undefined) return explicit
+    const raw = env[envKey]
+    if (raw === undefined) return undefined
+    const n = Number(raw)
+    return Number.isFinite(n) ? n : undefined
+  }
+
+  const max = num(opts.max, 'TANGEN_DB_POOL_MAX')
+  if (max !== undefined) out.max = max
+  const idle = num(opts.idleTimeout, 'TANGEN_DB_IDLE_TIMEOUT')
+  if (idle !== undefined) out.idle_timeout = idle
+  const connect = num(opts.connectTimeout, 'TANGEN_DB_CONNECT_TIMEOUT')
+  if (connect !== undefined) out.connect_timeout = connect
+
+  out.prepare = resolvePrepare(opts, env).prepare
+
+  return out
+}
+
+/**
+ * Creates a Drizzle database client wrapping a postgres.js connection pool.
+ * @param databaseUrl - PostgreSQL connection string
+ * @param poolOptions - Optional pool tuning; env vars used as fallback
+ * @returns A Drizzle client extended with an `end()` method to close the pool
+ */
+export function createDb(databaseUrl: string, poolOptions: DbPoolOptions = {}) {
+  const resolved = resolvePoolOptions(poolOptions)
+  const client = postgres(databaseUrl, {
+    ...resolved,
+    onnotice: (n) => {
+      if (n.severity !== 'NOTICE') console.warn(`[db] ${n.severity}: ${n.message}`)
+    },
+  })
+  // Query Monitor tap: in-place, identity-preserving, inert until a hook is
+  // installed via setQueryHook (one ref read per query when off).
+  instrumentSql(client)
+  // Preparation policy: postgres.js executes every drizzle query unprepared
+  // whatever the pool says, so asking for it has to be threaded through by
+  // hand. Engages ONLY on an explicit `true`, so an unset TANGEN_DB_PREPARE
+  // keeps the behaviour it has today. See prepare-policy.ts.
+  applyPreparePolicy(client, resolved.prepare === true)
+  const db = drizzle(client, { schema })
+  // $rawClient: the underlying postgres.js client — for features that need
+  // parameterized raw SQL (e.g. @tangen/knowledge pgvector ops) without
+  // reaching into drizzle internals.
+  return Object.assign(db, { end: () => client.end(), $rawClient: client })
+}
+
+export type DbClient = ReturnType<typeof createDb>