singlestoredb 1.0.4__py3-none-any.whl → 1.2.0__py3-none-any.whl

singlestoredb/fusion/handlers/workspace.py

@@ -15,7 +15,34 @@ from .utils import get_workspace_manager
 
 class ShowRegionsHandler(SQLHandler):
     """
-    SHOW REGIONS [ <like> ] [ <order-by> ] [ <limit> ];
+    SHOW REGIONS [ <like> ]
+        [ <order-by> ]
+        [ <limit> ];
+
+    Description
+    -----------
+    Returns a list of all the valid regions for the user.
+
+    Arguments
+    ---------
+    * ``<pattern>``: A pattern similar to SQL LIKE clause.
+      Uses ``%`` as the wildcard character.
+
+    Remarks
+    -------
+    * Use the ``LIKE`` clause to specify a pattern and return only the
+      regions that match the specified pattern.
+    * The ``LIMIT`` clause limits the number of results to the
+      specified number.
+    * Use the ``ORDER BY`` clause to sort the results by the specified
+      key. By default, the results are sorted in the ascending order.
+
+    Example
+    -------
+    The following command returns a list of all the regions in the US
+    and sorts the results in ascending order by their ``Name``::
+
+        SHOW REGIONS LIKE 'US%' ORDER BY Name;
 
     """
 
@@ -40,7 +67,40 @@ ShowRegionsHandler.register(overwrite=True)
 
 class ShowWorkspaceGroupsHandler(SQLHandler):
     """
-    SHOW WORKSPACE GROUPS [ <like> ] [ <extended> ] [ <order-by> ] [ <limit> ];
+    SHOW WORKSPACE GROUPS [ <like> ]
+        [ <extended> ] [ <order-by> ]
+        [ <limit> ];
+
+    Description
+    -----------
+    Displays information on workspace groups.
+
+    Arguments
+    ---------
+    * ``<pattern>``: A pattern similar to SQL LIKE clause.
+      Uses ``%`` as the wildcard character.
+
+    Remarks
+    -------
+    * Use the ``LIKE`` clause to specify a pattern and return only the
+      workspace groups that match the specified pattern.
+    * The ``LIMIT`` clause limits the number of results to the
+      specified number.
+    * Use the ``ORDER BY`` clause to sort the results by the specified
+      key. By default, the results are sorted in the ascending order.
+    * To return more information about the workspace groups, use the
+      ``EXTENDED`` clause.
+
+    Example
+    -------
+    The following command displays a list of workspace groups with names
+    that match the specified pattern::
+
+        SHOW WORKSPACE GROUPS LIKE 'Marketing%' EXTENDED ORDER BY Name;
+
+    See Also
+    --------
+    * ``SHOW WORKSPACES``
 
     """
 
@@ -81,7 +141,9 @@ ShowWorkspaceGroupsHandler.register(overwrite=True)
 
 class ShowWorkspacesHandler(SQLHandler):
     """
-    SHOW WORKSPACES [ in_group ] [ <like> ] [ <extended> ] [ <order-by> ] [ <limit> ];
+    SHOW WORKSPACES [ in_group ]
+        [ <like> ] [ <extended> ]
+        [ <order-by> ] [ <limit> ];
 
     # Workspace group
     in_group = IN GROUP { group_id | group_name }
@@ -92,6 +154,45 @@ class ShowWorkspacesHandler(SQLHandler):
     # Name of group
     group_name = '<group-name>'
 
+    Description
+    -----------
+    Displays information on workspaces in a workspace group.
+
+    Arguments
+    ---------
+    * ``<group_id>``: The ID of the workspace group that contains
+      the workspace.
+    * ``<group_name>``: The name of the workspace group that
+      contains the workspace.
+    * ``<pattern>``: A pattern similar to SQL LIKE clause.
+      Uses ``%`` as the wildcard character.
+
+    Remarks
+    -------
+    * The ``IN GROUP`` clause specifies the ID or the name of the
+      workspace group that contains the workspace.
+    * Use the ``LIKE`` clause to specify a pattern and return only
+      the workspaces that match the specified pattern.
+    * The ``LIMIT`` clause limits the number of results to the
+      specified number.
+    * Use the ``ORDER BY`` clause to sort the results by the
+      specified key. By default, the results are sorted in the
+      ascending order.
+    * To return more information about the workspaces, use the
+      ``EXTENDED`` clause.
+
+    Example
+    -------
+    The following command displays information on all the workspaces
+    in a workspace group named **wsg1** and sorts the results by
+    workspace name in the ascending order::
+
+        SHOW WORKSPACES IN GROUP 'wsg1' EXTENDED ORDER BY Name;
+
+    See Also
+    --------
+    * ``SHOW WORKSPACE GROUPS``
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
@@ -136,6 +237,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 +265,78 @@ 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
+    -----------
+    Creates a workspace group.
+
+    Arguments
+    ---------
+    * ``<group-name>``: The name of the workspace group.
+    * ``<region_id>`` or ``<region_name>``: The ID or the name of the region
+      in which the new workspace group is created.
+    * ``<password>``: The admin password of the workspace group.
+      The password must contain:
+        - At least 8 characters
+        - At least one uppercase character
+        - At least one lowercase character
+        - At least one number or special character
+    * ``<expiry_time>``: The timestamp of when the workspace group terminates.
+      Expiration time can be specified as a timestamp or duration.
+    * ``<ip_range>``: A list of allowed IP addresses or CIDR ranges.
+    * ``<backup_key_id>``: The KMS key ID associated with the backup bucket.
+    * ``<data_key_id>``: The KMS key ID associated with the data bucket.
+    * ``<day>:<hour>``: The day of the week (0-6) and the hour of the day
+      (0-23) when the engine updates are applied to the workspace group.
+
+    Remarks
+    -------
+    * Specify the ``IF NOT EXISTS`` clause to create a new workspace group only
+      if a workspace group with the specified name does not exist.
+    * If the ``WITH BACKUP BUCKET KMS KEY ID '<backup_key_id>'`` clause is
+      specified, Customer-Managed Encryption Keys (CMEK) encryption is enabled
+      for the data bucket of the workspace group.
+    * If the ``WITH DATA BUCKET KMS KEY ID '<data_key_id>'`` clause is specified,
+      CMEK encryption for the data bucket and Amazon Elastic Block Store (EBS)
+      volumes of the workspace group is enabled.
+    * To enable Smart Disaster Recovery (SmartDR) for the workspace group, specify
+      the WITH SMART DR clause. Refer to Smart Disaster Recovery (DR):
+      SmartDR for more information.
+    * To allow incoming traffic from any IP address, use the ``ALLOW ALL TRAFFIC``
+      clause.
+
+    Examples
+    --------
+    The following command creates a workspace group named wsg1 in the
+    US East 2 (Ohio) region::
+
+        CREATE WORKSPACE GROUP 'wsg1' IN REGION 'US East 2 (Ohio)';
+
+    The following command specifies additional workspace group configuration
+    options::
+
+        CREATE WORKSPACE GROUP 'wsg1'
+            IN REGION ID '93b61160-0000-1000-9000-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 +363,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
@@ -201,8 +389,13 @@ CreateWorkspaceGroupHandler.register(overwrite=True)
 
 class CreateWorkspaceHandler(SQLHandler):
     """
-    CREATE WORKSPACE [ if_not_exists ] workspace_name [ in_group ]
-        WITH SIZE size [ wait_on_active ];
+    CREATE WORKSPACE [ if_not_exists ] workspace_name
+        [ in_group ]
+        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,10 +415,63 @@ 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
+    -----------
+    Creates a new workspace. Refer to
+    `Creating and Using Workspaces <https://docs.singlestore.com/cloud/getting-started-with-singlestore-helios/about-workspaces/creating-and-using-workspaces/>`_
+    for more information.
+
+    Arguments
+    ---------
+    * ``<workspace_name>``: The name of the workspace.
+    * ``<group_id>`` or ``<group_name>``: The ID or name of the workspace group
+      in which the workspace is created.
+    * ``<workspace_size>``: The size of the workspace in workspace size notation,
+      for example "S-1".
+    * ``<suspend_time>``: The time (in seconds) after which the workspace is
+      suspended, according to the specified auto-suspend type.
+    * ``<multiplier>``: The multiplier for the persistent cache associated with
+      the workspace.
+
+    Remarks
+    -------
+    * Use the ``IF NOT EXISTS`` clause to create a new workspace only if a workspace
+      with the specified name does not exist.
+    * If the ``WITH CACHE CONFIG <multiplier>`` clause is specified, the cache
+      configuration multiplier is enabled for the workspace. It can have the
+      following values: 1, 2, or 4.
+    * The ``WAIT ON ACTIVE`` clause indicates that the execution is paused until this
+      workspace is in ACTIVE state.
+    * Specify the ``ENABLE KAI`` clause to enable SingleStore Kai and the MongoDB®
+      API for the workspace.
+
+    Example
+    -------
+    The following command creates a workspace named **examplews** in a workspace
+    group named **wsg1**::
+
+        CREATE WORKSPACE 'examplews' IN GROUP 'wsgroup1'
+            WITH SIZE 'S-00' WAIT ON ACTIVE;
+
+    See Also
+    --------
+    * ``CREATE WORKSPACE GROUP``
+
+    """  # noqa: E501
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         workspace_group = get_workspace_group(params)
@@ -238,8 +484,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'],
         )
 
@@ -251,7 +508,9 @@ CreateWorkspaceHandler.register(overwrite=True)
 
 class SuspendWorkspaceHandler(SQLHandler):
     """
-    SUSPEND WORKSPACE workspace [ in_group ] [ wait_on_suspended ];
+    SUSPEND WORKSPACE workspace
+        [ in_group ]
+        [ wait_on_suspended ];
 
     # Workspace
     workspace = { workspace_id | workspace_name }
@@ -274,7 +533,39 @@ class SuspendWorkspaceHandler(SQLHandler):
     # Wait for workspace to be suspended before continuing
     wait_on_suspended = WAIT ON SUSPENDED
 
-    """
+    Description
+    -----------
+    Suspends a workspace.
+
+    Refer to `Manage Workspaces <https://docs.singlestore.com/cloud/user-and-workspace-administration/manage-organizations/manage-workspaces/>`_
+    for more information.
+
+    Arguments
+    ---------
+    * ``<workspace-id>``: The ID of the workspace to suspend.
+    * ``<workspace-name>``: The name of the workspace to suspend.
+    * ``<group-id>``: The ID of the workspace group that contains
+      the workspace.
+    * ``<group-name>``: The name of the workspace group that
+      contains the workspace.
+
+    Remarks
+    -------
+    * Use the ``WAIT ON SUSPENDED`` clause to pause query execution
+      until the workspace is in the ``SUSPENDED`` state.
+
+    Example
+    -------
+    The following example suspends a workspace named examplews in
+    a workspace group named **wsg1**::
+
+        SUSPEND WORKSPACE 'examplews' IN GROUP 'wsg1';
+
+    See Also
+    --------
+    * ``RESUME WORKSPACE``
+
+    """  # noqa: E501
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         ws = get_workspace(params)
@@ -287,7 +578,10 @@ 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 +601,53 @@ 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
+    -----------
+    Resumes a workspace.
+
+    Refer to `Manage Workspaces <https://docs.singlestore.com/cloud/user-and-workspace-administration/manage-organizations/manage-workspaces/>`_
+    for more information.
+
+    Arguments
+    ---------
+    * ``<workspace-id>``: The ID of the workspace to resume.
+    * ``<workspace-name>``: The name of the workspace to resume.
+    * ``<group_id>``: The ID of the workspace group that contains
+      the workspace.
+    * ``<group_name>``: The name of the workspace group that
+      contains the workspace.
+
+    Remarks
+    -------
+    * Use the ``IN GROUP`` clause to specify the ID or name of the
+      workspace group that contains the workspace to resume.
+    * Use the ``WAIT ON RESUMED`` clause to pause query execution
+      until the workspace is in the ``RESUMED`` state.
+    * Specify the ``DISABLE AUTO SUSPEND`` clause to disable
+      auto-suspend for the resumed workspace.
+
+    Example
+    -------
+    The following example resumes a workspace with the specified ID
+    in a workspace group named **wsg1**::
+
+        RESUME WORKSPACE ID '93b61160-0000-1000-9000-977b8e2e3ee5'
+            IN GROUP 'wsg1';
+
+    """  # noqa: E501
 
     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
 
 
@@ -323,7 +656,10 @@ ResumeWorkspaceHandler.register(overwrite=True)
 
 class DropWorkspaceGroupHandler(SQLHandler):
     """
-    DROP WORKSPACE GROUP [ if_exists ] group [ wait_on_terminated ] [ force ];
+    DROP WORKSPACE GROUP [ if_exists ]
+        group
+        [ wait_on_terminated ]
+        [ force ];
 
     # Only run command if the workspace group exists
     if_exists = IF EXISTS
@@ -343,6 +679,35 @@ class DropWorkspaceGroupHandler(SQLHandler):
     # Should the workspace group be terminated even if it has workspaces?
     force = FORCE
 
+    Description
+    -----------
+    Deletes the specified workspace group.
+
+    Arguments
+    ---------
+    * ``<group_id>``: The ID of the workspace group to delete.
+    * ``<group_name>``: The name of the workspace group to delete.
+
+    Remarks
+    -------
+    * Specify the ``IF EXISTS`` clause to attempt the delete operation
+      only if a workspace group with the specified ID or name exists.
+    * Use the ``WAIT ON TERMINATED`` clause to pause query execution until
+      the workspace group is in the ``TERMINATED`` state.
+    * If the ``FORCE`` clause is specified, the workspace group is
+      terminated even if it contains workspaces.
+
+    Example
+    -------
+    The following command deletes a workspace group named **wsg1** even
+    if it contains workspaces::
+
+        DROP WORKSPACE GROUP 'wsg1' FORCE;
+
+    See Also
+    --------
+    * ``DROP WORKSPACE``
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
@@ -367,7 +732,10 @@ DropWorkspaceGroupHandler.register(overwrite=True)
 
 class DropWorkspaceHandler(SQLHandler):
     """
-    DROP WORKSPACE [ if_exists ] workspace [ in_group ] [ wait_on_terminated ];
+    DROP WORKSPACE [ if_exists ]
+        workspace
+        [ in_group ]
+        [ wait_on_terminated ];
 
     # Only drop workspace if it exists
     if_exists = IF EXISTS
@@ -393,6 +761,41 @@ class DropWorkspaceHandler(SQLHandler):
     # Wait for workspace to be terminated before continuing
     wait_on_terminated = WAIT ON TERMINATED
 
+    Description
+    -----------
+    Deletes a workspace.
+
+    Arguments
+    ---------
+    * ``<workspace-id>``: The ID of the workspace to delete.
+    * ``<workspace-name>``: The name of the workspace to delete.
+    * ``<group_id>``: The ID of the workspace group that contains
+      the workspace.
+    * ``<group_name>``: The name of the workspace group that
+      contains the workspace.
+
+    Remarks
+    -------
+    * Specify the ``IF EXISTS`` clause to attempt the delete operation
+      only if a workspace with the specified ID or name exists.
+    * Use the ``IN GROUP`` clause to specify the ID or name of the workspace
+      group that contains the workspace to delete.
+    * Use the ``WAIT ON TERMINATED`` clause to pause query execution until
+      the workspace is in the ``TERMINATED`` state.
+    * All databases attached to the workspace are detached when the
+      workspace is deleted (terminated).
+
+    Example
+    -------
+    The following example deletes a workspace named **examplews** in
+    a workspace group **wsg1**::
+
+        DROP WORKSPACE IF EXISTS 'examplews' IN GROUP 'wsg1';
+
+    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,31 @@ class ShowFusionCommandsHandler(SQLHandler):
     # LIKE pattern
     like = LIKE '<pattern>'
 
+    Description
+    -----------
+    Displays a list of all the Fusion commands.
+
+    Arguments
+    ---------
+    * `<pattern>``: A pattern similar to SQL LIKE clause. Uses ``%`` as
+      the wildcard character.
+
+    Remarks
+    -------
+    * Use the ``LIKE`` clause to specify a pattern and return only the
+      commands that match the specified pattern.
+
+    Example
+    -------
+    The following command returns all the Fusion commands that start
+    with 'SHOW'::
+
+        SHOW FUSION COMMANDS LIKE 'SHOW%'
+
+    See Also
+    --------
+    * ``SHOW FUSION HELP``
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[result.FusionSQLResult]:
@@ -128,7 +154,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 +174,21 @@ 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.
+
+    Arguments
+    ---------
+    * ``<command>``: A Fusion command.
+
+    Example
+    -------
+    The following command displays the grammar for the
+    ``CREATE WORKSPACE`` Fusion command::
+
+        SHOW FUSION GRAMMAR FOR 'CREATE WORKSPACE';
+
     """
 
     def run(self, params: Dict[str, Any]) -> Optional[result.FusionSQLResult]:
@@ -162,3 +203,47 @@ class ShowFusionGrammarHandler(SQLHandler):
 
 
 ShowFusionGrammarHandler.register()
+
+
+class ShowFusionHelpHandler(SQLHandler):
+    """
+    SHOW FUSION HELP for_command;
+
+    # Command to show help for
+    for_command = FOR '<command>'
+
+    Description
+    -----------
+    Displays the documentation for a Fusion command.
+
+    Arguments
+    ---------
+    * ``<command>``: A Fusion command.
+
+    Example
+    -------
+    The following command displays the documentation for
+    the ``CREATE WORKSPACE`` Fusion 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()