singlestoredb 1.0.3__cp38-abi3-win32.whl → 1.1.0__cp38-abi3-win32.whl

singlestoredb/fusion/handlers/workspace.py

@@ -17,6 +17,22 @@ class ShowRegionsHandler(SQLHandler):
     """
     SHOW REGIONS [ <like> ] [ <order-by> ] [ <limit> ];
 
+    Description
+    -----------
+    Show all available regions.
+
+    Remarks
+    -------
+    * ``LIKE`` specifies a pattern to match. ``%`` is a wildcard.
+    * ``ORDER BY`` specifies the column names to sort by.
+    * ``LIMIT`` indicates a maximum number of results to return.
+
+    Example
+    -------
+    Show all regions in the US::
+
+        SHOW REGIONS LIKE 'US%' ORDER BY Name;
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
@@ -42,6 +58,28 @@ class ShowWorkspaceGroupsHandler(SQLHandler):
     """
     SHOW WORKSPACE GROUPS [ <like> ] [ <extended> ] [ <order-by> ] [ <limit> ];
 
+    Description
+    -----------
+    Show workspace group information.
+
+    Remarks
+    -------
+    * ``LIKE`` specifies a pattern to match. ``%`` is a wildcard.
+    * ``EXTENDED`` indicates that extra workspace group information should
+      be returned in the result set.
+    * ``ORDER BY`` specifies the column names to sort by.
+    * ``LIMIT`` indicates a maximum number of results to return.
+
+    Example
+    -------
+    Display workspace groups that match a pattern incuding extended information::
+
+        SHOW WORKSPACE GROUPS LIKE 'Marketing%' EXTENDED ORDER BY Name;
+
+    See Also
+    --------
+    * SHOW WORKSPACES
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
@@ -92,6 +130,30 @@ class ShowWorkspacesHandler(SQLHandler):
     # Name of group
     group_name = '<group-name>'
 
+    Description
+    -----------
+    Show workspaces in a workspace group.
+
+    Remarks
+    -------
+    * ``IN GROUP`` specifies the workspace group to list workspaces for. If a
+      workspace group ID is specified, you should use ``IN GROUP ID``.
+    * ``LIKE`` specifies a pattern to match. ``%`` is a wildcard.
+    * ``EXTENDED`` indicates that extra workspace group information should
+      be returned in the result set.
+    * ``ORDER BY`` specifies the column names to sort by.
+    * ``LIMIT`` indicates a maximum number of results to return.
+
+    Example
+    -------
+    Display workspaces in a workspace group including extended information::
+
+        SHOW WORKSPACES IN GROUP 'My Group' EXTENDED ORDER BY Name;
+
+    See Also
+    --------
+    * SHOW WORKSPACE GROUPS
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
@@ -136,6 +198,11 @@ class CreateWorkspaceGroupHandler(SQLHandler):
         [ with_password ]
         [ expires_at ]
         [ with_firewall_ranges ]
+        [ with_backup_bucket_kms_key_id ]
+        [ with_data_bucket_kms_key_id ]
+        [ with_smart_dr ]
+        [ allow_all_traffic ]
+        [ with_update_window ]
     ;
 
     # Only create workspace group if it doesn't exist already
@@ -159,6 +226,60 @@ class CreateWorkspaceGroupHandler(SQLHandler):
     # Incoming IP ranges
     with_firewall_ranges = WITH FIREWALL RANGES '<ip-range>',...
 
+    # Backup bucket key
+    with_backup_bucket_kms_key_id = WITH BACKUP BUCKET KMS KEY ID '<key-id>'
+
+    # Data bucket key
+    with_data_bucket_kms_key_id = WITH DATA BUCKET KMS KEY ID '<key-id>'
+
+    # Smart DR
+    with_smart_dr = WITH SMART DR
+
+    # Allow all incoming traffic
+    allow_all_traffic = ALLOW ALL TRAFFIC
+
+    # Update window
+    with_update_window = WITH UPDATE WINDOW '<day>:<hour>'
+
+    Description
+    -----------
+    Create a workspace group.
+
+    Remarks
+    -------
+    * ``IF NOT EXISTS`` indicates that the creation of the workspace group
+      will only be attempted if a workspace group with that name doesn't
+      already exist.
+    * ``IN REGION`` specifies the region to create the workspace group in.
+      If a region ID is used, ``IN REGION ID`` should be used.
+    * ``EXPIRES AT`` specifies an expiration date/time or interval.
+    * ``WITH FIREWALL RANGES`` indicates IP ranges to allow access to the
+       workspace group.
+    * ``WITH BACKUP BUCKET KMS KEY ID`` is the key ID associated with the
+      backup bucket.
+    * ``WITH DATA BUCKET KMS KEY ID`` is the key ID associated with the
+      data bucket.
+    * ``WITH SMART DR`` enables smart disaster recovery.
+    * ``ALLOW ALL TRAFFIC`` allows all incoming traffic.
+    * ``WITH UPDATE WINDOW`` specifies tha day (0-6) and hour (0-23) of the
+      update window.
+
+    Examples
+    --------
+    Example 1: Create workspace group in US East 2 (Ohio)::
+
+        CREATE WORKSPACE GROUP 'My Group' IN REGION 'US East 2 (Ohio)';
+
+    Example 2: Create workspace group with region ID and accessible from anywhere::
+
+        CREATE WORKSPACE GROUP 'My Group'
+               IN REGION ID '93b61160-0cae-4e11-a5de-977b8e2e3ee5'
+               WITH FIREWALL RANGES '0.0.0.0/0';
+
+    See Also
+    --------
+    * SHOW WORKSPACE GROUPS
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
@@ -185,12 +306,22 @@ class CreateWorkspaceGroupHandler(SQLHandler):
         else:
             region_id = params['region_id']
 
+        with_update_window = None
+        if params['with_update_window']:
+            day, hour = params['with_update_window'].split(':', 1)
+            with_update_window = dict(day=int(day), hour=int(hour))
+
         manager.create_workspace_group(
             params['group_name'],
             region=region_id,
             admin_password=params['with_password'],
             expires_at=params['expires_at'],
             firewall_ranges=params['with_firewall_ranges'],
+            backup_bucket_kms_key_id=params['with_backup_bucket_kms_key_id'],
+            data_bucket_kms_key_id=params['with_data_bucket_kms_key_id'],
+            smart_dr=params['with_smart_dr'],
+            allow_all_traffic=params['allow_all_traffic'],
+            update_window=with_update_window,
         )
 
         return None
@@ -202,7 +333,8 @@ CreateWorkspaceGroupHandler.register(overwrite=True)
 class CreateWorkspaceHandler(SQLHandler):
     """
     CREATE WORKSPACE [ if_not_exists ] workspace_name [ in_group ]
-        WITH SIZE size [ wait_on_active ];
+        WITH SIZE size [ auto_suspend ] [ enable_kai ]
+        [ with_cache_config ] [ wait_on_active ];
 
     # Create workspace in workspace group
     in_group = IN GROUP { group_id | group_name }
@@ -222,9 +354,48 @@ class CreateWorkspaceHandler(SQLHandler):
     # Runtime size
     size = '<size>'
 
+    # Auto-suspend
+    auto_suspend = AUTO SUSPEND suspend_after_seconds SECONDS suspend_type
+    suspend_after_seconds = AFTER <integer>
+    suspend_type = WITH TYPE { IDLE | SCHEDULED | DISABLED }
+
+    # Enable Kai
+    enable_kai = ENABLE KAI
+
+    # Cache config
+    with_cache_config = WITH CACHE CONFIG <integer>
+
     # Wait for workspace to be active before continuing
     wait_on_active = WAIT ON ACTIVE
 
+    Description
+    -----------
+    Create a workspace in a workspace group.
+
+    Remarks
+    -------
+    * ``IF NOT EXISTS`` indicates that the creation of the workspace
+      will only be attempted if a workspace with that name doesn't
+      already exist.
+    * ``IN GROUP`` indicates the workspace group to create the workspace
+      in. If an ID is used, ``IN GROUP ID`` should be used.
+    * ``SIZE`` indicates a cluster size specification such as 'S-00'.
+    * ``WITH CACHE CONFIG`` specifies the multiplier for the persistent cache
+      associated with the workspace. It must be 1, 2, or 4.
+    * ``WAIT ON ACTIVE`` indicates that execution should be paused until
+      the workspace has reached the ACTIVE state.
+
+    Example
+    -------
+    Create a workspace group and wait until it is active::
+
+        CREATE WORKSPACE 'my-workspace' IN GROUP 'My Group'
+               WITH SIZE 'S-00' WAIT ON ACTIVE;
+
+    See Also
+    --------
+    * CREATE WORKSPACE GROUP
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
@@ -238,8 +409,19 @@ class CreateWorkspaceHandler(SQLHandler):
             except KeyError:
                 pass
 
+        auto_suspend = None
+        if params['auto_suspend']:
+            auto_suspend = dict(
+                suspend_after_seconds=params['auto_suspend'][0]['suspend_after_seconds'],
+                suspend_type=params['auto_suspend'][-1]['suspend_type'].upper(),
+            )
+
         workspace_group.create_workspace(
-            params['workspace_name'], size=params['size'],
+            params['workspace_name'],
+            size=params['size'],
+            auto_suspend=auto_suspend,
+            enable_kai=params['enable_kai'],
+            cache_config=params['with_cache_config'],
             wait_on_active=params['wait_on_active'],
         )
 
@@ -274,6 +456,21 @@ class SuspendWorkspaceHandler(SQLHandler):
     # Wait for workspace to be suspended before continuing
     wait_on_suspended = WAIT ON SUSPENDED
 
+    Description
+    -----------
+    Suspend a workspace.
+
+    Remarks
+    -------
+    * ``IN GROUP`` indicates the workspace group of the workspace.
+      If an ID is used, ``IN GROUP ID`` should be used.
+    * ``WAIT ON SUSPENDED`` indicates that execution should be paused until
+      the workspace has reached the SUSPENDED state.
+
+    See Also
+    --------
+    * RESUME WORKSPACE
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
@@ -287,7 +484,8 @@ SuspendWorkspaceHandler.register(overwrite=True)
 
 class ResumeWorkspaceHandler(SQLHandler):
     """
-    RESUME WORKSPACE workspace [ in_group ] [ wait_on_resumed ];
+    RESUME WORKSPACE workspace [ in_group ]
+        [ disable_auto_suspend ] [ wait_on_resumed ];
 
     # Workspace
     workspace = { workspace_id | workspace_name }
@@ -307,14 +505,31 @@ class ResumeWorkspaceHandler(SQLHandler):
     # Name of workspace group
     group_name = '<group-name>'
 
+    # Disable auto-suspend
+    disable_auto_suspend = DISABLE AUTO SUSPEND
+
     # Wait for workspace to be resumed before continuing
     wait_on_resumed = WAIT ON RESUMED
 
+    Description
+    -----------
+    Resume a workspace.
+
+    Remarks
+    -------
+    * ``IN GROUP`` indicates the workspace group of the workspace.
+      If an ID is used, ``IN GROUP ID`` should be used.
+    * ``WAIT ON RESUMED`` indicates that execution should be paused until
+      the workspace has reached the RESUMED state.
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         ws = get_workspace(params)
-        ws.resume(wait_on_resumed=params['wait_on_resumed'])
+        ws.resume(
+            wait_on_resumed=params['wait_on_resumed'],
+            disable_auto_suspend=params['disable_auto_suspend'],
+        )
         return None
 
 
@@ -343,6 +558,29 @@ class DropWorkspaceGroupHandler(SQLHandler):
     # Should the workspace group be terminated even if it has workspaces?
     force = FORCE
 
+    Description
+    -----------
+    Drop a workspace group.
+
+    Remarks
+    -------
+    * ``IF EXISTS`` indicates that the dropping of the workspace group should
+      only be attempted if a workspace group with the given name exists.
+    * ``WAIT ON TERMINATED`` specifies that execution should be paused
+      until the workspace group reaches the TERMINATED state.
+    * ``FORCE`` specifies that the workspace group should be terminated
+      even if it contains workspaces.
+
+    Example
+    -------
+    Drop a workspace group and all workspaces within it::
+
+        DROP WORKSPACE GROUP 'My Group' FORCE;
+
+    See Also
+    --------
+    * DROP WORKSPACE
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
@@ -393,6 +631,29 @@ class DropWorkspaceHandler(SQLHandler):
     # Wait for workspace to be terminated before continuing
     wait_on_terminated = WAIT ON TERMINATED
 
+    Description
+    -----------
+    Drop a workspace.
+
+    Remarks
+    -------
+    * ``IF EXISTS`` indicates that the dropping of the workspace should
+      only be attempted if a workspace with the given name exists.
+    * ``IN GROUP`` indicates the workspace group of the workspace.
+      If an ID is used, ``IN GROUP ID`` should be used.
+    * ``WAIT ON TERMINATED`` specifies that execution should be paused
+      until the workspace reaches the TERMINATED state.
+
+    Example
+    -------
+    Drop a workspace if it exists::
+
+        DROP WORKSPACE IF EXISTS 'my-workspace' IN GROUP 'My Group';
+
+    See Also
+    --------
+    * DROP WORKSPACE GROUP
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:

singlestoredb/fusion/registry.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 import re
+import sys
 from typing import Any
 from typing import Dict
 from typing import List
@@ -120,6 +121,20 @@ class ShowFusionCommandsHandler(SQLHandler):
     # LIKE pattern
     like = LIKE '<pattern>'
 
+    Description
+    -----------
+    Display all Fusion SQL commands.
+
+    Remarks
+    -------
+    * ``LIKE`` indicates a pattern of commands to display. ``%`` is a wildcard.
+
+    Example
+    -------
+    Display all commands starting with 'SHOW'::
+
+        SHOW FUSION COMMANDS LIKE 'SHOW%';
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[result.FusionSQLResult]:
@@ -128,7 +143,7 @@ class ShowFusionCommandsHandler(SQLHandler):
 
         data: List[Tuple[Any, ...]] = []
         for _, v in sorted(_handlers.items()):
-            data.append((v.help.lstrip(),))
+            data.append((v.syntax.lstrip(),))
 
         res.set_rows(data)
 
@@ -148,6 +163,20 @@ class ShowFusionGrammarHandler(SQLHandler):
     # Query to show grammar for
     for_query = FOR '<query>'
 
+    Description
+    -----------
+    Show the full grammar of a Fusion SQL command for a given query.
+
+    Remarks
+    -------
+    * ``<query>`` is a string containing a Fusion SQL command.
+
+    Example
+    -------
+    Display the full grammar of the ``CREATE WORKSPACE`` command::
+
+        SHOW FUSION GRAMMAR FOR 'CREATE WORKSPACE';
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[result.FusionSQLResult]:
@@ -162,3 +191,42 @@ class ShowFusionGrammarHandler(SQLHandler):
 
 
 ShowFusionGrammarHandler.register()
+
+
+class ShowFusionHelpHandler(SQLHandler):
+    """
+    SHOW FUSION HELP for_command;
+
+    # Command to show help for
+    for_command = FOR '<command>'
+
+    Description
+    -----------
+    Show the documentation for a Fusion SQL command.
+
+    Example
+    -------
+    Display the help for the ``CREATE WORKSPACE`` command::
+
+        SHOW FUSION HELP FOR 'CREATE WORKSPACE';
+
+    """
+
+    def run(self, params: Dict[str, Any]) -> Optional[result.FusionSQLResult]:
+        handler = get_handler(params['for_command'])
+        if handler is not None:
+            try:
+                from IPython.display import display
+                from IPython.display import Markdown
+                display(Markdown(handler.help))
+            except Exception:
+                print(handler.help)
+        else:
+            print(
+                f'No handler found for command \'{params["for_command"]}\'',
+                file=sys.stderr,
+            )
+        return None
+
+
+ShowFusionHelpHandler.register()

singlestoredb/http/connection.py

@@ -62,6 +62,7 @@ from ..utils.debug import log_query
 from ..utils.mogrify import mogrify
 from ..utils.results import Description
 from ..utils.results import format_results
+from ..utils.results import get_schema
 from ..utils.results import Result
 
 
@@ -333,6 +334,7 @@ class Cursor(connection.Cursor):
         self._row_idx: int = -1
         self._result_idx: int = -1
         self._descriptions: List[List[Description]] = []
+        self._schemas: List[Dict[str, Any]] = []
         self.arraysize: int = get_option('results.arraysize')
         self.rowcount: int = 0
         self.lastrowid: Optional[int] = None
@@ -355,6 +357,14 @@ class Cursor(connection.Cursor):
             return self._descriptions[self._result_idx]
         return None
 
+    @property
+    def _schema(self) -> Optional[Any]:
+        if not self._schemas:
+            return None
+        if self._result_idx >= 0 and self._result_idx < len(self._schemas):
+            return self._schemas[self._result_idx]
+        return None
+
     def _post(self, path: str, *args: Any, **kwargs: Any) -> requests.Response:
         """
         Invoke a POST request on the HTTP connection.
@@ -460,6 +470,7 @@ class Cursor(connection.Cursor):
             self._results_type = results_type
 
         self._descriptions.append(list(mgmt_res.description))
+        self._schemas.append(get_schema(self._results_type, list(mgmt_res.description)))
         self._results.append(list(mgmt_res.rows))
         self.rowcount = len(self._results[-1])
 
@@ -487,6 +498,7 @@ class Cursor(connection.Cursor):
         is_callproc: bool = False,
     ) -> int:
         self._descriptions = []
+        self._schemas = []
         self._results = []
         self._pymy_results = []
         self._row_idx = -1
@@ -571,6 +583,20 @@ class Cursor(connection.Cursor):
                     if isinstance(k, int):
                         http_converters[k] = v
 
+            # Make JSON a string for Arrow
+            if 'arrow' in self._results_type:
+                def json_to_str(x: Any) -> Optional[str]:
+                    if x is None:
+                        return None
+                    return json.dumps(x)
+                http_converters[245] = json_to_str
+
+            # Don't convert date/times in polars
+            elif 'polars' in self._results_type:
+                http_converters.pop(7, None)
+                http_converters.pop(10, None)
+                http_converters.pop(12, None)
+
             results = out['results']
 
             # Convert data to Python types
@@ -616,6 +642,7 @@ class Cursor(connection.Cursor):
                         )
                         pymy_res.append(PyMyField(col['name'], flags, charset))
                     self._descriptions.append(description)
+                    self._schemas.append(get_schema(self._results_type, description))
 
                     rows = convert_rows(result.get('rows', []), convs)
 
@@ -659,6 +686,7 @@ class Cursor(connection.Cursor):
         rowcount = 0
         if args is not None and len(args) > 0:
             description = []
+            schema = {}
             # Detect dataframes
             if hasattr(args, 'itertuples'):
                 argiter = args.itertuples(index=False)  # type: ignore
@@ -668,11 +696,14 @@ class Cursor(connection.Cursor):
                 self.execute(query, params)
                 if self._descriptions:
                     description = self._descriptions[-1]
+                if self._schemas:
+                    schema = self._schemas[-1]
                 if self._rows is not None:
                     results.append(self._rows)
                 rowcount += self.rowcount
             self._results = results
             self._descriptions = [description for _ in range(len(results))]
+            self._schemas = [schema for _ in range(len(results))]
         else:
             self.execute(query)
             rowcount += self.rowcount
@@ -721,6 +752,7 @@ class Cursor(connection.Cursor):
             self._results_type,
             self.description or [],
             out, single=True,
+            schema=self._schema,
         )
 
     def fetchmany(
@@ -752,7 +784,10 @@ class Cursor(connection.Cursor):
             size = max(int(size), 1)
         out = self._rows[self._row_idx:self._row_idx+size]
         self._row_idx += len(out)
-        return format_results(self._results_type, self.description or [], out)
+        return format_results(
+            self._results_type, self.description or [],
+            out, schema=self._schema,
+        )
 
     def fetchall(self) -> Result:
         """
@@ -774,7 +809,10 @@ class Cursor(connection.Cursor):
             return tuple()
         out = list(self._rows[self._row_idx:])
         self._row_idx = len(out)
-        return format_results(self._results_type, self.description or [], out)
+        return format_results(
+            self._results_type, self.description or [],
+            out, schema=self._schema,
+        )
 
     def nextset(self) -> Optional[bool]:
         """Skip to the next available result set."""

singlestoredb/management/utils.py

@@ -9,6 +9,7 @@ from typing import Any
 from typing import Callable
 from typing import Dict
 from typing import List
+from typing import Mapping
 from typing import Optional
 from typing import SupportsIndex
 from typing import TypeVar
@@ -282,3 +283,32 @@ def camel_to_snake(s: Optional[str]) -> Optional[str]:
     if out and out[0] == '_':
         return out[1:]
     return out
+
+
+def snake_to_camel_dict(
+    s: Optional[Mapping[str, Any]],
+    cap_first: bool = False,
+) -> Optional[Dict[str, Any]]:
+    """Convert snake-case keys to camel-case keys."""
+    if s is None:
+        return None
+    out = {}
+    for k, v in s.items():
+        if isinstance(s, Mapping):
+            out[str(snake_to_camel(k))] = snake_to_camel_dict(v, cap_first=cap_first)
+        else:
+            out[str(snake_to_camel(k))] = v
+    return out
+
+
+def camel_to_snake_dict(s: Optional[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Convert camel-case keys to snake-case keys."""
+    if s is None:
+        return None
+    out = {}
+    for k, v in s.items():
+        if isinstance(s, Mapping):
+            out[str(camel_to_snake(k))] = camel_to_snake_dict(v)
+        else:
+            out[str(camel_to_snake(k))] = v
+    return out