New backup and recovery approaches in Manticore Search
Published: 2023-03-08 11:05:19

Published: Mar 07, 2023

Hey there! We’ve got some great news to share with you about the Manticore’s backup tool we released recently as a part of [Manticore Search 6](https://manticoresearch.com/blog/manticore-search-6-0-0/). If you’re someone who values their data and wants to ensure its safety and security, then this is definitely something you’ll want to check out.

The tool is a game-changer when it comes to backing up your Manticore data. You no longer have to worry about losing important information due to system crashes or other unforeseen events. With the new tool, you can easily automate the backup process by adding it to your cron job. This means you can sit back and relax knowing that your data is protected.

## History
In the past, keeping your data safe was a tough task that required manual backups which were often time-consuming and prone to errors. Let’s recall how challenging it was.

**Manticore Search** offers support for two types of tables: `RT` (real-time) and `plain`. While both serve different purposes, it’s worth noting that backing up plain tables is relatively easy, whereas RT tables require a more nuanced approach.

### RT tables backup
You probably used to struggle with backing up **Manticore Search** data of RT tables for a long time, without any reliable tool to make the process seamless. If you’re curious, let me take you down memory lane and explain what the manual backup process used to entail:

- Firstly, it was important to stop **Manticore Search** and ensure that all the data had been properly flushed and that the program had exited correctly.
- Next, you had to locate the `data_dir / path` folders by referring to the Manticore config and copy all the data from it. This ensured that all data was saved and could be restored if necessary. It’s important to note that when dealing with large amounts of data, the backup process could take some time, resulting in downtime while the instance is stopped. However, this step is necessary to ensure the safety and availability of your data.
- Finally, you had to launch **Manticore Search** back.

Alternatively, you could to `set global maintenance=1` and then perform a backup or switch your app to a `_readonly` listener and ensure that any writes are halted.

### Plain tables backup
When you use plain tables in Manticore Search, the files on disk are only updated when you run the indexer or make updates to attributes via SQL query. This simple approach makes it easy to back up your index. While it’s not a difficult task, we still have plans to include it in the Backup Tool. You can stay tuned and follow updates by checking the related [issue](https://github.com/manticoresoftware/manticoresearch-backup/issues/48).

The new backup tool provides a significantly easier way to handle backups. With it, everything is streamlined and straightforward. You can even schedule regular backups, so you always have the latest version of your data at your fingertips, without any downtime or hassle.

## On the way to develop the backup tool
To develop the tool, we had to add extra features to our existing Manticore system: the `FREEZE` and `UNFREEZE` commands that play a crucial role in ensuring the consistency of your data during the backup process.

The `FREEZE` and `UNFREEZE` commands in **Manticore Search** work a bit differently than the traditional lock and unlock tables feature of **MySQL**. When using `FREEZE`, it stops flushing data to the disk, but still allows writing to the table and selecting updated data from it. It’s important to note that if the size of your RAM chunk grows beyond the `rt_mem_limit` threshold while performing a lengthy backup operation involving a lot of inserts, it can result in data being flushed to the disk. Only then will write operations be blocked until the flushing is complete. Nonetheless, this approach allows for a balance between locking the table entirely, maintaining data consistency, and ensuring database write availability while the table is frozen.

These features were essential for a reliable online backup solution. Without them, restoring your data could result in inconsistent or broken data, causing major headaches and costing you time and resources. To ensure proper backup logic, we start by FREEZING all tables. Next, we proceed to back up each table one by one and execute `UNFREEZE` after each backup. In addition, the tool has a protective measure that automatically executes `UNFREEZE` for all tables in the event that the process fails or is terminated by the user.

After ensuring that we had the necessary commands to safely implement logic for copying data, the next question arose – which programming language should we use to implement the tool? Our team had already decided to use PHP as our go-to language for the [Manticore Buddy project](https://manticoresearch.com/blog/manticoresearch-buddy-intro/). So, it was an easy decision for us to implement the data backup process using PHP:

- First of all, PHP provides greater flexibility compared to Bash, which is typically utilized for similar tools. This was crucial for our project’s specific requirements. For instance, it enables the usage of the tool in a Windows environment, which would not be possible with Bash.
- Secondly, and more importantly, we designed it in such a way that we could reuse the same code with the same level of flexibility in Manticore Buddy.

The Backup tool needs certain external modules, including compression. To simplify its usage, we statically compile PHP and include all extensions within it. This amalgamated entity is known as `manticore-executor`. Essentially, it’s like PHP but with everything included to run various Manticore Search PHP projects: Manticore Buddy and the backup tool. You can check out our story on the development of [Manticore Buddy and how we used PHP there](https://manticoresearch.com/blog/manticoresearch-buddy-challenges-and-solutions/).

This made it possible to use the tool not only from the command line but also as a new SQL command inside Manticore, using the same codebase.

Now, let’s learn how to backup your data by using CLI and SQL interfaces!

## manticore-backup - CLI flavour
The new backup tool was released in [Manticore 6](https://manticoresearch.com/blog/manticore-search-6-0-0/), so installing it is a breeze if you just follow the Manticore [installation guide](https://manticoresearch.com/install/) page.

Assuming that you have successfully installed the backup tool, you now should now have access to the `manticore-backup` executable. Let’s take a look at some real-life examples of how you can use the tool in your daily work. To begin, ensure that you have created a `/backup` folder to store all your backups. This folder will be used in all the examples that follow to illustrate how the tool works, but of course it doesn’t have to be exactly `/backup`, you can pick any path you want.

**Scenario 1**: you want to backup your entire Manticore instance:

```
manticore-backup --config=/etc/manticore/manticore.conf --backup-dir=/backup
```
**Scenario 2**: you want to backup only only a few tables:

```
manticore-backup --config=/etc/manticore/manticore.conf --backup-dir=/backup --tables=users,messages,products
```
Remember to back up your data regularly to ensure everything is secure. Furthermore, mirroring it to a different server or data center is advisable to ensure all data is available at all times.

Check the [backup help section](https://manual.manticoresearch.com/Securing_and_compacting_a_table/Backup_and_restore) for a deep dive into using the tool.

## How to use the SQL BACKUP command?
[Manticore 6](https://manticoresearch.com/blog/manticore-search-6-0-0/) also allows you to make backups using the SQL interface without installing anything or following special instructions. You can use the same approach discussed in the previous section to back up either the entire instance or specific tables.

For an entire instance backup, use this command:

```
BACKUP TO /backup
```
For specific tables backup, use this:

```
BACKUP TABLES users, messages, products TO /backup
```
Keep in mind that backing up a large amount of data can take some time. To avoid worrying about losing the connection to Manticore while running the BACKUP command, you can execute the query asynchronously. You will instantly receive a query ID and can check the backup process status later by sending the command `SHOW QUERIES`. Here’s an example:

```
BACKUP TO /backup OPTION async=1
```
It’s that simple!

Now, you may be wondering, _“What about restoring the backed-up data?”_

## Restore
We have successfully created a backup using two different methods, ensuring that your data is safe and secure. But how do you restore your data? Don’t worry, we’ve got you covered.

At the moment, `manticore-backup` only supports restoring the full backup while the Manticore Search daemon stopped, but we have in [plans](https://github.com/manticoresoftware/manticoresearch-backup/issues/58) adding restoration of individual tables as well.

Let’s assume that you backed up your data to `/backup` and the Backup tool created and stored all of your data in a folder named `backup-20230305121400`. You need to stop your Manticore Search instance, remove all data and configuration, and run the command:
 
```
manticore-backup --config=/etc/manticore/manticore.conf --backup-dir=/backup --restore=backup-20230305121400
```
If you still want to restore a specific table, you can use the [IMPORT TABLE](https://manual.manticoresearch.com/Data_creation_and_modification/Adding_data_from_external_storages/Adding_data_to_tables/Importing_table) in SQL mode. For example, if you have a table named `users` in your backup, you should just send a query like this:

```
IMPORT TABLE users FROM '/backup/backup-20230305121400/data/users'
```
You can find more information about `manticore-backup --restore` in the docs [here](https://manual.manticoresearch.com/Securing_and_compacting_a_table/Backup_and_restore#Restore) and about the `IMPORT` command [here](https://manual.manticoresearch.com/Data_creation_and_modification/Adding_data_from_external_storages/Adding_data_to_tables/Importing_table#Importing-table).

## Summary
When it comes to running things in a production environment, backing up your data is an absolute must-do. And now, with the help of `manticore-backup` and the `BACKUP` command, you can do it with ease.

To get started with the new backup tools, visit our [documentation](https://manual.manticoresearch.com/Securing_and_compacting_a_table/Backup_and_restore#Backup-and-restore). We are confident that you will love it! If you have any feature requests, please share them with us via [GitHub Issues](https://github.com/manticoresoftware/manticoresearch-backup).

Best regards, The Manticore Team ❤️