@freestyle-sh/with-postgres 0.2.1

package/README.md

@@ -0,0 +1,109 @@
+# @freestyle-sh/with-postgres
+
+PostgreSQL runtime extension for Freestyle VMs. Provides a fully configured PostgreSQL database server in your Freestyle VM.
+
+## Installation
+
+```bash
+npm install @freestyle-sh/with-postgres freestyle-sandboxes
+```
+
+## Usage
+
+```typescript
+import { freestyle } from "freestyle-sandboxes";
+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"
+    }),
+  },
+});
+
+// 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' }]
+```
+
+## API
+
+### Constructor Options
+
+- `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")
+
+### Methods
+
+#### `query<T>(sql: string): Promise<QueryResult<T>>`
+
+Execute a SQL query and return results as JSON.
+
+**Returns:** `{ rows: T[], rowCount: number, error?: string }`
+
+```typescript
+const result = await vm.postgres.query<{ id: number; name: string }>(`
+  SELECT id, name FROM users WHERE id = 1
+`);
+```
+
+#### `exec(sql: string): Promise<{ success: boolean, error?: string }>`
+
+Execute a SQL command without returning results (for CREATE, INSERT, UPDATE, DELETE, etc.).
+
+```typescript
+const result = await vm.postgres.exec(`
+  UPDATE users SET name = 'Bob' WHERE id = 1
+`);
+```
+
+#### `createDatabase(dbName: string): Promise<{ success: boolean, error?: string }>`
+
+Create a new database.
+
+```typescript
+await vm.postgres.createDatabase("newdb");
+```
+
+#### `dropDatabase(dbName: string): Promise<{ success: boolean, error?: string }>`
+
+Drop a database.
+
+```typescript
+await vm.postgres.dropDatabase("olddb");
+```
+
+## How It Works
+
+The package uses a systemd oneshot service to install and configure PostgreSQL during VM creation:
+
+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
+
+The installation is fully automated and completes during VM initialization.

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { VmWithInstance, VmWith, VmSpec } from 'freestyle-sandboxes';
+
+interface PostgresOptions {
+    version?: string;
+    password?: string;
+    database?: string;
+    user?: string;
+}
+interface QueryResult<T = any> {
+    rows: T[];
+    rowCount: number;
+    error?: string;
+}
+declare class VmPostgresInstance extends VmWithInstance {
+    private password;
+    private database;
+    private user;
+    constructor(options: Required<PostgresOptions>);
+    /**
+     * Execute a SQL query 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)
+     */
+    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);
+    configureSnapshotSpec(spec: VmSpec): VmSpec;
+    createInstance(): VmPostgresInstance;
+    installServiceName(): string;
+}
+
+export { VmPostgres, VmPostgresInstance };
+export type { PostgresOptions, QueryResult };

package/dist/index.js

@@ -0,0 +1,166 @@
+import { VmWithInstance, VmWith, VmSpec } from 'freestyle-sandboxes';
+
+class VmPostgresInstance extends VmWithInstance {
+  password;
+  database;
+  user;
+  constructor(options) {
+    super();
+    this.password = options.password;
+    this.database = options.database;
+    this.user = options.user;
+  }
+  /**
+   * Execute a SQL query 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
+    });
+    if (result.statusCode !== 0) {
+      return {
+        rows: [],
+        rowCount: 0,
+        error: result.stderr || "Query execution failed"
+      };
+    }
+    try {
+      const parsed = JSON.parse(result.stdout || "[]");
+      return {
+        rows: Array.isArray(parsed) ? parsed : [],
+        rowCount: Array.isArray(parsed) ? parsed.length : 0
+      };
+    } catch (e) {
+      return {
+        rows: [],
+        rowCount: 0,
+        error: `Failed to parse query results: ${e}`
+      };
+    }
+  }
+  /**
+   * Execute a SQL command without returning results (e.g., CREATE, INSERT, UPDATE, DELETE)
+   */
+  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
+    });
+    if (result.statusCode !== 0) {
+      return {
+        success: false,
+        error: result.stderr || "Command execution failed"
+      };
+    }
+    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 {
+  options;
+  constructor(options = {}) {
+    super();
+    this.options = {
+      version: options.version || "16",
+      password: options.password || "postgres",
+      database: options.database || "postgres",
+      user: options.user || "postgres"
+    };
+  }
+  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
+`;
+    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(this.options);
+  }
+  installServiceName() {
+    return "install-postgres.service";
+  }
+}
+
+export { VmPostgres, VmPostgresInstance };

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@freestyle-sh/with-postgres",
+  "version": "0.2.1",
+  "private": false,
+  "dependencies": {
+    "freestyle-sandboxes": "^0.1.8"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "source": "./src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "pkgroll"
+  }
+}