feat(pg): add exportSchemas function for DDL generation (#11448)

## Description

Add `exportSchemas()` function that exports Mastra database schema as
SQL DDL statements without requiring a database connection. This is
useful for:
- Generating migration scripts
- Reviewing the schema before deployment
- Creating database schemas in environments where the application
doesn't have CREATE privileges

Also refactored internal code to eliminate duplication:
- Extracted `generateTableSQL()` function from `createTable()` method
- Consolidated SQL type mapping into a single `mapToSqlType()` function

## Related Issue(s)

<!-- None - this is a new feature -->

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [x] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Export database schemas as SQL DDL without a DB connection; optional
schema name for targeted exports (emits CREATE SCHEMA if needed).
* Centralized SQL type handling for consistent DDL (including
timezone-aware timestamp columns).
* Schema export function exposed in the public storage API with usage
examples.

* **Tests**
* Added tests validating exported SQL for default and custom schemas,
constraint names, timestamps, and invalid/allowed schema names.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: gmethvin

.changeset/add-pg-export-schemas.md

@@ -0,0 +1,27 @@
+---
+"@mastra/pg": patch
+---
+
+Added `exportSchemas()` function to generate Mastra database schema as SQL DDL without a database connection.
+
+**What's New**
+
+You can now export your Mastra database schema as SQL DDL statements without connecting to a database. This is useful for:
+
+- Generating migration scripts
+- Reviewing the schema before deployment
+- Creating database schemas in environments where the application doesn't have CREATE privileges
+
+**Example**
+
+```typescript
+import { exportSchemas } from '@mastra/pg';
+
+// Export schema for default 'public' schema
+const ddl = exportSchemas();
+console.log(ddl);
+
+// Export schema for a custom schema
+const customDdl = exportSchemas('my_schema');
+// Creates: CREATE SCHEMA IF NOT EXISTS "my_schema"; and all tables within it
+```

stores/pg/src/storage/db/index.ts

@@ -152,6 +152,118 @@ function getTableName({ indexName, schemaName }: { indexName: string; schemaName
   return quotedSchemaName ? `${quotedSchemaName}.${quotedIndexName}` : quotedIndexName;
 }
 
+function mapToSqlType(type: StorageColumn['type']): string {
+  switch (type) {
+    case 'uuid':
+      return 'UUID';
+    case 'boolean':
+      return 'BOOLEAN';
+    default:
+      return getSqlType(type);
+  }
+}
+
+function generateTableSQL({
+  tableName,
+  schema,
+  schemaName,
+}: {
+  tableName: TABLE_NAMES;
+  schema: Record<string, StorageColumn>;
+  schemaName?: string;
+}): string {
+  const timeZColumns = Object.entries(schema)
+    .filter(([_, def]) => def.type === 'timestamp')
+    .map(([name]) => {
+      const parsedName = parseSqlIdentifier(name, 'column name');
+      return `"${parsedName}Z" TIMESTAMPTZ DEFAULT NOW()`;
+    });
+
+  const columns = Object.entries(schema).map(([name, def]) => {
+    const parsedName = parseSqlIdentifier(name, 'column name');
+    const constraints = [];
+    if (def.primaryKey) constraints.push('PRIMARY KEY');
+    if (!def.nullable) constraints.push('NOT NULL');
+    return `"${parsedName}" ${mapToSqlType(def.type)} ${constraints.join(' ')}`;
+  });
+
+  const finalColumns = [...columns, ...timeZColumns].join(',\n');
+  // Sanitize schema name before using it in constraint names to ensure valid SQL identifiers
+  const parsedSchemaName = schemaName ? parseSqlIdentifier(schemaName, 'schema name') : '';
+  const constraintPrefix = parsedSchemaName ? `${parsedSchemaName}_` : '';
+  const quotedSchemaName = getSchemaName(schemaName);
+
+  const sql = `
+            CREATE TABLE IF NOT EXISTS ${getTableName({ indexName: tableName, schemaName: quotedSchemaName })} (
+              ${finalColumns}
+            );
+            ${
+              tableName === TABLE_WORKFLOW_SNAPSHOT
+                ? `
+            DO $$ BEGIN
+              IF NOT EXISTS (
+                SELECT 1 FROM pg_constraint WHERE conname = '${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key'
+              ) AND NOT EXISTS (
+                SELECT 1 FROM pg_indexes WHERE indexname = '${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key'
+              ) THEN
+                ALTER TABLE ${getTableName({ indexName: tableName, schemaName: quotedSchemaName })}
+                ADD CONSTRAINT ${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key
+                UNIQUE (workflow_name, run_id);
+              END IF;
+            END $$;
+            `
+                : ''
+            }
+          ${
+            tableName === TABLE_SPANS
+              ? `
+            DO $$ BEGIN
+              IF NOT EXISTS (
+                SELECT 1 FROM pg_constraint WHERE conname = '${constraintPrefix}mastra_ai_spans_traceid_spanid_pk'
+              ) THEN
+                ALTER TABLE ${getTableName({ indexName: tableName, schemaName: quotedSchemaName })}
+                ADD CONSTRAINT ${constraintPrefix}mastra_ai_spans_traceid_spanid_pk
+                PRIMARY KEY ("traceId", "spanId");
+              END IF;
+            END $$;
+            `
+              : ''
+          }
+          `;
+
+  return sql;
+}
+
+/**
+ * Exports the Mastra database schema as SQL DDL statements.
+ * Does not require a database connection.
+ */
+export function exportSchemas(schemaName?: string): string {
+  const statements: string[] = [];
+
+  // Add schema creation if needed
+  if (schemaName) {
+    const quotedSchemaName = getSchemaName(schemaName);
+    statements.push(`-- Create schema if it doesn't exist`);
+    statements.push(`CREATE SCHEMA IF NOT EXISTS ${quotedSchemaName};`);
+    statements.push('');
+  }
+
+  // Generate SQL for all tables
+  for (const [tableName, schema] of Object.entries(TABLE_SCHEMAS)) {
+    statements.push(`-- Table: ${tableName}`);
+    const sql = generateTableSQL({
+      tableName: tableName as TABLE_NAMES,
+      schema,
+      schemaName,
+    });
+    statements.push(sql.trim());
+    statements.push('');
+  }
+
+  return statements.join('\n');
+}
+
 /**
  * Internal config for PgDB - accepts already-resolved client
  */
@@ -310,17 +422,6 @@ export class PgDB extends MastraBase {
     await registryEntry!.promise;
   }
 
-  protected getSqlType(type: StorageColumn['type']): string {
-    switch (type) {
-      case 'uuid':
-        return 'UUID';
-      case 'boolean':
-        return 'BOOLEAN';
-      default:
-        return getSqlType(type);
-    }
-  }
-
   protected getDefaultValue(type: StorageColumn['type']): string {
     switch (type) {
       case 'timestamp':
@@ -404,66 +505,11 @@ export class PgDB extends MastraBase {
         .filter(([_, def]) => def.type === 'timestamp')
         .map(([name]) => name);
 
-      const timeZColumns = Object.entries(schema)
-        .filter(([_, def]) => def.type === 'timestamp')
-        .map(([name]) => {
-          const parsedName = parseSqlIdentifier(name, 'column name');
-          return `"${parsedName}Z" TIMESTAMPTZ DEFAULT NOW()`;
-        });
-
-      const columns = Object.entries(schema).map(([name, def]) => {
-        const parsedName = parseSqlIdentifier(name, 'column name');
-        const constraints = [];
-        if (def.primaryKey) constraints.push('PRIMARY KEY');
-        if (!def.nullable) constraints.push('NOT NULL');
-        return `"${parsedName}" ${this.getSqlType(def.type)} ${constraints.join(' ')}`;
-      });
-
       if (this.schemaName) {
         await this.setupSchema();
       }
 
-      const finalColumns = [...columns, ...timeZColumns].join(',\n');
-      const constraintPrefix = this.schemaName ? `${this.schemaName}_` : '';
-      const schemaName = getSchemaName(this.schemaName);
-
-      const sql = `
-            CREATE TABLE IF NOT EXISTS ${getTableName({ indexName: tableName, schemaName })} (
-              ${finalColumns}
-            );
-            ${
-              tableName === TABLE_WORKFLOW_SNAPSHOT
-                ? `
-            DO $$ BEGIN
-              IF NOT EXISTS (
-                SELECT 1 FROM pg_constraint WHERE conname = '${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key'
-              ) AND NOT EXISTS (
-                SELECT 1 FROM pg_indexes WHERE indexname = '${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key'
-              ) THEN
-                ALTER TABLE ${getTableName({ indexName: tableName, schemaName })}
-                ADD CONSTRAINT ${constraintPrefix}mastra_workflow_snapshot_workflow_name_run_id_key
-                UNIQUE (workflow_name, run_id);
-              END IF;
-            END $$;
-            `
-                : ''
-            }
-          ${
-            tableName === TABLE_SPANS
-              ? `
-            DO $$ BEGIN
-              IF NOT EXISTS (
-                SELECT 1 FROM pg_constraint WHERE conname = '${constraintPrefix}mastra_ai_spans_traceid_spanid_pk'
-              ) THEN
-                ALTER TABLE ${getTableName({ indexName: tableName, schemaName: getSchemaName(this.schemaName) })}
-                ADD CONSTRAINT ${constraintPrefix}mastra_ai_spans_traceid_spanid_pk
-                PRIMARY KEY ("traceId", "spanId");
-              END IF;
-            END $$;
-            `
-              : ''
-          }
-          `;
+      const sql = generateTableSQL({ tableName, schema, schemaName: this.schemaName });
 
       await this.client.none(sql);
 
@@ -547,7 +593,7 @@ export class PgDB extends MastraBase {
         const columnExists = await this.hasColumn(TABLE_SPANS, columnName);
         if (!columnExists) {
           const parsedColumnName = parseSqlIdentifier(columnName, 'column name');
-          const sqlType = this.getSqlType(columnDef.type);
+          const sqlType = mapToSqlType(columnDef.type);
           // Align with createTable: nullable columns omit NOT NULL, non-nullable columns include it
           const nullable = columnDef.nullable ? '' : 'NOT NULL';
           const defaultValue = !columnDef.nullable ? this.getDefaultValue(columnDef.type) : '';
@@ -612,7 +658,7 @@ export class PgDB extends MastraBase {
         if (schema[columnName]) {
           const columnDef = schema[columnName];
           const parsedColumnName = parseSqlIdentifier(columnName, 'column name');
-          const sqlType = this.getSqlType(columnDef.type);
+          const sqlType = mapToSqlType(columnDef.type);
           // Align with createTable: nullable columns omit NOT NULL, non-nullable columns include it
           const nullable = columnDef.nullable ? '' : 'NOT NULL';
           const defaultValue = !columnDef.nullable ? this.getDefaultValue(columnDef.type) : '';

stores/pg/src/storage/index.ts

@@ -24,6 +24,8 @@ const DEFAULT_MAX_CONNECTIONS = 20;
 /** Default idle timeout in milliseconds */
 const DEFAULT_IDLE_TIMEOUT_MS = 30000;
 
+export { exportSchemas } from './db';
+// Export domain classes for direct use with MastraStorage composition
 export { AgentsPG, MemoryPG, ObservabilityPG, ScoresPG, WorkflowsPG };
 export { PoolAdapter } from './client';
 export type { DbClient, TxClient, QueryValues, Pool, PoolClient, QueryResult } from './client';

stores/pg/src/storage/test-utils.ts

@@ -5,7 +5,7 @@ import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from
 import type { PostgresStoreConfig } from '../shared/config';
 import { PgDB } from './db';
 import { MemoryPG } from './domains/memory';
-import { PostgresStore } from '.';
+import { exportSchemas, PostgresStore } from '.';
 
 export const TEST_CONFIG: PostgresStoreConfig = {
   id: 'test-postgres-store',
@@ -661,5 +661,60 @@ export function pgTests() {
         }
       });
     });
+
+    describe('Schema Export', () => {
+      it('should export schema for public schema', () => {
+        const schema = exportSchemas();
+
+        expect(schema).toContain('CREATE TABLE IF NOT EXISTS');
+        expect(schema).toContain('mastra_threads');
+        expect(schema).toContain('mastra_messages');
+        expect(schema).toContain('mastra_workflow_snapshot');
+        expect(schema).toContain('mastra_scorers');
+        expect(schema).toContain('mastra_ai_spans');
+        expect(schema).toContain('mastra_traces');
+        expect(schema).toContain('mastra_resources');
+        expect(schema).toContain('mastra_agents');
+      });
+
+      it('should export schema with custom schema name', () => {
+        const schema = exportSchemas('my_custom_schema');
+
+        expect(schema).toContain('CREATE SCHEMA IF NOT EXISTS "my_custom_schema"');
+        expect(schema).toContain('"my_custom_schema"."mastra_threads"');
+        expect(schema).toContain('"my_custom_schema"."mastra_messages"');
+
+        // Verify constraint names include the schema prefix
+        expect(schema).toContain('my_custom_schema_mastra_workflow_snapshot_workflow_name_run_id_key');
+        expect(schema).toContain('my_custom_schema_mastra_ai_spans_traceid_spanid_pk');
+      });
+
+      it('should generate SQL with correct constraints', () => {
+        const schema = exportSchemas();
+
+        expect(schema).toContain('createdAtZ" TIMESTAMPTZ DEFAULT NOW()');
+        expect(schema).toContain('updatedAtZ" TIMESTAMPTZ DEFAULT NOW()');
+        expect(schema).toContain('mastra_workflow_snapshot_workflow_name_run_id_key');
+        expect(schema).toContain('UNIQUE (workflow_name, run_id)');
+        expect(schema).toContain('mastra_ai_spans_traceid_spanid_pk');
+        expect(schema).toContain('PRIMARY KEY ("traceId", "spanId")');
+      });
+
+      it('should reject invalid schema names', () => {
+        // Schema names with special characters should throw an error
+        expect(() => exportSchemas('my-schema')).toThrow('Invalid schema name');
+        expect(() => exportSchemas('123schema')).toThrow('Invalid schema name');
+        expect(() => exportSchemas('schema with spaces')).toThrow('Invalid schema name');
+      });
+
+      it('should accept valid schema names with underscores', () => {
+        const schema = exportSchemas('my_schema');
+
+        // Valid schema name should work
+        expect(schema).toContain('"my_schema"."mastra_threads"');
+        expect(schema).toContain('my_schema_mastra_workflow_snapshot_workflow_name_run_id_key');
+        expect(schema).toContain('my_schema_mastra_ai_spans_traceid_spanid_pk');
+      });
+    });
   });
 }