# Welcome! ## Welcome to Medis 2 Medis is a modern, delightful, and professional Redis GUI. It's designed and developed by Redis experts, making it trustworthy even in critical situations. ### Notable Features #### Support all key types Medis works great with strings, lists, hashes, sets, sorted sets, streams, and even some third-party modules like [RedisJSON](https://redis.com/modules/redis-json/). With the beautiful UI, users can manage all data delightfully. #### Command query Medis provides a query view to run arbitrary commands. It highlights keywords to make everything super clear. #### Tree view for key lists Medis follows conventions of Redis community, shows a tree view to category keys as you wish. #### High performance Medis is designed to work with millions of keys and fields without blocking servers. #### Alert mode Medis provides the alert mode to make sure you're safe when working with production databases. Every writeable command sent to servers will need your approval explicitly. #### Support JSON/MessagePack Medis recognizes different data formats automatically so don't worry if you are using MessagePack to reduce memory usage. #### SSH tunnel and SSL Medis allows you to connect to remote servers with SSH tunnel, and it works great with SSL mode. #### Dark mode Of course, Medis supports dark mode! ## Have a question? We are using GitHub to manage issues. Feel free to submit one on for feature requests and bug reports. Additionally, you can contact us via email: . # Key Browser Key Browser is used to browser keys of your Redis data store. ## Fold level There is a convention that we use the separator `:` in the key name to represent property relationships. For example, a key with name `users:4590:name` can be a key that stores the user name of the user whose id is 4590. Medis supports this convention out-of-box by making the name parts as the folder of the tree view: ![](/files/KUT0bJf2KNuBOGMU5yYU) By default, we only show the first part as folders. However, you can configure this on the preference window: In the screenshot above, we set the "Max fold level" to 3, and the key list will look like: ![](/files/Hs79aQufcj7Ak9H8B9LH) # Command Query Command query window provides a redis-cli like interface for you to interact with Redis server with Redis commands. ![Command query window](/files/Vtlq2PkMJNNnlVJg41mZ) ## Basic usage Within the command input text view, users can enter any valid Redis command. Multiple commands may be entered, separated by newline characters (`\n`), unless they are enclosed within quotes. Clicking the "Execute Selected" button will execute the Redis command contained within the current line where the caret is positioned. Users may also execute multiple commands by selecting a range of lines that contain these commands. The commands that are about to be sent to the Redis server will be highlighted with a subtle gray background. Command names are case-insensitive. ## Command colors Read-only Redis commands, which will not modify the Redis database, are displayed in orange within the input text view. On the other hand, Redis commands that modify the database will be displayed in blue. ## Quote Encoding Arguments of a command are separated by whitespaces (spaces or `\t`). Sometimes you may want to include these separators in the argument. If that's the case, you can use `"` or `'` to wrap the argument. For example: ``` set keyname "content that contains a space" set keyname 'content that contains a space' ``` Backslashes (`\`) can be used to "protect" quotes if the arguments contain quotes: ``` set keyname "content that contains both spaces \"and\" quotes" ``` Additionally, you can use `\n` to insert newlines when the content is wrapped with double quotes: ``` set keyname "content that contains a \n newline" ``` Similarly, use backslashes to "protect" backslashes: ``` set keyname "content that contains a \\" ``` ## Multiline Command Use quotes (`"` or `'`) to wrap an argument across multiple lines: ``` eval " local a = 1 local b = 2 return a + b " 0 ``` # Custom URL Scheme Medis supports `medis:` and `mediss:` URLs for quickly opening Redis connections. For example, `medis://localhost:6379` will open Medis and connect to the server at `localhost` on port `6379`. You can specify the database index via the path. For example, to switch to database 2, you would use `medis://localhost:6379/2`. Username and password are also supported. Use `medis://username:password@localhost:6379` to include both username and password, or simply `medis://password@localhost:6379` if you want to omit the username. `mediss:` is similar to `medis:`, but it enables SSL for a secure connection. # Custom Encoders Medis offers a range of built-in encoders, including MessagePack, Gzip, and PHP, which can convert the data stored in the database into a human-readable format. Furthermore, you have the option to create and use your own custom encoders. A custom encoder is an executable shell script that communicates with Medis via standard input and output. ## API The API utilizes standard input and output. All content are encoded in [Base64](https://en.wikipedia.org/wiki/Base64) before sending to deal with binary data. ### Decode When Medis opens a string key or the content field of a hash/set/zset/list... key, and the user selects a custom encoder, Medis will encode the content in Base64 and send to the encoder script via the standard input and pass `decode` parameter. The process is effectively similar to: ``` echo -n "-17" | base64 | ./encoder_Reverse.sh decode ``` Where `encoder_Reverse.sh` is a custom encoder. ### Encode Similarly, when the content is going to be saved to the database, Medis calls the custom encoder to encode the content with `encode` parameter. ## Implement a Custom Encoder In this section, we are going to demostrate how to implement a simple custom encoder that reverses the input. ### Create a New File All custom encoders need to be placed in a specific folder so Medis can find them. You can open the folder from Settings -> Encoder -> Open Encoder Folder. ![](/files/vDzymixix6q9SvhYAy2P) Create a new file `encoder_Reverse.sh` inside the folder. It's worth noticing that the file name of custom encoders need to start with `encoder_`, otherwise they will be ignored. ### Coding Paste the following content into the file: ``` #!/bin/bash # Set correct exit code when any commands fail so Medis can tell # the user. set -e set -o pipefail if [ $1 = "decode" ]; then # Get input from stdin input=$(cat) # Decode Base64 decoded=$( base64 -d <<< $input ) # Reverse the input reversed=$( echo -n $decoded | rev) # Encode in Base64 echo -n $( echo -n $reversed | base64 ) elif [ $1 = "encode" ]; then echo "Encode not implemented!" 1>&2 exit 1 fi ``` {% hint style="info" %} Make sure the output doesn't have newline chars. That's the reason we use `echo -n`. {% endhint %} The first [shebang](https://en.wikipedia.org/wiki/Shebang_\(Unix\)) line is required so Medis can know how to run the script. It's possible to write the encoder in different languages as long as it has the correct shebang. For example, if you want to use Node.js, name the file with `encoder_Reverse.js`, and change the first line to: ``` #!/usr/local/bin/node ``` {% hint style="info" %} The shell script doesn't run your .bash\_rc file so make sure you provide the absolute path instead of **`#!/usr/bin/env node`**. {% endhint %} ### Enable the Encoder Then, add the executable permission to the script with `chmod +x encoder_Reverse.sh`. Then go to the encode setting panel and make sure our new encoder is enabled (you may need to click on the refresh button to see the encoder). That's it! You can open a string key and select our new encoder. The content will get reversed. However, if we make some changes and save the content, Medis shows an error alert because we raise an error in the script when the parameter is `encode`. I will let you finish the script. For this encoder, encode and decode do the same thing, but other encoders may not. # Content Rules By default, Medis attempts to select the most suitable encoder and viewer based on the content of the key. However, in certain scenarios, this automatic detection may fail. Additionally, the automatic detection does not take custom encoders into consideration, primarily due to performance constraints. To address these limitations, Medis allows users to configure explicit content rules for encoders and viewers, based on the key name or type. This enables users to customize the encoding and decoding process, ensuring that the appropriate encoder and viewer are used for each key. ## Create a New Rule To create a new rule, open the connection config modal and select the content rules tab. ![](/files/QmFsZbAWtzkoQEjESq4m) Click the + button to create a new rule. ![](/files/gW7OlAbn0fmhts2GK8Ni) #### When There are two conditions, and only when the two conditions are satisfied at the same time, the preferred viewer and encoder will apply. If the key name pattern is left empty, all key names pass the condition. The key name pattern supports glob rules like `*` and `?`. #### Then You can set either viewer or encoder or both of them. "Auto" is Medis's default behavior. For Hash/List/Set/Sorted Set keys, the viewer/encoder will be applied to their fields. # Custom SSH Config Due to the restrictions imposed by Apple sandbox, Medis does not utilize the SSH configuration file located at `~/.ssh/config` by default. This sandbox mechanism is intended to safeguard user files, and it restricts application access to only those files that the user has explicitly authorized within the program. In the event that the user has not explicitly selected their SSH configuration file, Medis will default to using an empty SSH configuration file. However, users have the option to specify their SSH configuration file within the application preferences. ![](/files/SsW1aMQ9PyquobRhyHj8) Please note that if you are using the App Store version of Medis, you must also grant the application access to any files that are required by your SSH configuration, such as identity files. This can be done using the "+" button located below the relevant file. # Language Settings Medis currently offers interface options in the following languages: * English * Simplified Chinese. We are progressively expanding our multilingual support, prioritizing additional languages based on user feedback. By default, Medis aligns with your system's language. Consequently, if your device is set to English, Medis will display its interface in English. In instances where your system's language is unsupported, Medis will default to English. ## Change Language You can override language setting for Medis specifically to make it show in a different language. 1. Open macOS system settings. 2. Find General -> Language & Region. 3. Click "+" button under "Applications" section (see the screenshot below).
4. Pick "Medis" in the application selector, and choose the language you want Medis to show in (see the screenshot below).
5. Quit and re-open Medis to apply the change. {% hint style="info" %} The system settings window might look different depending on your macOS version. If you are using an older version of macOS, your system settings may look like the screenshot below. In that case, you need to the "Apps" tab (highlighted in the red box). ![](/files/3clbkoqCVZuJH6M211PE) {% endhint %} # Delete Confirmation Dialog To avoid inadvertent deletion of keys, Medis, by default, presents a confirmation dialog when a key deletion is initiated via the GUI. While this feature is useful, it can slightly hinder the speed of your workflow in a development environment. Here's how you can improve this: ## Enable Shortcut

Delete Confirmation Dialog

In macOS's default setting, users have to click the delete button explicitly to confirm the deletion. However, you can enable the shortcut to move the focus from the "Cancel" button to "Delete" button so that you can confirm the deletion with your keyboard. To enable this feature, open System Settings, navigate to Keyboard panel, and enable "Keyboard navigation".
Once this shortcut is enabled, you can rely on the Tab key to shift focus to the Delete button, and the Enter key to authenticate the deletion. ## Disable Confirmation Dialog Medis also offers an option to deactivate the confirmation dialog for each separate connection, reducing the steps for key deletion. You can modify this setting by accessing the connection setting found in the toolbar.
In the setting window, uncheck the Delete confirmation checkbox:
This modification only applies to the current connection, preserving the delete confirmations for other connections. # Default Database Medis provides the option to assign a default database for each individual connection in the connection settings.
When you set a default database, Medis will automatically switch to that particular database upon server connection, rather than defaulting to the database with an index of 0. # DigitalOcean To connect to a Redis database managed by DigitalOcean, you can obtain the connection details from the database page: ![Database Page](/files/GCzFvcGsqPsGNPuW0OWa) Then put all the details in the config form. Make sure that the SSL mode is enabled: ![](/files/RsHGwuOKSEN14FWMvV1I) # Upstash Redis Upstash Redis provides a fully managed highly available Redis compatible database. ## Create a Database To create a database, you need to go to the [Upstash Console](https://console.upstash.com/redis?new=true\&ref=medis) and enter a name for your database. You can also choose the regions where you want to create your database.
## Connect to the Database Once you have created a database, you can connect to it using the `Endpoint`, `Port` and `Password`. You can find them in the database details page.
## Connect to the Database using Medis Lastly open Medis and click on the `New Server` button. Enter the `Host`, `Port` and `Password`, but leave the `Username` empty. If you have enabled `TLS (SSL)` on your database, you need to enable it in Medis as well.
\
# Cluster Redis Cluster provides a way to run a Redis installation where data is automatically sharded across multiple Redis nodes. A client that connects to a cluster handles command redirections and talks to each node in the cluster directly. Medis supports Redis Cluster out of the box. To connect to a cluster, fill in the host address and port number of any node in the cluster in the connection settings modal. You can also enable SSL mode and fill in the username and password if they are required. ![](/files/7AnCVi3H5rlIwIlm3a93) Once connected, Medis will discover other nodes in the cluster automatically and dispatch commands to the correct node by calculating the slot of keys. ## Caveats At the moment, commands invoked in the command query view will be sent to a random node in the cluster. # AWS ElastiCache AWS ElastiCache offers support for Redis, and you can manage these Redis instances using Medis. Medis is compatible with both cluster mode and non-cluster mode. For the purpose of this tutorial, we will focus on cluster mode, but most aspects are applicable to non-cluster mode as well. ## Accessing ElastiCache from Outside Your VPC To access ElastiCache from outside your VPC, you have two options: 1. Utilize an EC2 instance as an SSH jump server. 2. Set up a VPN. In this tutorial, we will demonstrate how to connect to a Redis cluster using an SSH jump server. ## Ensure Connectivity To verify connectivity, follow these steps: 1. SSH into your EC2 instance. 2. Ping your ElastiCache endpoint to ensure that your Redis instances are accessible from the EC2 instance. If the connection is unsuccessful, review your security group settings. For the endpoint address of your ElastiCache, you can either use the "Configuration endpoint" or the endpoint of one of the shard nodes. Medis will auto discover all nodes in the cluster:
## Create Connection Now open Medis and create a connection. Select "Cluster via SSH Tunnel" as the mode, and fill "SSH host" with the public address of your EC2 instance, and "User" with your EC2 user name. Make sure to select the key file associated with your EC2 instance. Fill "Host" with the endpoint of your ElastiCache and make sure "Port" is correct.
Click "Save" when everything looks good. Now you can connect to your Redis cluster from Medis! # Amazon MemoryDB for Redis Similar to AWS ElastiCache, Amazon MemoryDB for Redis is a database service that is compatible to Redis and Medis supports it out-of-the-box. Follow the guide of [connecting to AWS ElastiCache](/connect-to-your-database/aws-elasticache), you should be able to connect to Amazon MemoryDB for Redis with a similar process. ## Connect with a VPN If you've set a VPN and you are able to connect to your Amazon MemoryDB for Redis directly from your local machine, all you need to do is to select the "Cluster" mode in Medis and fill the Cluster endpoint that you can find in the Cluster details page in to the Host field.

Find your cluster endpoint

Select "Cluster" mode and make sure SSL is enabled

# 1Password SSH agent Medis officially supports the [1Password SSH agent](https://developer.1password.com/docs/ssh/agent/), enabling you to manage all your SSH secrets conveniently in one location. {% hint style="info" %} Please note that due to Apple's sandbox restrictions, only Medis versions downloaded from the [official website](https://getmedis.com/) support this feature. Do not hesitate to contact us if you require further assistance. {% endhint %} To configure the integration of Medis with 1Password, follow these steps: ## Update SSH Config Configure the 1Password SSH agent in your SSH config file by referring to [1Password's SSH Configuration Guide](https://developer.1password.com/docs/ssh/get-started/#step-4-configure-your-ssh-or-git-client) and adding the following: ``` Host * IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" ``` to your `~/.ssh/config`. ## Configuring Medis to Use SSH Configuration

SSH panel of Medis settings

1. Open "Settings..." in Medis 2. Switch to the SSH panel 3. Add your SSH config file so Medis can adhere to the. desired configurations ## Configuring Medis Connection Once the above steps are completed, Medis can utilize the 1Password SSH agent for your connections that have SSH tunnel enabled. Here's an example of what a typical setup might look like:
When establishing a connection, 1Password will prompt you for SSH key approval as follows: