Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

feat: add ListSQLSchemas to support lazy schema fetching in datasource panel (#8824)

mauro-cerzosimo89192e744312
diff --git a/frontend/src/__mocks__/requests.ts b/frontend/src/__mocks__/requests.ts
index 86fdb99949..085d0896a9 100644
--- a/frontend/src/__mocks__/requests.ts
+++ b/frontend/src/__mocks__/requests.ts
@@ -40,6 +40,7 @@ export const MockRequestClient = {
previewDatasetColumn: vi.fn().mockResolvedValue({}),
previewSQLTable: vi.fn().mockResolvedValue({}),
previewSQLTableList: vi.fn().mockResolvedValue({ tables: [] }),
+ previewSQLSchemaList: vi.fn().mockResolvedValue({ schemas: [] }),
previewDataSourceConnection: vi.fn().mockResolvedValue({}),
validateSQL: vi.fn().mockResolvedValue({}),
openFile: vi.fn().mockResolvedValue({}),
diff --git a/frontend/src/components/datasources/datasources.tsx b/frontend/src/components/datasources/datasources.tsx
index a62a22c410..32a3287b5c 100644
--- a/frontend/src/components/datasources/datasources.tsx
+++ b/frontend/src/components/datasources/datasources.tsx
@@ -28,6 +28,7 @@ import {
INTERNAL_SQL_ENGINES,
} from "@/core/datasets/engines";
import {
+ PreviewSQLSchemaList,
PreviewSQLTable,
PreviewSQLTableList,
} from "@/core/datasets/request-registry";
@@ -80,6 +81,7 @@ const INDENT = {
database: "pl-4",
schemaEmpty: "pl-8",
schema: "pl-7",
+ schemaLoading: "pl-8",
tableLoading: "pl-11",
tableSchemaless: "pl-8",
tableWithSchema: "pl-12",
@@ -369,6 +371,49 @@ const SchemaList: React.FC<{
hasSearch,
searchValue,
}) => {
+ const { addSchemaList } = useDataSourceActions();
+ const [schemasRequested, setSchemasRequested] = React.useState(false);
+
+ // Custom loading state, we need to wait for the data to propagate once requested
+ // useAsyncData's loading state may return false before data has propagated
+ const [schemasLoading, setSchemasLoading] = React.useState(false);
+
+ const { isPending, error } = useAsyncData(async () => {
+ if (schemas.length === 0 && engineName && !schemasRequested) {
+ setSchemasRequested(true);
+ setSchemasLoading(true);
+ try {
+ const previewSchemaList = await PreviewSQLSchemaList.request({
+ engine: engineName,
+ database: databaseName,
+ });
+
+ addSchemaList({
+ schemas: previewSchemaList.schemas ?? [],
+ sqlSchemaContext: {
+ engine: engineName,
+ database: databaseName,
+ },
+ });
+ } finally {
+ setSchemasLoading(false);
+ }
+ }
+ }, [schemas.length, engineName, databaseName, schemasRequested]);
+
+ if (isPending || schemasLoading) {
+ return (
+ <LoadingState
+ message="Loading schemas..."
+ className={INDENT.schemaLoading}
+ />
+ );
+ }
+
+ if (error) {
+ return <ErrorState error={error} className={INDENT.schemaLoading} />;
+ }
+
if (schemas.length === 0) {
return (
<EmptyState
diff --git a/frontend/src/core/datasets/__tests__/data-source.test.ts b/frontend/src/core/datasets/__tests__/data-source.test.ts
index 87b2aaff92..2d72df354d 100644
--- a/frontend/src/core/datasets/__tests__/data-source.test.ts
+++ b/frontend/src/core/datasets/__tests__/data-source.test.ts
@@ -1,7 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { beforeEach, describe, expect, it } from "vitest";
import { variableName } from "@/__tests__/branded";
-import type { DataTable } from "@/core/kernel/messages";
+import type { DatabaseSchema, DataTable } from "@/core/kernel/messages";
import type { VariableName } from "@/core/variables/types";
import {
type DataSourceConnection,
@@ -209,6 +209,93 @@ describe("filtering data sources", () => {
});
});
+describe("add schema list", () => {
+ const connections: DataSourceConnection[] = [
+ {
+ name: "conn1" as ConnectionName,
+ source: "sqlite",
+ display_name: "SQLite DB",
+ dialect: "sqlite",
+ databases: [
+ {
+ name: "db1",
+ schemas: [],
+ dialect: "sqlite",
+ },
+ ],
+ },
+ ];
+
+ // Helper function to add schema list
+ const addSchemaList = (
+ schemas: DatabaseSchema[],
+ engine: string,
+ database: string,
+ ) => {
+ return reducer(baseState, {
+ type: "addSchemaList",
+ payload: {
+ schemas,
+ sqlSchemaContext: { engine, database },
+ },
+ });
+ };
+
+ let baseState: DataSourceState;
+
+ beforeEach(() => {
+ baseState = addConnection(connections, baseState);
+ expect(baseState.connectionsMap.size).toBe(defaultConnSize + 1);
+ });
+
+ it("adds schema list to a specific database", () => {
+ const schemaList: DatabaseSchema[] = [
+ { name: "public", tables: [] },
+ { name: "analytics", tables: [] },
+ ];
+ const newState = addSchemaList(schemaList, "conn1", "db1");
+
+ const conn1 = newState.connectionsMap.get("conn1" as ConnectionName);
+ const db1 = conn1?.databases.find((db) => db.name === "db1");
+ expect(db1?.schemas).toEqual(schemaList);
+ });
+
+ it("updates schema list for a database", () => {
+ const schemaList: DatabaseSchema[] = [
+ { name: "public", tables: [] },
+ { name: "analytics", tables: [] },
+ ];
+ const newState = addSchemaList(schemaList, "conn1", "db1");
+
+ const conn1 = newState.connectionsMap.get("conn1" as ConnectionName);
+ const db1 = conn1?.databases.find((db) => db.name === "db1");
+ expect(db1?.schemas).toEqual(schemaList);
+
+ // update with new schema list
+ const newSchemaList: DatabaseSchema[] = [
+ { name: "public", tables: [] },
+ { name: "sales", tables: [] },
+ ];
+ const updatedState = addSchemaList(newSchemaList, "conn1", "db1");
+
+ const newConn = updatedState.connectionsMap.get("conn1" as ConnectionName);
+ const newDb1 = newConn?.databases.find((db) => db.name === "db1");
+ expect(newDb1?.schemas).toEqual(newSchemaList);
+ });
+
+ it("does not add schema list if database does not exist", () => {
+ const schemaList: DatabaseSchema[] = [
+ { name: "public", tables: [] },
+ { name: "analytics", tables: [] },
+ ];
+ const newState = addSchemaList(schemaList, "conn1", "non_existent_db");
+
+ const conn1 = newState.connectionsMap.get("conn1" as ConnectionName);
+ const db1 = conn1?.databases.find((db) => db.name === "db1");
+ expect(db1?.schemas.length).toBe(0);
+ });
+});
+
describe("add table list", () => {
const connections: DataSourceConnection[] = [
{
diff --git a/frontend/src/core/datasets/data-source-connections.ts b/frontend/src/core/datasets/data-source-connections.ts
index ebbace837e..23fe4540c9 100644
--- a/frontend/src/core/datasets/data-source-connections.ts
+++ b/frontend/src/core/datasets/data-source-connections.ts
@@ -5,6 +5,7 @@ import { isSchemaless } from "@/components/datasources/utils";
import { createReducerAndAtoms } from "@/utils/createReducer";
import { Logger } from "@/utils/Logger";
import type {
+ DatabaseSchema,
DataSourceConnection as DataSourceConnectionType,
DataTable,
} from "../kernel/messages";
@@ -43,6 +44,11 @@ export interface DataSourceState {
connectionsMap: ConnectionsMap;
}
+export interface SQLSchemaContext {
+ engine: string;
+ database: string;
+}
+
export interface SQLTableContext {
engine: string;
database: string;
@@ -134,6 +140,44 @@ const {
};
},
+ // Add schema list to a specific database in a connection
+ addSchemaList: (
+ state: DataSourceState,
+ opts: {
+ schemas: DatabaseSchema[];
+ sqlSchemaContext: SQLSchemaContext;
+ },
+ ): DataSourceState => {
+ const { schemas, sqlSchemaContext } = opts;
+ const { connectionsMap, latestEngineSelected } = state;
+ const connectionName = sqlSchemaContext.engine as ConnectionName;
+ const conn = connectionsMap.get(connectionName);
+
+ if (!conn) {
+ return state;
+ }
+
+ const newMap = new Map(connectionsMap);
+ const newConn: DataSourceConnection = {
+ ...conn,
+ databases: conn.databases.map((db) => {
+ if (db.name !== sqlSchemaContext.database) {
+ return db;
+ }
+ return {
+ ...db,
+ schemas: schemas,
+ };
+ }),
+ };
+ newMap.set(connectionName, newConn);
+
+ return {
+ latestEngineSelected: latestEngineSelected,
+ connectionsMap: newMap,
+ };
+ },
+
// Add table list to a specific schema in a connection
addTableList: (
state: DataSourceState,
diff --git a/frontend/src/core/datasets/request-registry.ts b/frontend/src/core/datasets/request-registry.ts
index 1df8aa78d2..938e3cb93f 100644
--- a/frontend/src/core/datasets/request-registry.ts
+++ b/frontend/src/core/datasets/request-registry.ts
@@ -1,5 +1,6 @@
/* Copyright 2026 Marimo. All rights reserved. */
import type {
+ SQLSchemaListPreview,
SQLTableListPreview,
SQLTablePreview,
ValidateSQLResult,
@@ -8,6 +9,7 @@ import { CachingRequestRegistry } from "../network/CachingRequestRegistry";
import { DeferredRequestRegistry } from "../network/DeferredRequestRegistry";
import { getRequestClient } from "../network/requests";
import type {
+ ListSQLSchemasRequest,
ListSQLTablesRequest,
PreviewSQLTableRequest,
ValidateSQLRequest,
@@ -28,6 +30,17 @@ export const PreviewSQLTable = new DeferredRequestRegistry<
});
});
+export const PreviewSQLSchemaList = new DeferredRequestRegistry<
+ Omit<ListSQLSchemasRequest, "requestId">,
+ SQLSchemaListPreview
+>("sql-schema-list-preview", async (requestId, req) => {
+ const client = getRequestClient();
+ await client.previewSQLSchemaList({
+ requestId: requestId,
+ ...req,
+ });
+});
+
export const PreviewSQLTableList = new DeferredRequestRegistry<
Omit<ListSQLTablesRequest, "requestId">,
SQLTableListPreview
diff --git a/frontend/src/core/islands/bridge.ts b/frontend/src/core/islands/bridge.ts
index b0038ee909..3334e1bf00 100644
--- a/frontend/src/core/islands/bridge.ts
+++ b/frontend/src/core/islands/bridge.ts
@@ -169,6 +169,7 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
previewDatasetColumn = throwNotImplemented;
previewSQLTable = throwNotImplemented;
previewSQLTableList = throwNotImplemented;
+ previewSQLSchemaList = throwNotImplemented;
previewDataSourceConnection = throwNotImplemented;
validateSQL = throwNotImplemented;
openFile = throwNotImplemented;
diff --git a/frontend/src/core/islands/main.ts b/frontend/src/core/islands/main.ts
index 2a5c43d154..57a375d888 100644
--- a/frontend/src/core/islands/main.ts
+++ b/frontend/src/core/islands/main.ts
@@ -121,6 +121,7 @@ export async function initialize() {
case "data-column-preview":
case "sql-table-preview":
case "sql-table-list-preview":
+ case "sql-schema-list-preview":
case "datasets":
case "data-source-connections":
case "validate-sql-result":
diff --git a/frontend/src/core/kernel/messages.ts b/frontend/src/core/kernel/messages.ts
index 6815ae7570..2e7a819dbc 100644
--- a/frontend/src/core/kernel/messages.ts
+++ b/frontend/src/core/kernel/messages.ts
@@ -41,6 +41,8 @@ export type DataColumnPreview = NotificationMessageData<"data-column-preview">;
export type SQLTablePreview = NotificationMessageData<"sql-table-preview">;
export type SQLTableListPreview =
NotificationMessageData<"sql-table-list-preview">;
+export type SQLSchemaListPreview =
+ NotificationMessageData<"sql-schema-list-preview">;
export type ValidateSQLResult = NotificationMessageData<"validate-sql-result">;
export type SecretKeysResult = NotificationMessageData<"secret-keys-result">;
export type StartupLogs = NotificationMessageData<"startup-logs">;
diff --git a/frontend/src/core/network/requests-lazy.ts b/frontend/src/core/network/requests-lazy.ts
index 39b85ccc73..199825fb34 100644
--- a/frontend/src/core/network/requests-lazy.ts
+++ b/frontend/src/core/network/requests-lazy.ts
@@ -112,6 +112,7 @@ const ACTIONS: Record<keyof AllRequests, Action> = {
previewDatasetColumn: "waitForConnectionOpen",
previewSQLTable: "waitForConnectionOpen",
previewSQLTableList: "waitForConnectionOpen",
+ previewSQLSchemaList: "waitForConnectionOpen",
previewDataSourceConnection: "waitForConnectionOpen",
validateSQL: "waitForConnectionOpen",
listStorageEntries: "waitForConnectionOpen",
diff --git a/frontend/src/core/network/requests-network.ts b/frontend/src/core/network/requests-network.ts
index 139866cfbe..9b730c83d4 100644
--- a/frontend/src/core/network/requests-network.ts
+++ b/frontend/src/core/network/requests-network.ts
@@ -244,6 +244,14 @@ export function createNetworkRequests(): EditRequests & RunRequests {
})
.then(handleResponseReturnNull);
},
+ previewSQLSchemaList: (request) => {
+ return getClient()
+ .POST("/api/datasources/preview_sql_schema_list", {
+ body: request,
+ params: getParams(),
+ })
+ .then(handleResponseReturnNull);
+ },
previewDataSourceConnection: (request) => {
return getClient()
.POST("/api/datasources/preview_datasource_connection", {
diff --git a/frontend/src/core/network/requests-static.ts b/frontend/src/core/network/requests-static.ts
index bc56bfea6e..aa16a683d8 100644
--- a/frontend/src/core/network/requests-static.ts
+++ b/frontend/src/core/network/requests-static.ts
@@ -57,6 +57,7 @@ export function createStaticRequests(): EditRequests & RunRequests {
previewDatasetColumn: throwNotInEditMode,
previewSQLTable: throwNotInEditMode,
previewSQLTableList: throwNotInEditMode,
+ previewSQLSchemaList: throwNotInEditMode,
previewDataSourceConnection: throwNotInEditMode,
validateSQL: throwNotInEditMode,
openFile: throwNotInEditMode,
diff --git a/frontend/src/core/network/requests-toasting.tsx b/frontend/src/core/network/requests-toasting.tsx
index d7e0059ab6..7df0cb1875 100644
--- a/frontend/src/core/network/requests-toasting.tsx
+++ b/frontend/src/core/network/requests-toasting.tsx
@@ -42,6 +42,7 @@ export function createErrorToastingRequests(
previewDatasetColumn: "Failed to fetch data sources",
previewSQLTable: "Failed to fetch SQL table",
previewSQLTableList: "Failed to fetch SQL table list",
+ previewSQLSchemaList: "Failed to fetch SQL schema list",
previewDataSourceConnection: "Failed to preview data source connection",
validateSQL: "Failed to validate SQL",
openFile: "Failed to open file",
diff --git a/frontend/src/core/network/types.ts b/frontend/src/core/network/types.ts
index 226c53ed63..50f5eac892 100644
--- a/frontend/src/core/network/types.ts
+++ b/frontend/src/core/network/types.ts
@@ -59,6 +59,7 @@ export type PreviewDatasetColumnRequest =
schemas["PreviewDatasetColumnRequest"];
export type PreviewSQLTableRequest = schemas["PreviewSQLTableRequest"];
export type ListSQLTablesRequest = schemas["ListSQLTablesRequest"];
+export type ListSQLSchemasRequest = schemas["ListSQLSchemasRequest"];
export type ListDataSourceConnectionRequest =
schemas["ListDataSourceConnectionRequest"];
export type ValidateSQLRequest = schemas["ValidateSQLRequest"];
@@ -151,6 +152,7 @@ export interface EditRequests {
previewDatasetColumn: (request: PreviewDatasetColumnRequest) => Promise<null>;
previewSQLTable: (request: PreviewSQLTableRequest) => Promise<null>;
previewSQLTableList: (request: ListSQLTablesRequest) => Promise<null>;
+ previewSQLSchemaList: (request: ListSQLSchemasRequest) => Promise<null>;
previewDataSourceConnection: (
request: ListDataSourceConnectionRequest,
) => Promise<null>;
diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.ts
index f976da8707..7334ab8df5 100644
--- a/frontend/src/core/wasm/bridge.ts
+++ b/frontend/src/core/wasm/bridge.ts
@@ -523,6 +523,16 @@ export class PyodideBridge implements RunRequests, EditRequests {
return null;
};
+ previewSQLSchemaList: EditRequests["previewSQLSchemaList"] = async (
+ request,
+ ) => {
+ await this.putControlRequest({
+ type: "list-sql-schemas",
+ ...request,
+ });
+ return null;
+ };
+
previewDataSourceConnection: EditRequests["previewDataSourceConnection"] =
async (request) => {
await this.putControlRequest({
diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
index 2a110a6d4f..d59c7953bb 100644
--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx
+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
@@ -37,6 +37,7 @@ import { useSetAppConfig } from "../config/config";
import { useDataSourceActions } from "../datasets/data-source-connections";
import type { ConnectionName } from "../datasets/engines";
import {
+ PreviewSQLSchemaList,
PreviewSQLTable,
PreviewSQLTableList,
ValidateSQL,
@@ -288,6 +289,9 @@ export function useMarimoKernelConnection(opts: {
case "sql-table-list-preview":
PreviewSQLTableList.resolve(msg.data.request_id, msg.data);
return;
+ case "sql-schema-list-preview":
+ PreviewSQLSchemaList.resolve(msg.data.request_id, msg.data);
+ return;
case "validate-sql-result":
ValidateSQL.resolve(msg.data.request_id as RequestId, msg.data);
return;
diff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.py
index 2d1928d655..b56a69f7d7 100644
--- a/marimo/_cli/development/commands.py
+++ b/marimo/_cli/development/commands.py
@@ -301,6 +301,7 @@ def _generate_server_api_schema() -> dict[str, Any]:
notifications.DataColumnPreviewNotification,
notifications.SQLTablePreviewNotification,
notifications.SQLTableListPreviewNotification,
+ notifications.SQLSchemaListPreviewNotification,
notifications.DataSourceConnectionsNotification,
notifications.StorageNamespacesNotification,
notifications.SecretKeysResultNotification,
@@ -388,6 +389,7 @@ def _generate_server_api_schema() -> dict[str, Any]:
commands.ListDataSourceConnectionCommand,
commands.ListSecretKeysCommand,
commands.ListSQLTablesCommand,
+ commands.ListSQLSchemasCommand,
commands.ModelMessage,
commands.PreviewDatasetColumnCommand,
commands.PreviewSQLTableCommand,
@@ -415,6 +417,7 @@ def _generate_server_api_schema() -> dict[str, Any]:
models.ListDataSourceConnectionRequest,
models.ListSecretKeysRequest,
models.ListSQLTablesRequest,
+ models.ListSQLSchemasRequest,
models.MCPRefreshResponse,
models.MCPStatusResponse,
models.PreviewDatasetColumnRequest,
diff --git a/marimo/_internal/commands.py b/marimo/_internal/commands.py
index 7baab429ff..4b4ad79408 100644
--- a/marimo/_internal/commands.py
+++ b/marimo/_internal/commands.py
@@ -21,6 +21,7 @@ from marimo._runtime.commands import (
ListDataSourceConnectionCommand,
ListOrValue,
ListSecretKeysCommand,
+ ListSQLSchemasCommand,
ListSQLTablesCommand,
ModelCommand,
ModelMessage,
@@ -60,6 +61,7 @@ __all__ = [
"ListDataSourceConnectionCommand",
"ListOrValue",
"ListSQLTablesCommand",
+ "ListSQLSchemasCommand",
"ListSecretKeysCommand",
"ModelMessage",
"PreviewDatasetColumnCommand",
diff --git a/marimo/_internal/notifications.py b/marimo/_internal/notifications.py
index 1ddb49ff07..b4b5d4b694 100644
--- a/marimo/_internal/notifications.py
+++ b/marimo/_internal/notifications.py
@@ -34,6 +34,7 @@ from marimo._messaging.notification import (
RemoveUIElementsNotification,
SecretKeysResultNotification,
SQLMetadata,
+ SQLSchemaListPreviewNotification,
SQLTableListPreviewNotification,
SQLTablePreviewNotification,
StartupLogsNotification,
@@ -81,6 +82,7 @@ __all__ = [
"SQLMetadata",
"SQLTableListPreviewNotification",
"SQLTablePreviewNotification",
+ "SQLSchemaListPreviewNotification",
"SecretKeysResultNotification",
"StartupLogsNotification",
"UIElementMessageNotification",
diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.py
index 97e1b8779f..6aa076b41d 100644
--- a/marimo/_messaging/notification.py
+++ b/marimo/_messaging/notification.py
@@ -26,6 +26,7 @@ from marimo._data.models import (
DataSourceConnection,
DataTable,
DataTableSource,
+ Schema,
)
from marimo._dependencies.dependencies import DependencyManager
from marimo._messaging.cell_output import CellOutput
@@ -488,6 +489,18 @@ class DatasetsNotification(Notification, tag="datasets"):
clear_channel: Optional[DataTableSource] = None
+class SQLDatabaseMetadata(msgspec.Struct):
+ """SQL database metadata.
+
+ Attributes:
+ connection: Connection identifier.
+ database: Database name.
+ """
+
+ connection: str
+ database: str
+
+
class SQLMetadata(msgspec.Struct, tag="sql-metadata"):
"""SQL database and schema metadata.
@@ -573,6 +586,25 @@ class DataColumnPreviewNotification(
column_name: str
+class SQLSchemaListPreviewNotification(
+ Notification, tag="sql-schema-list-preview"
+):
+ """List of SQL schemas in a database.
+
+ Attributes:
+ request_id: Request ID this responds to.
+ metadata: Database and schema metadata.
+ schemas: Schemas in database.
+ error: Error message if failed.
+ """
+
+ name: ClassVar[str] = "sql-schema-list-preview"
+ request_id: RequestId
+ metadata: SQLDatabaseMetadata
+ schemas: list[Schema] = msgspec.field(default_factory=list)
+ error: Optional[str] = None
+
+
class DataSourceConnectionsNotification(
Notification, tag="data-source-connections"
):
@@ -834,6 +866,7 @@ NotificationMessage = Union[
DataColumnPreviewNotification,
SQLTablePreviewNotification,
SQLTableListPreviewNotification,
+ SQLSchemaListPreviewNotification,
DataSourceConnectionsNotification,
ValidateSQLResultNotification,
# Storage
diff --git a/marimo/_runtime/commands.py b/marimo/_runtime/commands.py
index 5db2cad6ff..e2c9efdcf5 100644
--- a/marimo/_runtime/commands.py
+++ b/marimo/_runtime/commands.py
@@ -650,6 +650,23 @@ class ListSQLTablesCommand(Command):
schema: str
+class ListSQLSchemasCommand(Command):
+ """List schemas in an SQL database.
+
+ Retrieves names of all schemas in a database. Used by the SQL editor for
+ schema selection.
+
+ Attributes:
+ request_id: Unique identifier for this request.
+ engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).
+ database: Database to query.
+ """
+
+ request_id: RequestId
+ engine: str
+ database: str
+
+
class ListDataSourceConnectionCommand(Command):
"""List data source schemas.
@@ -864,6 +881,7 @@ CommandMessage = Union[
PreviewDatasetColumnCommand,
PreviewSQLTableCommand,
ListSQLTablesCommand,
+ ListSQLSchemasCommand,
ValidateSQLCommand,
ListDataSourceConnectionCommand,
# Storage operations
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index 96744d07c7..4ea3efce22 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -80,7 +80,9 @@ from marimo._messaging.notification import (
PackageStatusType,
RemoveUIElementsNotification,
SecretKeysResultNotification,
+ SQLDatabaseMetadata,
SQLMetadata,
+ SQLSchemaListPreviewNotification,
SQLTableListPreviewNotification,
SQLTablePreviewNotification,
StorageDownloadReadyNotification,
@@ -137,6 +139,7 @@ from marimo._runtime.commands import (
InvokeFunctionCommand,
ListDataSourceConnectionCommand,
ListSecretKeysCommand,
+ ListSQLSchemasCommand,
ListSQLTablesCommand,
ModelCommand,
PreviewDatasetColumnCommand,
@@ -2405,6 +2408,10 @@ class Kernel:
ListSQLTablesCommand,
self.datasets_callbacks.preview_sql_table_list,
)
+ handler.register(
+ ListSQLSchemasCommand,
+ self.datasets_callbacks.preview_sql_schema_list,
+ )
handler.register(
ListDataSourceConnectionCommand,
self.datasets_callbacks.preview_datasource_connection,
@@ -2696,6 +2703,62 @@ class DatasetCallbacks:
),
)
+ @kernel_tracer.start_as_current_span("preview_sql_schema_list")
+ async def preview_sql_schema_list(
+ self, request: ListSQLSchemasCommand
+ ) -> None:
+ """Get a list of schemas from an SQL database
+
+ Args:
+ request (ListSQLSchemasCommand): The request containing:
+ - engine: Name of the SQL engine / connection
+ - database: Name of the database
+ """
+ variable_name = cast(VariableName, request.engine)
+ database_name = request.database
+ sql_db_metadata = SQLDatabaseMetadata(
+ connection=variable_name,
+ database=database_name,
+ )
+
+ engine, error = self.get_engine_catalog(variable_name)
+ if error is not None or engine is None:
+ broadcast_notification(
+ SQLSchemaListPreviewNotification(
+ request_id=request.request_id,
+ schemas=[],
+ error=error,
+ metadata=sql_db_metadata,
+ ),
+ )
+ return
+
+ try:
+ schema_list = engine.get_schemas(
+ database=database_name,
+ include_tables=False,
+ include_table_details=False,
+ )
+ broadcast_notification(
+ SQLSchemaListPreviewNotification(
+ request_id=request.request_id,
+ schemas=schema_list,
+ metadata=sql_db_metadata,
+ ),
+ )
+ except Exception as e:
+ LOGGER.exception(
+ "Failed to get schema list for database %s", database_name
+ )
+ broadcast_notification(
+ SQLSchemaListPreviewNotification(
+ request_id=request.request_id,
+ schemas=[],
+ error="Failed to get schema list: " + str(e),
+ metadata=sql_db_metadata,
+ ),
+ )
+
@kernel_tracer.start_as_current_span("preview_datasource_connection")
async def preview_datasource_connection(
self, request: ListDataSourceConnectionCommand
diff --git a/marimo/_schemas/generated/notifications.yaml b/marimo/_schemas/generated/notifications.yaml
index a7649e0257..5f56ede95e 100644
--- a/marimo/_schemas/generated/notifications.yaml
+++ b/marimo/_schemas/generated/notifications.yaml
@@ -1138,6 +1138,18 @@ components:
- cell_id
title: RemoveUIElementsNotification
type: object
+ SQLDatabaseMetadata:
+ description: Metadata for a SQL database, including its dialect and name.
+ properties:
+ connection:
+ type: string
+ database:
+ type: string
+ required:
+ - connection
+ - database
+ title: SQLDatabaseMetadata
+ type: object
SQLMetadata:
description: Metadata for a SQL database.
properties:
@@ -1157,6 +1169,32 @@ components:
- schema
title: SQLMetadata
type: object
+ SQLSchemaListPreviewNotification:
+ description: Preview of a list of schemas in a database.
+ properties:
+ error:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
+ metadata:
+ $ref: '#/components/schemas/SQLDatabaseMetadata'
+ op:
+ enum:
+ - sql-schema-list-preview
+ request_id:
+ type: string
+ schemas:
+ default: []
+ items:
+ $ref: '#/components/schemas/Schema'
+ type: array
+ required:
+ - op
+ - request_id
+ - metadata
+ title: SQLSchemaListPreviewNotification
+ type: object
SQLTableListPreviewNotification:
description: Preview of a list of tables in a schema.
properties:
diff --git a/marimo/_server/api/endpoints/datasources.py b/marimo/_server/api/endpoints/datasources.py
index b781896d97..1136b0b192 100644
--- a/marimo/_server/api/endpoints/datasources.py
+++ b/marimo/_server/api/endpoints/datasources.py
@@ -10,6 +10,7 @@ from marimo._server.api.utils import dispatch_control_request
from marimo._server.models.models import (
BaseResponse,
ListDataSourceConnectionRequest,
+ ListSQLSchemasRequest,
ListSQLTablesRequest,
PreviewDatasetColumnRequest,
PreviewSQLTableRequest,
@@ -105,6 +106,32 @@ async def preview_sql_table_list(request: Request) -> BaseResponse:
return await dispatch_control_request(request, ListSQLTablesRequest)
[email protected]("/preview_sql_schema_list")
+@requires("edit")
+async def preview_sql_schema_list(request: Request) -> BaseResponse:
+ """
+ parameters:
+ - in: header
+ name: Marimo-Session-Id
+ schema:
+ type: string
+ required: true
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ListSQLSchemasRequest"
+ responses:
+ 200:
+ description: Preview a list of schemas in an SQL database
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SuccessResponse"
+ """
+ return await dispatch_control_request(request, ListSQLSchemasRequest)
+
+
@router.post("/preview_datasource_connection")
@requires("edit")
async def preview_datasource_connection(request: Request) -> BaseResponse:
diff --git a/marimo/_server/models/models.py b/marimo/_server/models/models.py
index f592de5a9a..3dc10f9191 100644
--- a/marimo/_server/models/models.py
+++ b/marimo/_server/models/models.py
@@ -20,6 +20,7 @@ from marimo._runtime.commands import (
InvokeFunctionCommand,
ListDataSourceConnectionCommand,
ListSecretKeysCommand,
+ ListSQLSchemasCommand,
ListSQLTablesCommand,
ModelCommand,
PreviewDatasetColumnCommand,
@@ -105,6 +106,15 @@ class ListSQLTablesRequest(ListSQLTablesCommand, tag=False):
)
+class ListSQLSchemasRequest(ListSQLSchemasCommand, tag=False):
+ def as_command(self) -> ListSQLSchemasCommand:
+ return ListSQLSchemasCommand(
+ request_id=self.request_id,
+ engine=self.engine,
+ database=self.database,
+ )
+
+
class PreviewDatasetColumnRequest(PreviewDatasetColumnCommand, tag=False):
def as_command(self) -> PreviewDatasetColumnCommand:
return PreviewDatasetColumnCommand(
diff --git a/marimo/_session/state/session_view.py b/marimo/_session/state/session_view.py
index 7a1608aed5..27dd0d5a68 100644
--- a/marimo/_session/state/session_view.py
+++ b/marimo/_session/state/session_view.py
@@ -20,6 +20,7 @@ from marimo._messaging.notification import (
ModelOpen,
ModelUpdate,
NotificationMessage,
+ SQLSchemaListPreviewNotification,
SQLTableListPreviewNotification,
SQLTablePreviewNotification,
StartupLogsNotification,
@@ -42,6 +43,7 @@ from marimo._runtime.commands import (
UpdateUIElementCommand,
)
from marimo._sql.connection_utils import (
+ update_schema_list_in_connection,
update_table_in_connection,
update_table_list_in_connection,
)
@@ -367,6 +369,17 @@ class SessionView:
sql_table_preview.table,
)
+ elif isinstance(notification, SQLSchemaListPreviewNotification):
+ sql_schema_list_preview = notification
+ sql_db_metadata = sql_schema_list_preview.metadata
+ schema_list_connections = self.data_connectors.connections
+ if sql_schema_list_preview.schemas is not None:
+ update_schema_list_in_connection(
+ schema_list_connections,
+ sql_db_metadata,
+ sql_schema_list_preview.schemas,
+ )
+
elif isinstance(notification, SQLTableListPreviewNotification):
sql_table_list_preview = notification
sql_metadata = sql_table_list_preview.metadata
diff --git a/marimo/_sql/connection_utils.py b/marimo/_sql/connection_utils.py
index 28ba047652..3e16a149ca 100644
--- a/marimo/_sql/connection_utils.py
+++ b/marimo/_sql/connection_utils.py
@@ -1,8 +1,8 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from marimo._data.models import DataSourceConnection, DataTable
-from marimo._messaging.notification import SQLMetadata
+from marimo._data.models import DataSourceConnection, DataTable, Schema
+from marimo._messaging.notification import SQLDatabaseMetadata, SQLMetadata
def update_table_in_connection(
@@ -35,6 +35,30 @@ def update_table_in_connection(
return
+def update_schema_list_in_connection(
+ connections: list[DataSourceConnection],
+ sql_db_metadata: SQLDatabaseMetadata,
+ updated_schema_list: list[Schema],
+) -> None:
+ """Update a list of schemas in the connection hierarchy, updates in-place.
+
+ Args:
+ connections: List of data source connections
+ sql_db_metadata: SQL database metadata containing connection, database info
+ updated_schema_list: The updated list of schemas to replace the existing ones
+ """
+ for connection in connections:
+ if connection.name != sql_db_metadata.connection:
+ continue
+
+ for database in connection.databases:
+ if database.name != sql_db_metadata.database:
+ continue
+
+ database.schemas = updated_schema_list
+ return
+
+
def update_table_list_in_connection(
connections: list[DataSourceConnection],
sql_metadata: SQLMetadata,
diff --git a/marimo/_sql/engines/adbc.py b/marimo/_sql/engines/adbc.py
index b94b22b6d2..9261b08b43 100644
--- a/marimo/_sql/engines/adbc.py
+++ b/marimo/_sql/engines/adbc.py
@@ -463,6 +463,19 @@ class AdbcDBAPIEngine(SQLConnection[AdbcDbApiConnection]):
def get_default_schema(self) -> Optional[str]:
return self._catalog.get_default_schema()
+ # TODO: The following methods are currently not implemented.
+ # We should consider implementing these in the future for better performance when users don't want to fetch everything.
+ def get_schemas(
+ self,
+ *,
+ database: Optional[str],
+ include_tables: bool,
+ include_table_details: bool,
+ ) -> list[Schema]:
+ """Get all schemas and optionally their tables. Keys are schema names."""
+ _, _, _ = database, include_tables, include_table_details
+ return []
+
def get_databases(
self,
*,
diff --git a/marimo/_sql/engines/clickhouse.py b/marimo/_sql/engines/clickhouse.py
index 007b5fd556..179e41640f 100644
--- a/marimo/_sql/engines/clickhouse.py
+++ b/marimo/_sql/engines/clickhouse.py
@@ -138,6 +138,19 @@ class ClickhouseEmbedded(SQLConnection[Optional["ChdbConnection"]]):
to_pandas=convert_to_pandas,
)
+ # TODO: The following methods are currently not implemented.
+ # We should consider implementing these in the future for better performance when users don't want to fetch everything.
+ def get_schemas(
+ self,
+ *,
+ database: Optional[str],
+ include_tables: bool,
+ include_table_details: bool,
+ ) -> list[Schema]:
+ """Get all schemas and optionally their tables. Keys are schema names."""
+ _, _, _ = database, include_tables, include_table_details
+ return []
+
# TODO: Implement the following functionalities
def get_databases(
self,
@@ -259,6 +272,19 @@ class ClickhouseServer(SQLConnection[Optional["ClickhouseClient"]]):
auto_discover_columns="auto",
)
+ # TODO: The following methods are currently not implemented.
+ # We should consider implementing these in the future for better performance when users don't want to fetch everything.
+ def get_schemas(
+ self,
+ *,
+ database: Optional[str],
+ include_tables: bool,
+ include_table_details: bool,
+ ) -> list[Schema]:
+ """Get all schemas and optionally their tables. Keys are schema names."""
+ _, _, _ = database, include_tables, include_table_details
+ return []
+
def get_databases(
self,
*,
diff --git a/marimo/_sql/engines/duckdb.py b/marimo/_sql/engines/duckdb.py
index 4df949bfd3..789212e944 100644
--- a/marimo/_sql/engines/duckdb.py
+++ b/marimo/_sql/engines/duckdb.py
@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Any, Literal, Optional, Union, cast
from marimo import _loggers
from marimo._data.get_datasets import get_databases_from_duckdb
-from marimo._data.models import Database, DataTable
+from marimo._data.models import Database, DataTable, Schema
from marimo._dependencies.dependencies import DependencyManager
from marimo._runtime.context.types import (
ContextNotInitializedError,
@@ -157,6 +157,19 @@ class DuckDBEngine(SQLConnection[Optional["duckdb.DuckDBPyConnection"]]):
with self._install_connection(connection):
return get_databases_from_duckdb(connection, self._engine_name)
+ # TODO: The following methods are currently not implemented.
+ # We should consider implementing these in the future for better performance when users don't want to fetch everything.
+ def get_schemas(
+ self,
+ *,
+ database: Optional[str],
+ include_tables: bool,
+ include_table_details: bool,
+ ) -> list[Schema]:
+ """Get all schemas and optionally their tables. Keys are schema names."""
+ _, _, _ = database, include_tables, include_table_details
+ return []
+
def get_tables_in_schema(
self, *, schema: str, database: str, include_table_details: bool
) -> list[DataTable]:
diff --git a/marimo/_sql/engines/ibis.py b/marimo/_sql/engines/ibis.py
index 1ac9b94595..80685b240f 100644
--- a/marimo/_sql/engines/ibis.py
+++ b/marimo/_sql/engines/ibis.py
@@ -167,7 +167,7 @@ class IbisEngine(SQLConnection["SQLBackend"]):
for database_name in database_names:
database_name_str = str(database_name)
if self._resolve_should_auto_discover(include_schemas):
- schemas = self._get_schemas(
+ schemas = self.get_schemas(
database=database_name_str,
include_tables=self._resolve_should_auto_discover(
include_tables
@@ -190,7 +190,7 @@ class IbisEngine(SQLConnection["SQLBackend"]):
return databases
- def _get_schemas(
+ def get_schemas(
self,
*,
database: Optional[str],
diff --git a/marimo/_sql/engines/pyiceberg.py b/marimo/_sql/engines/pyiceberg.py
index f4df867624..8dac4e532e 100644
--- a/marimo/_sql/engines/pyiceberg.py
+++ b/marimo/_sql/engines/pyiceberg.py
@@ -66,6 +66,19 @@ class PyIcebergEngine(EngineCatalog["Catalog"]):
def get_default_schema(self) -> Optional[str]:
return None # Iceberg doesn't have schemas in the traditional sense
+ # TODO: The following methods are currently not implemented.
+ # We should consider implementing these in the future for better performance when users don't want to fetch everything.
+ def get_schemas(
+ self,
+ *,
+ database: Optional[str],
+ include_tables: bool,
+ include_table_details: bool,
+ ) -> list[Schema]:
+ """Get all schemas and optionally their tables. Keys are schema names."""
+ _, _, _ = database, include_tables, include_table_details
+ return []
+
def get_databases(
self,
*,
diff --git a/marimo/_sql/engines/redshift.py b/marimo/_sql/engines/redshift.py
index 4bf508b3bb..ff236418d8 100644
--- a/marimo/_sql/engines/redshift.py
+++ b/marimo/_sql/engines/redshift.py
@@ -199,7 +199,7 @@ class RedshiftEngine(SQLConnection["Connection"]):
schemas: list[Schema] = []
if include_schemas:
schemas = self.get_schemas(
- catalog=catalog,
+ database=catalog,
include_tables=include_tables,
include_table_details=include_table_details,
)
@@ -218,12 +218,19 @@ class RedshiftEngine(SQLConnection["Connection"]):
def get_schemas(
self,
*,
- catalog: str,
+ database: Optional[str],
include_tables: bool,
include_table_details: bool,
) -> list[Schema]:
"""Get schemas from the engine."""
+ # Redshift doesn't use the concept of databases, just catalogs and schemas.
+ catalog = database
+
+ if catalog is None:
+ # Early return to avoid passing None or "" as catalog
+ return []
+
output_schemas: list[Schema] = []
with self._connection.cursor() as cursor:
# get_schemas returns [["schema_name", "catalog"], ["schema_2", "catalog"]]
diff --git a/marimo/_sql/engines/sqlalchemy.py b/marimo/_sql/engines/sqlalchemy.py
index 92200c11a5..dd2163e00c 100644
--- a/marimo/_sql/engines/sqlalchemy.py
+++ b/marimo/_sql/engines/sqlalchemy.py
@@ -156,7 +156,7 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
# If database_name is None, the connection might be detached or invalid.
# We check for existing schemas to verify the connection's validity.
if database_name is None:
- schemas_found = self._get_schemas(
+ schemas_found = self.get_schemas(
database=None,
include_tables=False,
include_table_details=False,
@@ -210,7 +210,7 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
database_name = self.default_database
schemas = (
- self._get_schemas(
+ self.get_schemas(
database=database_name,
include_tables=self._resolve_should_auto_discover(
include_tables
@@ -232,7 +232,7 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
)
return databases
- def _get_schemas(
+ def get_schemas(
self,
*,
database: Optional[str],
diff --git a/marimo/_sql/engines/types.py b/marimo/_sql/engines/types.py
index e14921e8fb..0bc670ebb7 100644
--- a/marimo/_sql/engines/types.py
+++ b/marimo/_sql/engines/types.py
@@ -6,7 +6,7 @@ from dataclasses import dataclass
from typing import Any, Generic, Literal, Optional, TypeVar, Union
from marimo._config.config import SqlOutputType
-from marimo._data.models import Database, DataTable
+from marimo._data.models import Database, DataTable, Schema
from marimo._dependencies.dependencies import DependencyManager
from marimo._runtime.context.types import (
ContextNotInitializedError,
@@ -110,6 +110,17 @@ class EngineCatalog(BaseEngine[CONN], ABC):
"""Return the databases for the engine."""
pass
+ @abstractmethod
+ def get_schemas(
+ self,
+ *,
+ database: Optional[str],
+ include_tables: bool,
+ include_table_details: bool,
+ ) -> list[Schema]:
+ """Return the schemas for a database in the engine."""
+ pass
+
@abstractmethod
def get_tables_in_schema(
self, *, schema: str, database: str, include_table_details: bool
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index cfe73fa037..e4fbdf7c06 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -2450,6 +2450,7 @@ components:
- $ref: '#/components/schemas/PreviewDatasetColumnCommand'
- $ref: '#/components/schemas/PreviewSQLTableCommand'
- $ref: '#/components/schemas/ListSQLTablesCommand'
+ - $ref: '#/components/schemas/ListSQLSchemasCommand'
- $ref: '#/components/schemas/ValidateSQLCommand'
- $ref: '#/components/schemas/ListDataSourceConnectionCommand'
- $ref: '#/components/schemas/StorageListEntriesCommand'
@@ -2474,6 +2475,7 @@ components:
invoke-function: '#/components/schemas/InvokeFunctionCommand'
list-data-source-connection: '#/components/schemas/ListDataSourceConnectionCommand'
list-secret-keys: '#/components/schemas/ListSecretKeysCommand'
+ list-sql-schemas: '#/components/schemas/ListSQLSchemasCommand'
list-sql-tables: '#/components/schemas/ListSQLTablesCommand'
model: '#/components/schemas/ModelCommand'
preview-dataset-column: '#/components/schemas/PreviewDatasetColumnCommand'
@@ -2559,6 +2561,7 @@ components:
- $ref: '#/components/schemas/DataColumnPreviewNotification'
- $ref: '#/components/schemas/SQLTablePreviewNotification'
- $ref: '#/components/schemas/SQLTableListPreviewNotification'
+ - $ref: '#/components/schemas/SQLSchemaListPreviewNotification'
- $ref: '#/components/schemas/DataSourceConnectionsNotification'
- $ref: '#/components/schemas/ValidateSQLResultNotification'
- $ref: '#/components/schemas/StorageNamespacesNotification'
@@ -2601,6 +2604,7 @@ components:
remove-ui-elements: '#/components/schemas/RemoveUIElementsNotification'
secret-keys-result: '#/components/schemas/SecretKeysResultNotification'
send-ui-element-message: '#/components/schemas/UIElementMessageNotification'
+ sql-schema-list-preview: '#/components/schemas/SQLSchemaListPreviewNotification'
sql-table-list-preview: '#/components/schemas/SQLTableListPreviewNotification'
sql-table-preview: '#/components/schemas/SQLTablePreviewNotification'
startup-logs: '#/components/schemas/StartupLogsNotification'
@@ -2699,6 +2703,43 @@ components:
- packages
title: ListPackagesResponse
type: object
+ ListSQLSchemasCommand:
+ description: "List schemas in an SQL database.\n\n Retrieves names of all\
+ \ schemas in a database. Used by the SQL editor for\n schema selection.\n\
+ \n Attributes:\n request_id: Unique identifier for this request.\n\
+ \ engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).\n \
+ \ database: Database to query."
+ properties:
+ database:
+ type: string
+ engine:
+ type: string
+ requestId:
+ type: string
+ type:
+ enum:
+ - list-sql-schemas
+ required:
+ - type
+ - requestId
+ - engine
+ - database
+ title: ListSQLSchemasCommand
+ type: object
+ ListSQLSchemasRequest:
+ properties:
+ database:
+ type: string
+ engine:
+ type: string
+ requestId:
+ type: string
+ required:
+ - requestId
+ - engine
+ - database
+ title: ListSQLSchemasRequest
+ type: object
ListSQLTablesCommand:
description: "List tables in an SQL schema.\n\n Retrieves names of all tables\
\ and views in a schema. Used by the SQL\n editor for table selection.\n\
@@ -4055,6 +4096,19 @@ components:
- watcher_on_save
title: RuntimeConfig
type: object
+ SQLDatabaseMetadata:
+ description: "SQL database metadata.\n\n Attributes:\n connection:\
+ \ Connection identifier.\n database: Database name."
+ properties:
+ connection:
+ type: string
+ database:
+ type: string
+ required:
+ - connection
+ - database
+ title: SQLDatabaseMetadata
+ type: object
SQLMetadata:
description: "SQL database and schema metadata.\n\n Attributes:\n \
\ connection: Connection identifier.\n database: Database name.\n \
@@ -4076,6 +4130,35 @@ components:
- schema
title: SQLMetadata
type: object
+ SQLSchemaListPreviewNotification:
+ description: "List of SQL schemas in a database.\n\n Attributes:\n \
+ \ request_id: Request ID this responds to.\n metadata: Database and\
+ \ schema metadata.\n schemas: Schemas in database.\n error:\
+ \ Error message if failed."
+ properties:
+ error:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
+ metadata:
+ $ref: '#/components/schemas/SQLDatabaseMetadata'
+ op:
+ enum:
+ - sql-schema-list-preview
+ request_id:
+ $ref: '#/components/schemas/RequestId'
+ schemas:
+ default: []
+ items:
+ $ref: '#/components/schemas/Schema'
+ type: array
+ required:
+ - op
+ - request_id
+ - metadata
+ title: SQLSchemaListPreviewNotification
+ type: object
SQLTableListPreviewNotification:
description: "List of SQL tables in a schema.\n\n Attributes:\n request_id:\
\ Request ID this responds to.\n metadata: Database and schema metadata.\n\
@@ -5690,6 +5773,26 @@ paths:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Broadcasts a datasource connection
+ /api/datasources/preview_sql_schema_list:
+ post:
+ parameters:
+ - in: header
+ name: Marimo-Session-Id
+ required: true
+ schema:
+ type: string
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ListSQLSchemasRequest'
+ responses:
+ 200:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SuccessResponse'
+ description: Preview a list of schemas in an SQL database
/api/datasources/preview_sql_table:
post:
parameters:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 75fd64ddec..82314ebeed 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -448,6 +448,47 @@ export interface paths {
patch?: never;
trace?: never;
};
+ "/api/datasources/preview_sql_schema_list": {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ get?: never;
+ put?: never;
+ post: {
+ parameters: {
+ query?: never;
+ header: {
+ "Marimo-Session-Id": string;
+ };
+ path?: never;
+ cookie?: never;
+ };
+ requestBody?: {
+ content: {
+ "application/json": components["schemas"]["ListSQLSchemasRequest"];
+ };
+ };
+ responses: {
+ /** @description Preview a list of schemas in an SQL database */
+ 200: {
+ headers: {
+ [name: string]: unknown;
+ };
+ content: {
+ "application/json": components["schemas"]["SuccessResponse"];
+ };
+ };
+ };
+ };
+ delete?: never;
+ options?: never;
+ head?: never;
+ patch?: never;
+ trace?: never;
+ };
"/api/datasources/preview_sql_table": {
parameters: {
query?: never;
@@ -4773,6 +4814,7 @@ export interface components {
| components["schemas"]["PreviewDatasetColumnCommand"]
| components["schemas"]["PreviewSQLTableCommand"]
| components["schemas"]["ListSQLTablesCommand"]
+ | components["schemas"]["ListSQLSchemasCommand"]
| components["schemas"]["ValidateSQLCommand"]
| components["schemas"]["ListDataSourceConnectionCommand"]
| components["schemas"]["StorageListEntriesCommand"]
@@ -4834,6 +4876,7 @@ export interface components {
| components["schemas"]["DataColumnPreviewNotification"]
| components["schemas"]["SQLTablePreviewNotification"]
| components["schemas"]["SQLTableListPreviewNotification"]
+ | components["schemas"]["SQLSchemaListPreviewNotification"]
| components["schemas"]["DataSourceConnectionsNotification"]
| components["schemas"]["ValidateSQLResultNotification"]
| components["schemas"]["StorageNamespacesNotification"]
@@ -4910,6 +4953,31 @@ export interface components {
ListPackagesResponse: {
packages: components["schemas"]["PackageDescription"][];
};
+ /**
+ * ListSQLSchemasCommand
+ * @description List schemas in an SQL database.
+ *
+ * Retrieves names of all schemas in a database. Used by the SQL editor for
+ * schema selection.
+ *
+ * Attributes:
+ * request_id: Unique identifier for this request.
+ * engine: SQL engine ('postgresql', 'mysql', 'duckdb', etc.).
+ * database: Database to query.
+ */
+ ListSQLSchemasCommand: {
+ database: string;
+ engine: string;
+ requestId: string;
+ /** @enum {unknown} */
+ type: "list-sql-schemas";
+ };
+ /** ListSQLSchemasRequest */
+ ListSQLSchemasRequest: {
+ database: string;
+ engine: string;
+ requestId: string;
+ };
/**
* ListSQLTablesCommand
* @description List tables in an SQL schema.
@@ -5732,6 +5800,18 @@ export interface components {
/** @enum {unknown} */
watcher_on_save: "autorun" | "lazy";
};
+ /**
+ * SQLDatabaseMetadata
+ * @description SQL database metadata.
+ *
+ * Attributes:
+ * connection: Connection identifier.
+ * database: Database name.
+ */
+ SQLDatabaseMetadata: {
+ connection: string;
+ database: string;
+ };
/**
* SQLMetadata
* @description SQL database and schema metadata.
@@ -5748,6 +5828,26 @@ export interface components {
/** @enum {unknown} */
type: "sql-metadata";
};
+ /**
+ * SQLSchemaListPreviewNotification
+ * @description List of SQL schemas in a database.
+ *
+ * Attributes:
+ * request_id: Request ID this responds to.
+ * metadata: Database and schema metadata.
+ * schemas: Schemas in database.
+ * error: Error message if failed.
+ */
+ SQLSchemaListPreviewNotification: {
+ /** @default null */
+ error?: string | null;
+ metadata: components["schemas"]["SQLDatabaseMetadata"];
+ /** @enum {unknown} */
+ op: "sql-schema-list-preview";
+ request_id: components["schemas"]["RequestId"];
+ /** @default [] */
+ schemas?: components["schemas"]["Schema"][];
+ };
/**
* SQLTableListPreviewNotification
* @description List of SQL tables in a schema.
diff --git a/scripts/generate_schemas.py b/scripts/generate_schemas.py
index fb51e90295..41fd223388 100755
--- a/scripts/generate_schemas.py
+++ b/scripts/generate_schemas.py
@@ -52,6 +52,7 @@ with app.setup:
o.DatasetsNotification,
o.SQLTablePreviewNotification,
o.SQLTableListPreviewNotification,
+ o.SQLSchemaListPreviewNotification,
o.DataColumnPreviewNotification,
o.DataSourceConnectionsNotification,
o.ValidateSQLResultNotification,
diff --git a/tests/_internal/snapshots/internal_api.txt b/tests/_internal/snapshots/internal_api.txt
index 13fdd6a742..d6c1cbe3f8 100644
--- a/tests/_internal/snapshots/internal_api.txt
+++ b/tests/_internal/snapshots/internal_api.txt
@@ -17,6 +17,7 @@ commands
InvokeFunctionCommand
ListDataSourceConnectionCommand
ListOrValue
+ ListSQLSchemasCommand
ListSQLTablesCommand
ListSecretKeysCommand
ModelCommand
@@ -87,6 +88,7 @@ notifications
ReloadNotification
RemoveUIElementsNotification
SQLMetadata
+ SQLSchemaListPreviewNotification
SQLTableListPreviewNotification
SQLTablePreviewNotification
SecretKeysResultNotification
diff --git a/tests/_runtime/test_runtime_datasets.py b/tests/_runtime/test_runtime_datasets.py
index 8c48f6c62a..992ead5caf 100644
--- a/tests/_runtime/test_runtime_datasets.py
+++ b/tests/_runtime/test_runtime_datasets.py
@@ -7,7 +7,9 @@ import pytest
from marimo._dependencies.dependencies import DependencyManager
from marimo._messaging.notification import (
DataSourceConnectionsNotification,
+ SQLDatabaseMetadata,
SQLMetadata,
+ SQLSchemaListPreviewNotification,
SQLTableListPreviewNotification,
SQLTablePreviewNotification,
ValidateSQLResultNotification,
@@ -15,6 +17,7 @@ from marimo._messaging.notification import (
from marimo._runtime.commands import (
ExecuteCellCommand,
ListDataSourceConnectionCommand,
+ ListSQLSchemasCommand,
ListSQLTablesCommand,
PreviewSQLTableCommand,
ValidateSQLCommand,
@@ -182,6 +185,103 @@ class TestPreviewSQLTable:
]
[email protected](not HAS_SQL, reason="SQL deps not available")
+class TestPreviewSQLSchemaList:
+ async def test_non_existent_engine(
+ self, mocked_kernel: MockedKernel
+ ) -> None:
+ k = mocked_kernel.k
+ stream = mocked_kernel.stream
+
+ preview_sql_schema_list_request = ListSQLSchemasCommand(
+ request_id=RequestId("0"),
+ engine=DUCKDB_CONN,
+ database="test",
+ )
+ await k.handle_message(preview_sql_schema_list_request)
+ preview_sql_schema_list_results = [
+ op
+ for op in stream.operations
+ if isinstance(op, SQLSchemaListPreviewNotification)
+ ]
+ assert preview_sql_schema_list_results == [
+ SQLSchemaListPreviewNotification(
+ request_id=RequestId("0"),
+ schemas=[],
+ error="Engine not found",
+ metadata=SQLDatabaseMetadata(
+ connection=DUCKDB_CONN, database="test"
+ ),
+ )
+ ]
+
+ async def test_catalog_engine(
+ self,
+ mocked_kernel: MockedKernel,
+ connection_requests: list[ExecuteCellCommand],
+ ) -> None:
+ k = mocked_kernel.k
+ stream = mocked_kernel.stream
+
+ await k.run(connection_requests)
+
+ preview_sql_schema_list_request = ListSQLSchemasCommand(
+ request_id=RequestId("0"),
+ engine=DUCKDB_CONN,
+ database="test",
+ )
+ await k.handle_message(preview_sql_schema_list_request)
+
+ preview_sql_schema_list_results = [
+ op
+ for op in stream.operations
+ if isinstance(op, SQLSchemaListPreviewNotification)
+ ]
+ assert preview_sql_schema_list_results == [
+ SQLSchemaListPreviewNotification(
+ request_id=RequestId("0"),
+ schemas=[],
+ error=None,
+ metadata=SQLDatabaseMetadata(
+ connection=DUCKDB_CONN, database="test"
+ ),
+ )
+ ]
+
+ async def test_query_engine(
+ self,
+ mocked_kernel: MockedKernel,
+ connection_requests: list[ExecuteCellCommand],
+ ) -> None:
+ k = mocked_kernel.k
+ stream = mocked_kernel.stream
+
+ await k.run(connection_requests)
+
+ preview_sql_schema_list_request = ListSQLSchemasCommand(
+ request_id=RequestId("0"),
+ engine=SQLITE_CONN,
+ database="test",
+ )
+ await k.handle_message(preview_sql_schema_list_request)
+
+ preview_sql_schema_list_results = [
+ op
+ for op in stream.operations
+ if isinstance(op, SQLSchemaListPreviewNotification)
+ ]
+ assert preview_sql_schema_list_results == [
+ SQLSchemaListPreviewNotification(
+ request_id=RequestId("0"),
+ schemas=[],
+ error="Connection does not support catalog operations",
+ metadata=SQLDatabaseMetadata(
+ connection=SQLITE_CONN, database="test"
+ ),
+ )
+ ]
+
+
@pytest.mark.skipif(not HAS_SQL, reason="SQL deps not available")
class TestPreviewSQLTableList:
async def test_non_existent_engine(
diff --git a/tests/_server/api/endpoints/test_datasources.py b/tests/_server/api/endpoints/test_datasources.py
index 4cb4514a3e..fb9fb167fb 100644
--- a/tests/_server/api/endpoints/test_datasources.py
+++ b/tests/_server/api/endpoints/test_datasources.py
@@ -50,6 +50,22 @@ def test_preview_sql_table(client: TestClient) -> None:
assert content["success"] is True
+@with_session(SESSION_ID)
+def test_preview_sql_schema_list(client: TestClient) -> None:
+ response = client.post(
+ "/api/datasources/preview_sql_schema_list",
+ headers=HEADERS,
+ json={
+ "requestId": "test_request_id",
+ "engine": "test_engine",
+ "database": "test_db",
+ },
+ )
+ assert response.status_code == 200, response.text
+ content = response.json()
+ assert content["success"] is True
+
+
@with_session(SESSION_ID)
def test_preview_sql_table_list(client: TestClient) -> None:
response = client.post(
@@ -108,6 +124,17 @@ def test_fails_in_read_mode(client: TestClient) -> None:
)
assert response.status_code == 401
+ response = client.post(
+ "/api/datasources/preview_sql_schema_list",
+ headers=HEADERS,
+ json={
+ "requestId": "test_request_id",
+ "engine": "test_engine",
+ "database": "test_db",
+ },
+ )
+ assert response.status_code == 401
+
response = client.post(
"/api/datasources/preview_sql_table_list",
headers=HEADERS,
diff --git a/tests/_session/state/test_session_view.py b/tests/_session/state/test_session_view.py
index 6ef7a7e359..6ddf4c6cb6 100644
--- a/tests/_session/state/test_session_view.py
+++ b/tests/_session/state/test_session_view.py
@@ -25,7 +25,9 @@ from marimo._messaging.notification import (
ModelLifecycleNotification,
ModelOpen,
ModelUpdate,
+ SQLDatabaseMetadata,
SQLMetadata,
+ SQLSchemaListPreviewNotification,
SQLTableListPreviewNotification,
SQLTablePreviewNotification,
StartupLogsNotification,
@@ -901,6 +903,49 @@ def test_add_sql_table_previews() -> None:
== 10
)
+ # Add sql schema preview list
+ session_view.add_raw_notification(
+ serialize_kernel_message(
+ SQLSchemaListPreviewNotification(
+ metadata=SQLDatabaseMetadata(
+ connection="connection1", database="db1"
+ ),
+ request_id=RequestId("request_id"),
+ schemas=[
+ Schema(
+ name="db1",
+ tables=[
+ DataTable(
+ name="table2",
+ source_type="connection",
+ source="db1",
+ num_rows=20,
+ num_columns=10,
+ variable_name=VariableName("var"),
+ columns=[],
+ )
+ ],
+ )
+ ],
+ )
+ )
+ )
+ assert session_view_connections[0].databases[0].schemas[0].tables == [
+ DataTable(
+ source_type="connection",
+ source="db1",
+ name="table2",
+ num_rows=20,
+ num_columns=10,
+ variable_name=VariableName("var"),
+ columns=[],
+ engine=None,
+ type="table",
+ primary_keys=None,
+ indexes=None,
+ )
+ ]
+
# Add sql table preview list
session_view.add_raw_notification(
serialize_kernel_message(
diff --git a/tests/_sql/test_connection_utils.py b/tests/_sql/test_connection_utils.py
index 69dd10e9b3..1dfdac7a5f 100644
--- a/tests/_sql/test_connection_utils.py
+++ b/tests/_sql/test_connection_utils.py
@@ -13,8 +13,9 @@ from marimo._data.models import (
DataTableColumn,
Schema,
)
-from marimo._messaging.notification import SQLMetadata
+from marimo._messaging.notification import SQLDatabaseMetadata, SQLMetadata
from marimo._sql.connection_utils import (
+ update_schema_list_in_connection,
update_table_in_connection,
update_table_list_in_connection,
)
@@ -199,6 +200,55 @@ class TestUpdateTableInConnection:
assert connections[0].databases[0].schemas[0].tables == original_tables
+class TestUpdateSchemaListInConnection:
+ """Tests for update_schema_list_in_connection function."""
+
+ def test_update_schema_list(self) -> None:
+ """Test updating a schema list in the hierarchy."""
+ connections = create_test_connections(num_schemas_per_db=3)
+
+ sql_db_metadata = SQLDatabaseMetadata(
+ connection="connection_0",
+ database="database_0",
+ )
+
+ # Create new schema list
+ new_schemas = [
+ Schema(name=f"new_schema_{i}", tables=[]) for i in range(5)
+ ]
+
+ update_schema_list_in_connection(
+ connections, sql_db_metadata, new_schemas
+ )
+
+ # Verify the update
+ target_database = connections[0].databases[0]
+ assert len(target_database.schemas) == 5
+ assert target_database.schemas[0].name == "new_schema_0"
+ assert target_database.schemas[4].name == "new_schema_4"
+
+ def test_update_schema_list_nonexistent_connection(self) -> None:
+ """Test updating a schema list in a non-existent connection."""
+ connections = create_test_connections(num_schemas_per_db=3)
+
+ sql_db_metadata = SQLDatabaseMetadata(
+ connection="nonexistent",
+ database="database_0",
+ )
+
+ new_schemas = [
+ Schema(name=f"new_schema_{i}", tables=[]) for i in range(5)
+ ]
+ original_count = len(connections[0].databases[0].schemas)
+
+ update_schema_list_in_connection(
+ connections, sql_db_metadata, new_schemas
+ )
+
+ # Verify nothing changed
+ assert len(connections[0].databases[0].schemas) == original_count
+
+
class TestUpdateTableListInConnection:
"""Tests for update_table_list_in_connection function."""
@@ -412,6 +462,43 @@ class TestPerformance:
# Early exit should be very fast
assert avg_time < 0.1, f"Performance too slow: {avg_time:.4f}ms"
+ def test_performance_update_schema_list(self) -> None:
+ """Benchmark update_schema_list_in_connection."""
+ connections = create_test_connections(
+ num_connections=5,
+ num_databases_per_conn=5,
+ num_schemas_per_db=10,
+ num_tables_per_schema=50,
+ )
+
+ sql_db_metadata = SQLDatabaseMetadata(
+ connection="connection_4",
+ database="database_4",
+ )
+
+ new_schemas = [
+ Schema(name=f"new_schema_{i}", tables=[]) for i in range(10)
+ ]
+
+ def update_func() -> None:
+ update_schema_list_in_connection(
+ connections, sql_db_metadata, new_schemas
+ )
+
+ avg_time, total_time = self._measure_performance(
+ update_func, iterations=1000
+ )
+
+ print(
+ f"\nUpdate schema list (5x5x10 = 250 schemas): "
+ f"{avg_time:.4f}ms avg, {total_time:.2f}ms total"
+ )
+
+ # Should be fast since we're just replacing a list reference
+ assert avg_time < TIME_THRESHOLD_SECONDS, (
+ f"Performance too slow: {avg_time:.4f}ms"
+ )
+
def test_performance_update_table_list(self) -> None:
"""Benchmark update_table_list_in_connection."""
connections = create_test_connections(
diff --git a/tests/_sql/test_ibis.py b/tests/_sql/test_ibis.py
index aef35a387e..eec2320880 100644
--- a/tests/_sql/test_ibis.py
+++ b/tests/_sql/test_ibis.py
@@ -457,7 +457,7 @@ def test_ibis_engine_get_schemas(ibis_backend: SQLBackend) -> None:
"""Test IbisEngine get_schemas method."""
var_name = VariableName("my_ibis")
engine = IbisEngine(ibis_backend, engine_name=var_name)
- schemas = engine._get_schemas(
+ schemas = engine.get_schemas(
database="memory",
include_tables=True,
include_table_details=True,
@@ -473,7 +473,7 @@ def test_ibis_engine_get_schemas(ibis_backend: SQLBackend) -> None:
assert schema == get_expected_schema("my_schema", "test2")
# Test with include_table_details false
- schemas = engine._get_schemas(
+ schemas = engine.get_schemas(
database="memory",
include_tables=True,
include_table_details=False,
@@ -489,7 +489,7 @@ def test_ibis_engine_get_schemas(ibis_backend: SQLBackend) -> None:
assert schema.tables[0] == expected_table
# Test with include_tables false
- schemas = engine._get_schemas(
+ schemas = engine.get_schemas(
database="memory",
include_tables=False,
include_table_details=True,
diff --git a/tests/_sql/test_sqlalchemy.py b/tests/_sql/test_sqlalchemy.py
index 1f4ed502f2..67dd50cc03 100644
--- a/tests/_sql/test_sqlalchemy.py
+++ b/tests/_sql/test_sqlalchemy.py
@@ -399,7 +399,7 @@ def test_sqlalchemy_engine_get_schemas(sqlite_engine: sa.Engine) -> None:
engine = SQLAlchemyEngine(
sqlite_engine, engine_name=VariableName("test_sqlite")
)
- schemas = engine._get_schemas(
+ schemas = engine.get_schemas(
database=UNUSED_DB_NAME,
include_tables=True,
include_table_details=True,
@@ -415,7 +415,7 @@ def test_sqlalchemy_engine_get_schemas(sqlite_engine: sa.Engine) -> None:
assert schema == get_expected_schema("my_schema", "test2")
# Test with include_table_details false
- schemas = engine._get_schemas(
+ schemas = engine.get_schemas(
database=UNUSED_DB_NAME,
include_tables=True,
include_table_details=False,
@@ -431,7 +431,7 @@ def test_sqlalchemy_engine_get_schemas(sqlite_engine: sa.Engine) -> None:
assert schema.tables[0] == expected_table
# Test with include_tables false
- schemas = engine._get_schemas(
+ schemas = engine.get_schemas(
database=UNUSED_DB_NAME,
include_tables=False,
include_table_details=True,