@freestyle-sh/with-postgres 0.2.9 → 0.2.10

package/README.md

@@ -1,109 +1,101 @@
 # @freestyle-sh/with-postgres
 
-PostgreSQL runtime extension for Freestyle VMs. Provides a fully configured PostgreSQL database server in your Freestyle VM.
+PostgreSQL runtime extension for Freestyle VMs. Declaratively configure a PostgreSQL server, databases, and schema/seed scripts that run during VM snapshot setup.
 
 ## Installation
 
 ```bash
-npm install @freestyle-sh/with-postgres freestyle-sandboxes
+npm install @freestyle-sh/with-postgres freestyle
 ```
 
 ## Usage
 
 ```typescript
-import { freestyle } from "freestyle-sandboxes";
+import { freestyle, VmSpec } from "freestyle";
 import { VmPostgres } from "@freestyle-sh/with-postgres";
 
-const { vm } = await freestyle.vms.create({
-  with: {
-    postgres: new VmPostgres({
-      password: "mypassword",
-      database: "mydb",
-      version: "16", // Optional, defaults to "16"
-      user: "postgres", // Optional, defaults to "postgres"
-    }),
-  },
+const pg = new VmPostgres({ password: "secret" });
+
+const db = pg.database({ name: "myapp", create: true });
+
+const schema = db.script("schema", {
+  sql: `
+    CREATE TABLE users (
+      id SERIAL PRIMARY KEY,
+      name VARCHAR(100)
+    );
+  `,
 });
 
-// Create a table
-await vm.postgres.exec(`
-  CREATE TABLE users (
-    id SERIAL PRIMARY KEY,
-    name VARCHAR(100),
-    email VARCHAR(100)
-  )
-`);
-
-// Insert data
-await vm.postgres.exec(`
-  INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')
-`);
-
-// Query data
-const result = await vm.postgres.query<{ id: number; name: string; email: string }>(`
-  SELECT * FROM users
-`);
-
-console.log(result.rows); // [{ id: 1, name: 'Alice', email: 'alice@example.com' }]
-```
+const seed = db.script("seed", {
+  sql: `INSERT INTO users (name) VALUES ('Alice'), ('Bob');`,
+  after: [schema],
+});
 
-## API
+const spec = new VmSpec()
+  .with("postgres", pg)
+  .with("db", db)
+  .with("schema", schema)
+  .with("seed", seed)
+  .snapshot();
 
-### Constructor Options
+const { vm } = await freestyle.vms.create({ spec });
 
-- `version?: string` - PostgreSQL version to install (default: "16")
-- `password?: string` - Password for the postgres user (default: "postgres")
-- `database?: string` - Default database to create (default: "postgres")
-- `user?: string` - PostgreSQL user (default: "postgres")
+const result = await vm.db.query<{ id: number; name: string }>(
+  `SELECT * FROM users`
+);
+console.log(result.rows); // [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+```
 
-### Methods
+The install, database creation, and each script run as ordered systemd oneshot services during snapshot setup, so everything is baked into the snapshot.
 
-#### `query<T>(sql: string): Promise<QueryResult<T>>`
+## API
 
-Execute a SQL query and return results as JSON.
+### `new VmPostgres(options?)`
 
-**Returns:** `{ rows: T[], rowCount: number, error?: string }`
+Configures the PostgreSQL server. Pure config — has no runtime methods.
 
-```typescript
-const result = await vm.postgres.query<{ id: number; name: string }>(`
-  SELECT id, name FROM users WHERE id = 1
-`);
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `version` | `string` | `"18"` | PostgreSQL major version (installed from the official PGDG apt repo) |
+| `password` | `string` | `"postgres"` | Password for the postgres superuser |
+| `user` | `string` | `"postgres"` | PostgreSQL superuser name |
 
-#### `exec(sql: string): Promise<{ success: boolean, error?: string }>`
+### `pg.database({ name, create? })`
 
-Execute a SQL command without returning results (for CREATE, INSERT, UPDATE, DELETE, etc.).
+Declares a database. Returns a `Database` you can attach scripts to and query at runtime.
 
-```typescript
-const result = await vm.postgres.exec(`
-  UPDATE users SET name = 'Bob' WHERE id = 1
-`);
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | — | Database name |
+| `create` | `boolean` | `false` | If true, idempotently creates the database during snapshot setup |
 
-#### `createDatabase(dbName: string): Promise<{ success: boolean, error?: string }>`
+#### `vm.<name>.query<T>(sql)`
 
-Create a new database.
+Run a SQL query against this database. Returns `{ rows: T[], rowCount, error? }`. Results are returned as a JSON array (psql wraps the query in `json_agg(row_to_json(...))`).
 
-```typescript
-await vm.postgres.createDatabase("newdb");
-```
+#### `vm.<name>.exec(sql)`
 
-#### `dropDatabase(dbName: string): Promise<{ success: boolean, error?: string }>`
+Run a SQL command without returning rows. Returns `{ success, error? }`.
 
-Drop a database.
+### `db.script(name, { sql, after? })`
 
-```typescript
-await vm.postgres.dropDatabase("olddb");
-```
+Declares a SQL script that runs once during snapshot setup against this database.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sql` | `string` | — | Inline SQL to execute |
+| `after` | `DatabaseScript[]` | `[]` | Scripts that must run before this one |
+
+Each script becomes a systemd oneshot with `ON_ERROR_STOP=1`, so the snapshot fails fast if any SQL errors. Scripts depend automatically on the database's create service (or on `install-postgres` if `create: false`), and on every script listed in `after`.
 
-## How It Works
+#### `vm.<name>.logs()`
 
-The package uses a systemd oneshot service to install and configure PostgreSQL during VM creation:
+Returns the journalctl output for the script's systemd service as `string[]`.
 
-1. Installs PostgreSQL from apt repositories
-2. Configures password authentication
-3. Creates the default database (if specified)
-4. Enables network connections
-5. Starts PostgreSQL as a system service
+## How it works
 
-The installation is fully automated and completes during VM initialization.
+1. `VmPostgres` adds the official PGDG apt repository and installs the requested PostgreSQL version (see https://www.postgresql.org/download/linux/debian/), then sets the superuser password and enables md5 password auth on TCP and the local socket.
+2. Each `database({ create: true })` adds a oneshot that creates the database if it doesn't exist.
+3. Each `script(...)` writes its SQL to `/opt/pg-scripts/<db>/<name>.sql` and adds a oneshot that runs `psql -f` against the right database, in the order you declared via `after`.
+4. All setup oneshots use `deleteAfterSuccess: true`, so they don't re-run on reboot from the snapshot.

package/dist/index.d.ts

@@ -1,54 +1,83 @@
-import { VmWithInstance, VmWith, VmSpec } from 'freestyle-sandboxes';
+import { VmWith, VmWithInstance, VmSpec } from 'freestyle';
 
 interface PostgresOptions {
     version?: string;
     password?: string;
-    database?: string;
     user?: string;
 }
+interface ResolvedPostgresOptions {
+    version: string;
+    password: string;
+    user: string;
+}
 interface QueryResult<T = any> {
     rows: T[];
     rowCount: number;
     error?: string;
 }
+interface DatabaseOptions {
+    name: string;
+    create?: boolean;
+}
+interface ScriptOptions {
+    sql: string;
+    after?: DatabaseScript[];
+}
+declare class VmPostgres extends VmWith<VmPostgresInstance> {
+    options: ResolvedPostgresOptions;
+    constructor(options?: PostgresOptions);
+    database(options: DatabaseOptions): Database;
+    installServiceName(): string;
+    configureSnapshotSpec(spec: VmSpec): VmSpec;
+    createInstance(): VmPostgresInstance;
+}
 declare class VmPostgresInstance extends VmWithInstance {
-    private password;
+}
+declare class Database extends VmWith<DatabaseInstance> {
+    options: DatabaseOptions;
+    postgres: VmPostgres;
+    constructor(options: DatabaseOptions, postgres: VmPostgres);
+    script(name: string, options: ScriptOptions): DatabaseScript;
+    getCreateServiceName(): string;
+    configureSnapshotSpec(spec: VmSpec): VmSpec;
+    createInstance(): DatabaseInstance;
+}
+declare class DatabaseInstance extends VmWithInstance {
     private database;
     private user;
-    constructor(options: Required<PostgresOptions>);
+    private password;
+    constructor(opts: {
+        database: string;
+        user: string;
+        password: string;
+    });
     /**
-     * Execute a SQL query and return the results
+     * Execute a SQL query against this database and return the results.
      */
     query<T = any>(sql: string): Promise<QueryResult<T>>;
     /**
-     * Execute a SQL command without returning results (e.g., CREATE, INSERT, UPDATE, DELETE)
+     * Execute a SQL command without returning results (CREATE, INSERT, UPDATE, DELETE, etc.).
      */
     exec(sql: string): Promise<{
         success: boolean;
         error?: string;
     }>;
-    /**
-     * Create a new database
-     */
-    createDatabase(dbName: string): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
-    /**
-     * Drop a database
-     */
-    dropDatabase(dbName: string): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
 }
-declare class VmPostgres extends VmWith<VmPostgresInstance> {
-    private options;
-    constructor(options?: PostgresOptions);
+declare class DatabaseScript extends VmWith<DatabaseScriptInstance> {
+    name: string;
+    database: Database;
+    options: ScriptOptions;
+    constructor(name: string, database: Database, options: ScriptOptions);
+    getServiceName(): string;
+    getScriptPath(): string;
     configureSnapshotSpec(spec: VmSpec): VmSpec;
-    createInstance(): VmPostgresInstance;
-    installServiceName(): string;
+    createInstance(): DatabaseScriptInstance;
+}
+declare class DatabaseScriptInstance extends VmWithInstance {
+    private serviceName;
+    constructor(serviceName: string);
+    logs(): Promise<string[] | undefined>;
 }
 
-export { VmPostgres, VmPostgresInstance };
-export type { PostgresOptions, QueryResult };
+export { Database, DatabaseInstance, DatabaseScript, DatabaseScriptInstance, VmPostgres, VmPostgresInstance };
+export type { DatabaseOptions, PostgresOptions, QueryResult, ScriptOptions };

package/dist/index.js

@@ -1,24 +1,149 @@
-import { VmWithInstance, VmWith, VmSpec } from 'freestyle-sandboxes';
+import { VmWith, VmSpec, VmWithInstance } from 'freestyle';
 
+class VmPostgres extends VmWith {
+  options;
+  constructor(options = {}) {
+    super();
+    this.options = {
+      version: options.version || "18",
+      password: options.password || "postgres",
+      user: options.user || "postgres"
+    };
+  }
+  database(options) {
+    return new Database(options, this);
+  }
+  installServiceName() {
+    return "install-postgres.service";
+  }
+  configureSnapshotSpec(spec) {
+    const installScript = `#!/bin/bash
+set -e
+
+# Add the official PostgreSQL apt repository (PGDG) so any
+# PostgreSQL version is available on any Debian release.
+# See https://www.postgresql.org/download/linux/debian/
+sudo apt-get update
+sudo apt-get install -y curl ca-certificates
+sudo install -d /usr/share/postgresql-common/pgdg
+sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail   https://www.postgresql.org/media/keys/ACCC4CF8.asc
+. /etc/os-release
+sudo sh -c "echo 'deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $VERSION_CODENAME-pgdg main' > /etc/apt/sources.list.d/pgdg.list"
+
+# Install PostgreSQL
+sudo apt-get update
+sudo apt-get install -y postgresql-${this.options.version} postgresql-client-${this.options.version}
+
+# Start PostgreSQL
+sudo systemctl start postgresql
+
+# Set password for postgres user
+sudo -u postgres psql -c "ALTER USER postgres PASSWORD '${this.options.password}';"
+
+# Configure PostgreSQL to accept password authentication
+echo "host all all 0.0.0.0/0 md5" | sudo tee -a /etc/postgresql/${this.options.version}/main/pg_hba.conf
+echo "local all all md5" | sudo tee -a /etc/postgresql/${this.options.version}/main/pg_hba.conf
+
+# Allow connections from all addresses
+sudo sed -i "s/#listen_addresses = 'localhost'/listen_addresses = '*'/" /etc/postgresql/${this.options.version}/main/postgresql.conf
+
+# Restart PostgreSQL to apply changes
+sudo systemctl restart postgresql
+
+# Enable PostgreSQL to start on boot
+sudo systemctl enable postgresql
+`;
+    return this.composeSpecs(
+      spec,
+      new VmSpec({
+        additionalFiles: {
+          "/opt/install-postgres.sh": { content: installScript }
+        },
+        systemd: {
+          services: [
+            {
+              name: "install-postgres",
+              mode: "oneshot",
+              deleteAfterSuccess: true,
+              exec: ["bash /opt/install-postgres.sh"],
+              timeoutSec: 600
+            }
+          ]
+        }
+      })
+    );
+  }
+  createInstance() {
+    return new VmPostgresInstance();
+  }
+}
 class VmPostgresInstance extends VmWithInstance {
-  password;
+}
+class Database extends VmWith {
+  options;
+  postgres;
+  constructor(options, postgres) {
+    super();
+    this.options = options;
+    this.postgres = postgres;
+  }
+  script(name, options) {
+    return new DatabaseScript(name, this, options);
+  }
+  getCreateServiceName() {
+    return `pg-create-${this.options.name}`;
+  }
+  configureSnapshotSpec(spec) {
+    if (!this.options.create) return spec;
+    const { password, user } = this.postgres.options;
+    const dbName = this.options.name;
+    const psqlBase = `PGPASSWORD='${password}' psql -h 127.0.0.1 -U ${user} -d postgres`;
+    const createCmd = `${psqlBase} -tAc "SELECT 1 FROM pg_database WHERE datname='${dbName}'" | grep -q 1 || ${psqlBase} -c 'CREATE DATABASE ${dbName}'`;
+    return this.composeSpecs(
+      spec,
+      new VmSpec({
+        systemd: {
+          services: [
+            {
+              name: this.getCreateServiceName(),
+              mode: "oneshot",
+              deleteAfterSuccess: true,
+              after: [this.postgres.installServiceName()],
+              requires: [this.postgres.installServiceName()],
+              bash: createCmd,
+              timeoutSec: 60
+            }
+          ]
+        }
+      })
+    );
+  }
+  createInstance() {
+    return new DatabaseInstance({
+      database: this.options.name,
+      user: this.postgres.options.user,
+      password: this.postgres.options.password
+    });
+  }
+}
+class DatabaseInstance extends VmWithInstance {
   database;
   user;
-  constructor(options) {
+  password;
+  constructor(opts) {
     super();
-    this.password = options.password;
-    this.database = options.database;
-    this.user = options.user;
+    this.database = opts.database;
+    this.user = opts.user;
+    this.password = opts.password;
   }
   /**
-   * Execute a SQL query and return the results
+   * Execute a SQL query against this database and return the results.
    */
   async query(sql) {
-    const escapedSql = sql.replace(/'/g, "'\\''");
-    const command = `PGPASSWORD='${this.password}' psql -U ${this.user} -d ${this.database} -t -A -F',' -c '${escapedSql}' --json`;
-    const result = await this.vm.exec({
-      command
-    });
+    const wrappedSql = `SELECT COALESCE(json_agg(row_to_json(t)), '[]'::json) FROM (${sql}) t`;
+    const escapedSql = wrappedSql.replace(/'/g, "'\\''");
+    const command = `PGPASSWORD='${this.password}' psql -h 127.0.0.1 -U ${this.user} -d ${this.database} -t -A -c '${escapedSql}'`;
+    const result = await this.vm.exec({ command });
     if (result.statusCode !== 0) {
       return {
         rows: [],
@@ -41,14 +166,12 @@ class VmPostgresInstance extends VmWithInstance {
     }
   }
   /**
-   * Execute a SQL command without returning results (e.g., CREATE, INSERT, UPDATE, DELETE)
+   * Execute a SQL command without returning results (CREATE, INSERT, UPDATE, DELETE, etc.).
    */
   async exec(sql) {
     const escapedSql = sql.replace(/'/g, "'\\''");
-    const command = `PGPASSWORD='${this.password}' psql -U ${this.user} -d ${this.database} -c '${escapedSql}'`;
-    const result = await this.vm.exec({
-      command
-    });
+    const command = `PGPASSWORD='${this.password}' psql -h 127.0.0.1 -U ${this.user} -d ${this.database} -c '${escapedSql}'`;
+    const result = await this.vm.exec({ command });
     if (result.statusCode !== 0) {
       return {
         success: false,
@@ -57,98 +180,53 @@ class VmPostgresInstance extends VmWithInstance {
     }
     return { success: true };
   }
-  /**
-   * Create a new database
-   */
-  async createDatabase(dbName) {
-    const command = `PGPASSWORD='${this.password}' psql -U ${this.user} -d postgres -c 'CREATE DATABASE ${dbName}'`;
-    const result = await this.vm.exec({
-      command
-    });
-    if (result.statusCode !== 0) {
-      return {
-        success: false,
-        error: result.stderr || "Database creation failed"
-      };
-    }
-    return { success: true };
-  }
-  /**
-   * Drop a database
-   */
-  async dropDatabase(dbName) {
-    const command = `PGPASSWORD='${this.password}' psql -U ${this.user} -d postgres -c 'DROP DATABASE IF EXISTS ${dbName}'`;
-    const result = await this.vm.exec({
-      command
-    });
-    if (result.statusCode !== 0) {
-      return {
-        success: false,
-        error: result.stderr || "Database drop failed"
-      };
-    }
-    return { success: true };
-  }
 }
-class VmPostgres extends VmWith {
+class DatabaseScript extends VmWith {
+  name;
+  database;
   options;
-  constructor(options = {}) {
+  constructor(name, database, options) {
     super();
-    this.options = {
-      version: options.version || "16",
-      password: options.password || "postgres",
-      database: options.database || "postgres",
-      user: options.user || "postgres"
-    };
+    this.name = name;
+    this.database = database;
+    this.options = options;
+  }
+  getServiceName() {
+    return `pg-script-${this.database.options.name}-${this.name}`;
+  }
+  getScriptPath() {
+    return `/opt/pg-scripts/${this.database.options.name}/${this.name}.sql`;
   }
   configureSnapshotSpec(spec) {
-    const installScript = `#!/bin/bash
-set -e
-
-# Install PostgreSQL
-sudo apt-get update
-sudo apt-get install -y postgresql-${this.options.version} postgresql-client-${this.options.version}
-
-# Start PostgreSQL
-sudo systemctl start postgresql
-
-# Set password for postgres user
-sudo -u postgres psql -c "ALTER USER postgres PASSWORD '${this.options.password}';"
-
-# Create default database if not postgres
-if [ "${this.options.database}" != "postgres" ]; then
-  sudo -u postgres psql -c "CREATE DATABASE ${this.options.database};"
-fi
-
-# Configure PostgreSQL to accept password authentication
-echo "host all all 0.0.0.0/0 md5" | sudo tee -a /etc/postgresql/${this.options.version}/main/pg_hba.conf
-echo "local all all md5" | sudo tee -a /etc/postgresql/${this.options.version}/main/pg_hba.conf
-
-# Allow connections from all addresses
-sudo sed -i "s/#listen_addresses = 'localhost'/listen_addresses = '*'/" /etc/postgresql/${this.options.version}/main/postgresql.conf
-
-# Restart PostgreSQL to apply changes
-sudo systemctl restart postgresql
-
-# Enable PostgreSQL to start on boot
-sudo systemctl enable postgresql
-`;
+    const { password, user } = this.database.postgres.options;
+    const dbName = this.database.options.name;
+    const scriptPath = this.getScriptPath();
+    const deps = [];
+    if (this.database.options.create) {
+      deps.push(this.database.getCreateServiceName());
+    } else {
+      deps.push(this.database.postgres.installServiceName());
+    }
+    for (const dep of this.options.after ?? []) {
+      deps.push(dep.getServiceName());
+    }
+    const command = `PGPASSWORD='${password}' psql -h 127.0.0.1 -U ${user} -d ${dbName} -v ON_ERROR_STOP=1 -f ${scriptPath}`;
     return this.composeSpecs(
       spec,
       new VmSpec({
         additionalFiles: {
-          "/opt/install-postgres.sh": {
-            content: installScript
-          }
+          [scriptPath]: { content: this.options.sql }
         },
         systemd: {
           services: [
             {
-              name: "install-postgres",
+              name: this.getServiceName(),
               mode: "oneshot",
               deleteAfterSuccess: true,
-              exec: ["bash /opt/install-postgres.sh"],
-              timeoutSec: 600
+              after: deps,
+              requires: deps,
+              bash: command,
+              timeoutSec: 300
             }
           ]
         }
@@ -156,11 +234,20 @@ sudo systemctl enable postgresql
     );
   }
   createInstance() {
-    return new VmPostgresInstance(this.options);
+    return new DatabaseScriptInstance(this.getServiceName());
   }
-  installServiceName() {
-    return "install-postgres.service";
+}
+class DatabaseScriptInstance extends VmWithInstance {
+  serviceName;
+  constructor(serviceName) {
+    super();
+    this.serviceName = serviceName;
+  }
+  logs() {
+    return this.vm.exec({
+      command: `journalctl -u ${this.serviceName} --no-pager -n 100`
+    }).then((result) => result.stdout?.trim().split("\n"));
   }
 }
 
-export { VmPostgres, VmPostgresInstance };
+export { Database, DatabaseInstance, DatabaseScript, DatabaseScriptInstance, VmPostgres, VmPostgresInstance };

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@freestyle-sh/with-postgres",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "private": false,
   "dependencies": {
-    "freestyle-sandboxes": "^0.1.28"
+    "freestyle": "^0.1.46"
   },
   "type": "module",
   "main": "./dist/index.js",