@schemic/postgres 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vertio Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @schemic/postgres
+
+The PostgreSQL driver for [Schemic](https://github.com/schemichq/schemic) —
+author your Postgres schema in TypeScript and emit, introspect, and diff it as
+native SQL DDL.
+
+> [!NOTE]
+> **Alpha.** Today the driver runs on embedded [PGlite](https://pglite.dev):
+> authoring, DDL emit, introspection, and migrations round-trip against it. A
+> client for hosted Postgres servers is planned. See
+> [docs/COVERAGE.md](docs/COVERAGE.md) for the feature-by-feature status.
+
+## Install
+
+```bash
+bun add @schemic/cli @schemic/postgres @electric-sql/pglite
+```
+
+`@electric-sql/pglite` is the embedded engine (the only engine today). `zod`
+ships with the driver — add it yourself only if you import `z` directly for
+custom codecs.
+
+## Quick start
+
+Scaffold a Postgres project (`sc` is the short alias for `schemic`):
+
+```bash
+sc init --driver postgres
+```
+
+`init` writes a `schemic.config.ts`, a sample schema, a seed stub, and
+`.env.example`. The sample schema:
+
+```ts
+// database/schema/tables.ts
+import { defineTable, s, sqlExpr } from "@schemic/postgres";
+
+export const user = defineTable("user", {
+  email: s.varchar(255).$unique(),
+  name: s.text(),
+  age: s.smallint().optional(),
+  createdAt: s.timestamptz().$default(sqlExpr("now()")),
+});
+```
+
+…which emits this Postgres DDL (an `id` primary key is added automatically):
+
+```sql
+CREATE TABLE "user" (
+  "id" text PRIMARY KEY,
+  "age" smallint,
+  "createdAt" timestamp with time zone NOT NULL DEFAULT now(),
+  "email" varchar(255) NOT NULL,
+  "name" text NOT NULL
+);
+CREATE UNIQUE INDEX "user_email_key" ON "user" ("email");
+```
+
+The connection lives in `schemic.config.ts` — a named connection from the
+`postgresConnection` factory (no `driver:` string to keep in sync):
+
+```ts
+import { defineConfig } from "@schemic/core/config";
+import { postgresConnection } from "@schemic/postgres";
+
+export default defineConfig({
+  connections: {
+    default: postgresConnection({
+      schema: "./database/schema",
+      // PGlite (embedded): `file:<dir>` persists to a data dir; "" is in-memory.
+      url: process.env.DATABASE_URL ?? "file:./.pgdata",
+    }),
+  },
+});
+```
+
+Then drive it from the CLI:
+
+```bash
+sc diff        # preview changes vs the last snapshot
+sc gen         # write a migration for the pending change
+sc migrate     # apply pending migrations
+sc seed        # run database/seed.ts against a connection
+sc status      # show applied vs pending migrations
+```
+
+## Authoring
+
+`s.*` is a [Zod](https://zod.dev) superset with Postgres-native types —
+`s.varchar(n)`, `s.text()`, `s.smallint()`, `s.timestamptz()`, and more — plus
+DDL modifiers like `.$unique()` and `.$default(sqlExpr(...))`. Reach for
+`sqlExpr` to drop raw SQL into defaults and other expressions.
+
+## Docs
+
+Feature-by-feature coverage: [docs/COVERAGE.md](docs/COVERAGE.md). This package
+is part of the [Schemic](https://github.com/schemichq/schemic) toolkit — shared
+concepts (schema-as-code, the migration model, codecs) are at
+[schemic.dev](https://schemic.dev).
+
+## License
+
+[MIT](./LICENSE) © Vertio Solutions

package/lib/index.d.ts

@@ -0,0 +1,240 @@
+import { ConnectionConfigBase, ConnectionEntry, ResolveContext, Driver } from '@schemic/core/driver';
+import { SFieldBase, AnyField, SchemaOf } from '@schemic/core/authoring';
+import * as z from 'zod';
+
+/** A pg column type token + optional params (`varchar`/[255], `numeric`/[10,2]); the leaf factory sets it. */
+interface PgTypeRef {
+    type: string;
+    params?: (string | number)[];
+}
+/** Postgres-native field metadata (the `native` slot of {@link PgField}). All optional; merged by `$`-methods. */
+interface PgMeta {
+    /** The pg base type (sans option/nullable/array wrappers, which live on the Zod schema). */
+    pg?: PgTypeRef;
+    /** `DEFAULT <expr>` (verbatim SQL). */
+    default?: string;
+    /** Field-level `CHECK (<expr>)` (verbatim SQL boolean expr). */
+    check?: string;
+    /** `GENERATED ALWAYS AS (<expr>) STORED` (verbatim SQL expr). */
+    generated?: string;
+    /** `GENERATED {ALWAYS|BY DEFAULT} AS IDENTITY` (also how `serial` is modeled). */
+    identity?: "always" | "by-default";
+    /** Column-level `UNIQUE`. */
+    unique?: boolean;
+    /** Column is (part of) the PRIMARY KEY. */
+    primaryKey?: boolean;
+    /** A foreign key to `table(id)` with optional referential actions. */
+    references?: {
+        table: string;
+        onDelete?: string;
+        onUpdate?: string;
+    };
+    /** `COMMENT ON COLUMN`. */
+    comment?: string;
+}
+/** A raw SQL expression marker for DDL clauses (`$default`/`$check`/`$generated`) — spliced verbatim. */
+interface SqlExpr {
+    readonly __sql: string;
+}
+/** Mark a string as a raw SQL expression (vs a literal value) for a DDL clause: `s.timestamptz().$default(sqlExpr("now()"))`. */
+declare const sqlExpr: (sql: string) => SqlExpr;
+/**
+ * A Postgres field: a Zod schema (App/Wire typing) + {@link PgMeta} (pg-native DDL metadata). Extends
+ * the neutral {@link SFieldBase}, which supplies the codecs, the Zod wrappers, and the `z.*` passthrough;
+ * this subclass re-types the wrappers so a chain stays a `PgField`, and adds the pg `$`-methods.
+ */
+declare class PgField<S extends z.ZodType = z.ZodType, Flags extends string = never> extends SFieldBase<S, Flags, PgMeta> {
+    protected rebuild<S2 extends z.ZodType, F2 extends string>(schema: S2, native: PgMeta): PgField<S2, F2>;
+    protected blank(): PgMeta;
+    optional: () => PgField<z.ZodOptional<S>, Flags>;
+    nullable: () => PgField<z.ZodNullable<S>, Flags>;
+    nullish: () => PgField<z.ZodOptional<z.ZodNullable<S>>, Flags>;
+    array: () => PgField<z.ZodArray<S>, Flags>;
+    default: (value: z.input<S>) => PgField<z.ZodDefault<S>, Flags>;
+    prefault: (value: z.input<S>) => PgField<z.ZodPrefault<S>, Flags>;
+    catch: (value: z.output<S>) => PgField<z.ZodCatch<S>, Flags>;
+    private with;
+    /** `DEFAULT <value>` — a JS literal, or `sqlExpr("now()")` for a raw SQL default. */
+    $default(value: z.input<S> | SqlExpr): PgField<S, Flags>;
+    /** Field-level `CHECK (<expr>)`. */
+    $check(expr: string | SqlExpr): PgField<S, Flags>;
+    /** `GENERATED ALWAYS AS (<expr>) STORED` — a computed column. */
+    $generated(expr: string | SqlExpr): PgField<S, Flags>;
+    /** `GENERATED {ALWAYS|BY DEFAULT} AS IDENTITY` (auto-increment). */
+    $identity(mode?: "always" | "by-default"): PgField<S, Flags>;
+    /** Column-level `UNIQUE`. */
+    $unique(): PgField<S, Flags>;
+    /** Mark this column (part of) the PRIMARY KEY. */
+    $primaryKey(): PgField<S, Flags>;
+    /** Foreign key to `table(id)` with optional `ON DELETE`/`ON UPDATE` actions. */
+    $references(table: string, opts?: {
+        onDelete?: string;
+        onUpdate?: string;
+    }): PgField<S, Flags>;
+    /** `COMMENT ON COLUMN`. */
+    $comment(text: string): PgField<S, Flags>;
+    /**
+     * ESCAPE HATCH (chainable form) — teach the driver how to STORE this field's value in Postgres:
+     * give the **wire type** as an `s.*`/Zod field (its pg column type is taken from it) plus a codec
+     * (`encode`: app -> wire, `decode`: wire -> app). This turns an otherwise-unmappable App value
+     * (e.g. `s.instanceof(Money)`) into a real pg column. Omit the codec for an identity mapping (the
+     * app value is stored as-is). Mirrors SurrealDB's `.$surreal(wire, codec)`; the standalone
+     * {@link s.$postgres} factory is the from-scratch equivalent. `$`-prefixed to avoid clashing with Zod.
+     */
+    $postgres<WF extends AnyField | z.ZodType, A = z.output<S>>(wire: WF, codec?: {
+        encode: (app: A) => z.output<SchemaOf<WF>>;
+        decode: (wire: z.output<SchemaOf<WF>>) => A;
+    }): PgField<z.ZodCodec<SchemaOf<WF>, S>, Flags>;
+}
+/** The Postgres authoring namespace. Zod drop-ins (string/number/…) + native pg types + `$postgres`. */
+declare const s: {
+    string: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    number: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    text: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    varchar: (n?: number) => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    char: (n?: number) => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    citext: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    smallint: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    integer: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    int: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    bigint: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    serial: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    bigserial: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    numeric: (precision?: number, scale?: number) => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    decimal: (precision?: number, scale?: number) => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    real: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    doublePrecision: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    float: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    money: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    boolean: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    bool: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    timestamptz: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    timestamp: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    date: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    time: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    timetz: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    interval: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    uuid: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    bytea: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    inet: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    cidr: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    macaddr: () => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    jsonb: <T extends z.ZodType = z.ZodUnknown>(shape?: T) => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    json: <T extends z.ZodType = z.ZodUnknown>(shape?: T) => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    enum: <const T extends readonly [string, ...string[]]>(values: T) => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    literal: <const V extends string | number | boolean>(value: V) => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    object: (shape: Record<string, AnyField | z.ZodType>) => PgField<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, never>;
+    array: (elem: AnyField | z.ZodType) => PgField;
+    references: (table: string, opts?: {
+        onDelete?: string;
+        onUpdate?: string;
+    }) => PgField;
+    /**
+     * ESCAPE HATCH — a pg type with no portable meaning, stored via a Zod codec (encode/decode). The
+     * column is emitted as `pgType`; App-side reads/writes go through `codec`. Mirrors surreal `$surreal`.
+     */
+    $postgres: <C extends z.ZodType>(pgType: string, codec: C) => PgField<C>;
+};
+/** Table-level pg config: composite PK, table CHECKs, and secondary indexes. */
+interface PgTableConfig {
+    primaryKey?: string[];
+    checks?: string[];
+    indexes?: {
+        name?: string;
+        cols: string[];
+        unique?: boolean;
+    }[];
+}
+/**
+ * A Postgres table definition — the `Authored` object the driver's `lower` reads. Structurally a
+ * `{ name }` (the neutral `Authored` bound); also carries its `fields` (a `{ col: PgField }` map) and
+ * table-level config. Chainable: `.primaryKey(...)`, `.check(expr)`, `.index([...])`.
+ */
+declare class PgTableDef<Name extends string = string, F extends Record<string, PgField> = Record<string, PgField>> {
+    readonly name: Name;
+    readonly fields: F;
+    readonly config: PgTableConfig;
+    constructor(name: Name, fields: F, config?: PgTableConfig);
+    /** Composite / custom PRIMARY KEY (overrides the implicit `id`). */
+    primaryKey(...cols: (keyof F & string)[]): PgTableDef<Name, F>;
+    /** A table-level `CHECK (<expr>)`. */
+    check(expr: string): PgTableDef<Name, F>;
+    /** A secondary index over `cols` (optionally `UNIQUE`). */
+    index(cols: (keyof F & string)[], opts?: {
+        name?: string;
+        unique?: boolean;
+    }): PgTableDef<Name, F>;
+    /**
+     * A foreign-key field referencing THIS table (for use in another table's shape):
+     * `author: user.record({ onDelete: "cascade" })`. Also satisfies the CLI's structural table check.
+     */
+    record(opts?: {
+        onDelete?: string;
+        onUpdate?: string;
+    }): PgField;
+}
+/** Declare a Postgres table: `export const user = defineTable("user", { name: s.text(), age: s.integer().optional() })`. */
+declare function defineTable<Name extends string, F extends Record<string, PgField>>(name: Name, fields: F, config?: PgTableConfig): PgTableDef<Name, F>;
+/** The decoded (App-land) row type of a table — `z.output` of each field's schema. */
+type App<T extends PgTableDef> = {
+    [K in keyof T["fields"]]: z.output<T["fields"][K]["schema"]>;
+};
+/** The encoded (wire) row type of a table — `z.input` of each field's schema. */
+type Wire<T extends PgTableDef> = {
+    [K in keyof T["fields"]]: z.input<T["fields"][K]["schema"]>;
+};
+
+interface PgConn {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    exec(sql: string): Promise<unknown>;
+    close(): Promise<void>;
+}
+/** A bound Postgres query: text with positional `$1..$n` placeholders + the values bound to them. */
+interface BoundPgQuery {
+    query: string;
+    params: unknown[];
+}
+/** A raw SQL fragment spliced VERBATIM into a `pgSql` template (NOT parameterized — caller-trusted). */
+interface PgFragment {
+    readonly __pgRaw: string;
+}
+/** Splice a raw SQL string verbatim (NOT parameterized — only for caller-trusted SQL). */
+declare function raw(sql: string): PgFragment;
+/** A safely double-quoted identifier (table/column) to splice into a `pgSql` template. */
+declare function identifier(name: string): PgFragment;
+/**
+ * Tagged-template SQL builder — the Postgres analogue of SurrealDB's `surql`. Interpolated values
+ * become positional bind params (`$1..$n`), so values are never string-interpolated (injection-safe).
+ * Wrap a value in {@link raw} / {@link identifier} to splice SQL STRUCTURE instead of a param, and a
+ * nested `pgSql` composes (its placeholders renumber, its params merge). Returns a {@link BoundPgQuery}
+ * — it does NOT execute; pass it to `postgresDriver.query` / `conn.query`, or nest it in another `pgSql`.
+ *
+ *   pgSql`SELECT * FROM ${identifier("user")} WHERE id = ${id}`
+ *   // -> { query: 'SELECT * FROM "user" WHERE id = $1', params: [id] }
+ */
+declare function pgSql(strings: TemplateStringsArray, ...values: unknown[]): BoundPgQuery;
+/** Postgres connection params, on top of the dialect-neutral base ({schema, key?, migrations?}). */
+interface PostgresConnectionConfig extends ConnectionConfigBase {
+    /**
+     * Where to connect. `file:<dir>` (or a bare path) -> embedded PGlite data dir; empty/omitted ->
+     * in-memory PGlite. A `postgres://` URL is reserved for a future node-postgres client.
+     */
+    url?: string;
+}
+/**
+ * Typed `postgresConnection(...)` factory — the only thing a config's `connections` map accepts for
+ * this driver. Wraps {@link connectionEntry} with the Postgres connection shape. Pass a static config,
+ * a resolver yielding one config, or a resolver yielding a keyed COLLECTION (each entry needs `key`).
+ */
+declare function postgresConnection(config: PostgresConnectionConfig): ConnectionEntry;
+declare function postgresConnection(resolver: (ctx: ResolveContext) => PostgresConnectionConfig | Promise<PostgresConnectionConfig>): ConnectionEntry;
+declare function postgresConnection(resolver: (ctx: ResolveContext) => (PostgresConnectionConfig & {
+    key: string;
+})[] | Promise<(PostgresConnectionConfig & {
+    key: string;
+})[]>): ConnectionEntry;
+declare const postgresDriver: Driver<PgConn>;
+
+export { type App, type BoundPgQuery, type PgConn, PgField, type PgMeta, type PgTableConfig, PgTableDef, type PgTypeRef, type PostgresConnectionConfig, type SqlExpr, type Wire, defineTable, identifier, pgSql, postgresConnection, postgresDriver, raw, s, sqlExpr };