# ATTACH DATABASE

> **📝 Note**: Point in Time Recovery (PITR) is only available for Enterprise edition databases. This feature can be used through the `AT MILESTONE` and `AT TIME` options. For more information, refer to [SingleStore Helios Editions](https://docs.singlestore.com/cloud/getting-started-with-singlestore-helios/about-singlestore-helios/singlestore-helios-editions.md).

The `ATTACH DATABASE` command restores an unlimited storage database at a restore point and then brings the database online.

See [Permissions Matrix](https://docs.singlestore.com/cloud/reference/sql-reference/security-management-commands/permissions-matrix.md) for the permissions required to use this command.

## Syntax

```sql
ATTACH DATABASE remote_database_name [ON WORKSPACE `workspace_name`] [AT MILESTONE milestone_name | AT TIME attach_time]

```

## Arguments

## attach\_time

A `DATETIME` or `DATETIME(6)` literal.

## milestone\_name

A quoted string, which is the name of a milestone to restore to.

## workspace\_name

(Optional) Specifies the name of the target SingleStore Helios workspace where the database will be attached. The workspace name must be enclosed in backticks (`` ` ``).

## Remarks

* `AT TIME` attaches the database, with its contents restored to the specified point in time. The specified time may be a `DATETIME` or a `DATETIME(6)` literal. An error will be returned if you attempt to attach a database at time literal that is later than the time of the latest detach.`DATETIME` should be in the UTC format.
* If `AT MILESTONE` and `AT TIME` are not specified, the database is attached at the latest state where all information is available for committed transactions.
* You cannot specify both `AT MILESTONE` and `AT TIME`.
* Use `ON WORKSPACE workspace_name` only when the aggregator is not part of a workspace (e.g., a Master Aggregator) to specify the source workspace for the database.
* The database to attach must belong to the same workspace group as the target workspace.
* Attaching an unlimited storage database can be faster than restoring an equivalent local storage database. This is because an attach of an unlimited storage database does not copy all data to the workspace, as is the case with the restore of a local storage database. Note that after an unlimited storage database is attached, queries may be slower for some time until remote data is cached locally in the workspace.
* This command cannot be run on [system databases](https://docs.singlestore.com/cloud/reference/system-databases.md).

## Attaching a Dropped Database

The `ATTACH DROPPED DATABASE` command re-attaches a database that was previously dropped and needs to be restored in its previous state.

```sql
ATTACH [DROPPED] DATABASE remote_database_name [AS new_database_name] [AT MILESTONE milestone_name | AT TIME attach_time]
```

In some recovery or restore scenarios, when using PITR, the standard `ATTACH DATABASE ... AT TIME ...` command may fail if the database to be attached is no longer present in the system metadata.

```sql
ATTACH DATABASE db01;

```

```output

ERROR 2564 (HY000): No matching attach point found in metadata service. Check information_schema.MV_CLOUD_BRANCHES
```

You can query the information\_schema table `MV_CLOUD_BRANCHES` to find out which dropped databases are available for attachment and what their corresponding metadata is, for example, branches, states, or timestamps and then re-attach the available database:

```sql
SELECT * FROM information_schema.MV_CLOUD_BRANCHES WHERE database_name = 'db01';

```

```output

+------------+-----------------------------------------+--------------------------------------+---------------+-----------+---------------------------+-------------+-----------------+-----------------+-------------------------+--------------------+-------------+----------------+-------------+----------------------------+-----------------------+--------------------+-----------------------------------+----------------------------+--------------------+-------------+-----------------------------+------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------+
| ROW_NUMBER | STORAGE_ID                              | WORKSPACE_GROUP_ID                   | DATABASE_NAME | REGION    | LATEST_COMPUTE_ID         | ATTACH_TYPE | PREV_ROW_NUMBER | PREV_COMPUTE_ID | PREV_WORKSPACE_GROUP_ID | PREV_DATABASE_NAME | PREV_REGION | OLDEST_VERSION | END_VERSION | LATEST_VERSION_LOWER_BOUND | OLDEST_UNIX_TIMESTAMP | END_UNIX_TIMESTAMP | LATEST_UNIX_TIMESTAMP_LOWER_BOUND | LATEST_ATTACH_TIME         | ATTACH_SOURCE_TIME | IS_DETACHED | IS_ATTACHED_TO_THIS_COMPUTE | IS_DROPPED | IS_ATTACHABLE | ATTACH_SYNTAX                                                                                                                                                                    | ATTACH_MEMO | BRANCH_COMPUTE_HISTORY        |
+------------+-----------------------------------------+--------------------------------------+---------------+-----------+---------------------------+-------------+-----------------+-----------------+-------------------------+--------------------+-------------+----------------+-------------+----------------------------+-----------------------+--------------------+-----------------------------------+----------------------------+--------------------+-------------+-----------------------------+------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------+
|          7 | 3982638125115796877:6081038623377649045 | 4393076e-aeee-4a98-a834-2ed8193e1c2c | db01          | us-west-2 | 10077921659319494183:2002 | create      |            NULL | NULL            | NULL                    | NULL               | NULL        |              1 |     5242960 |                    5242929 |     1753383348.185387 |  1753383660.892483 |                 1753383571.216999 | 2025-07-24 18:55:45.012191 | NULL               |           1 |                           0 |          1 |             1 | ATTACH DROPPED DATABASE `db01` FROM WORKSPACE GROUP '4393076e-aeee-4a98-a834-2ed8193e1c2c' STORAGEID 3982638125115796877:6081038623377649045 COMPUTEID 10077921659319494183:2002 |             | ["10077921659319494183:2002"] |
+------------+-----------------------------------------+--------------------------------------+---------------+-----------+---------------------------+-------------+-----------------+-----------------+-------------------------+--------------------+-------------+----------------+-------------+----------------------------+-----------------------+--------------------+-----------------------------------+----------------------------+--------------------+-------------+-----------------------------+------------+---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------+

```

```sql
ATTACH DROPPED DATABASE db01;

```

```output

Query OK, 1 row affected (9.632 sec)
```

## Examples

```sql
ATTACH DATABASE db01;
```

```sql
ATTACH DATABASE db01 AT MILESTONE m01;
```

The following example uses the UTC timezone.

```sql
ATTACH DATABASE db01 AT TIME "2022-09-03 11:37:07";
```

## Attach a Database to a workspace

You can only attach a database to a workspace within a single workspace group.

A database cannot have more than one read-write attachment.

Databases with a large number of partitions cannot be attached to a small workspace. The engine automatically performs the following check: core count \* 8 >= total number of partitions.

Here is an example of the error message when the total number of partitions is greater: "*Creating or attaching a database with 32 total partitions to a workspace with 2 total cores is not supported. Please use a larger workspace.*"

To attach an existing database in the *read-write mode* to a workspace, connect to the target workspace and execute the following command:

```sql
ATTACH DATABASE db_name;
```

To attach an existing database to a workspace in the *read-only mode*, execute the following command:

```sql
ATTACH DATABASE db_name READ ONLY;
```

The *read-only mode* is mutually exclusive with the PITR options. Hence it cannot be combined with the PITR options like milestones or attach\_time. It always attaches to latest and always replicates changes from the writable attach of the database if such an attachment exists.

To attach an existing database to another workspace in the same workspace group, execute the following command:

```sql
ATTACH DATABASE db_name AS test_db ON WORKSPACE `workspace-1`;

```

where, `db_name` is a database in another workspace (`workspace-2`) that belongs to the same workspace group as `workspace-1`.

**Renaming a Database**

1. To rename an existing database, create a new database branch from the original database. This branch serves as a point-in-time copy, containing all data from the original database exactly as it existed at the moment of branching.
   ```sql
   ATTACH DATABASE x_db AS x_db_new_name;
   ```

2. After the branch is successfully created, you can detach or drop the original database.

3. Finally, rename the newly created branch to the original database name.

> **📝 Note**: `SHOW DATABASES` only lists the databases that are attached to the current workspace.

***

Modified at: June 16, 2026

Source: [/cloud/reference/sql-reference/operational-commands/attach-database/](https://docs.singlestore.com/cloud/reference/sql-reference/operational-commands/attach-database/)

(An index of the documentation is available at /llms.txt)